README

A powerful yet lightweight PHP library for creating dynamic JSON with loops, conditionals, functions, variables, and pattern matching. Think of it as a feature-rich templating engine specifically designed for JSON generation.

🚀 Features

Variable Interpolation: Use {{variable}} syntax with dot notation for nested access
Template Functions: 30+ built-in functions (upper, lower, date, round, join, etc.)
Arithmetic Operations: Perform calculations with @set directive
Loops: Iterate over arrays with @djson for directive
Conditionals: Include/exclude content with @djson if, @djson unless, @djson exists
Pattern Matching: Switch/case logic with @djson match and @djson switch
Variable Assignment: Set and calculate values with @djson set
Else Statements: Full conditional logic with @djson else
Loop Helpers: Access _index, _key, _first, _last in loops
Type Preservation: Maintains data types (numbers, booleans, null)
Error Handling: Comprehensive validation with detailed error messages
PHP 8.1+: Modern PHP with constructor property promotion

📚 Full Documentation: https://djson.dev

Installation

composer require qoliber/djson

Quick Start

use Qoliber\DJson\DJson;

$djson = new DJson();

$template = [
    'greeting' => 'Hello {{name | upper}}!',
    'users' => [
        '@djson for users as user',
        'name' => '{{user.name}}',
        'email' => '{{user.email}}'
    ]
];

$data = [
    'name' => 'world',
    'users' => [
        ['name' => 'John', 'email' => 'john@example.com'],
        ['name' => 'Jane', 'email' => 'jane@example.com']
    ]
];

$result = $djson->process($template, $data);
// ['greeting' => 'Hello WORLD!', 'users' => [...]]

Core Features

Variable Interpolation with Functions

$template = [
    'title' => '{{product.name | upper}}',
    'price' => '{{product.price | number_format(2)}}',
    'date' => '{{timestamp | date("Y-m-d")}}'
];

Loops with Special Variables

$template = [
    'items' => [
        '@djson for products as product',
        'position' => '{{_index}}',        // Current index
        'isFirst' => '{{_first}}',         // true if first item
        'isLast' => '{{_last}}',           // true if last item
        'name' => '{{product.name}}'
    ]
];

Conditionals with Else

$template = [
    '@djson if user.isPremium',
    'status' => 'Premium Member',
    '@djson else',
    'status' => 'Free User'
];

Pattern Matching (Switch/Case)

$template = [
    '@djson match status',
    '@djson case active',
    'message' => 'User is active',
    '@djson case pending',
    'message' => 'Awaiting approval',
    '@djson default',
    'message' => 'Status unknown'
];

Arithmetic Operations

$template = [
    '@djson set total = price * quantity',
    '@djson set discount = total * 0.1',
    '@djson set final = total - discount',
    'finalPrice' => '{{final | number_format(2)}}'
];

Conditional Expressions

$template = [
    '@djson if stock > 0',
    'available' => true,
    '@djson unless stock < 10',
    'lowStock' => false
];

Built-in Template Functions

String Functions

upper, lower, capitalize, title
trim, escape, slug
substr, replace

Number Functions

number_format, round, ceil, floor, abs

Array Functions

count, first, last, join, sort, unique

Date Functions

date, strtotime

Utility Functions

default, coalesce
json_encode

See full function documentation at djson.dev/functions

Advanced Examples

E-commerce Product with Calculations

$template = [
    'product' => '{{name}}',
    '@djson set subtotal = price * quantity',
    '@djson set tax = subtotal * 0.2',
    '@djson set total = subtotal + tax',
    'pricing' => [
        'subtotal' => '{{subtotal | number_format(2)}}',
        'tax' => '{{tax | number_format(2)}}',
        'total' => '{{total | number_format(2)}}'
    ]
];

Complex Conditional Logic

$template = [
    '@djson match userType',
    '@djson case admin',
    'permissions' => ['read', 'write', 'delete'],
    '@djson case editor',
    'permissions' => ['read', 'write'],
    '@djson case viewer',
    'permissions' => ['read'],
    '@djson default',
    'permissions' => []
];

For more examples, visit djson.dev/examples

Testing

DJson has comprehensive test coverage with 100% mutation score:

composer install
./vendor/bin/phpunit

Test Results:

✅ 103 tests, 385 assertions
🏆 100% mutation score (70/70 meaningful mutations killed)
⚡ Rock-solid quality assurance

API Reference

Core Methods

// Process array/JSON template, return array
$result = $djson->process($template, $data);

// Process and return JSON string
$json = $djson->processToJson($template, $data, JSON_PRETTY_PRINT);

// Load from file, return array
$result = $djson->processFile('template.json', $data);

// Load from file, return JSON string
$json = $djson->processFileToJson('template.json', $data, JSON_PRETTY_PRINT);

// Validate template (returns array of errors, empty if valid)
$errors = $djson->validate($template);

Directives

Directive	Description	Example
`@djson for <array> as <var>`	Loop over array	`@djson for users as user`
`@djson if <condition>`	Include if truthy	`@djson if isActive`
`@djson unless <condition>`	Include if falsy	`@djson unless isDeleted`
`@djson exists <path>`	Include if path exists	`@djson exists user.email`
`@djson else`	Else clause	`@djson else`
`@djson match <value>`	Pattern matching	`@djson match status`
`@djson case <pattern>`	Match case	`@djson case active`
`@djson default`	Default case	`@djson default`
`@djson set <var> = <expr>`	Set variable	`@djson set total = price * qty`
`{{variable}}`	Variable interpolation	`{{user.name}}`
`{{var \| function}}`	Apply function	`{{name \| upper}}`

Loop Variables

{{_index}} - Current loop index (0-based)
{{_key}} - Current loop key
{{_first}} - true if first iteration
{{_last}} - true if last iteration

Requirements

PHP 8.1 or higher

Documentation

Complete documentation available at djson.dev:

License

MIT

Author

Qoliber - info@qoliber.com

Made with ❤️ by Qoliber | Documentation | GitHub

qoliber / djson

Maintainers

Details