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
• Security First: Mandatory protection against dangerous functions (eval, exec, shell_exec, etc.)
• 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' => [...]]

Security

DJson takes security seriously with mandatory protection against dangerous function registration.

What's Protected

// These are BLOCKED - throws InvalidArgumentException
$djson->registerFunction('exec', fn($cmd) => shell_exec($cmd));
$djson->registerFunction('eval', fn($code) => eval($code));
$djson->registerFunction('file_get_contents', fn($path) => file_get_contents($path));
// Error: "dangerous pattern 'exec'... use registerUnsafeFunction()"

// Trying the "unsafe" method? ALSO blocked! (troll mode activated)
$djson->registerUnsafeFunction('exec', fn($cmd) => shell_exec($cmd));
// Error: "Sorry matey, no unsafe functions allowed! Security is mandatory!"

Protected Patterns

• Code Execution: eval, assert, call_user_func
• System Commands: exec, shell_exec, system, passthru, popen, proc_open
• Filesystem: file_get_contents, file_put_contents, unlink, chmod, rename
• Includes: include, require, include_once, require_once
• Serialization: unserialize
• Reflection: reflection
• Database Functions: mysqli, mysql_, pg_, sqlite, pdo, odbc_, sqlsrv_, oci_

Safe Functions Work Fine

// These are SAFE and work perfectly
$djson->registerFunction('currency', fn($v, $s = '$') => $s . number_format($v, 2));
$djson->registerFunction('md5hash', fn($v) => md5($v));
$djson->registerFunction('base64', fn($v) => base64_encode($v));
$djson->registerFunction('truncate', fn($v, $len = 50) => substr($v, 0, $len) . '...');

Why No Bypass?

Security is mandatory, not optional. If you need to execute system commands or access files, do it outside the template system where you have proper access controls. Templates are for rendering data, not executing code.

Deep Code Inspection

DJson uses PHP Reflection to inspect the actual source code of registered callables, not just function names:

// BLOCKED - Even though function name is safe, the code inside is dangerous!
$djson->registerFunction('process_data', function ($input) {
    return eval($input);  // Detected via reflection!
});
// Error: "callable's source code contains a call to prohibited function pattern 'eval'"

// BLOCKED - Database access detected in callable
$djson->registerFunction('get_user', function ($id) {
    return mysqli_query($conn, "SELECT * FROM users WHERE id = $id");
});
// Error: "callable's source code contains a call to prohibited function pattern 'mysqli'"

This means you cannot bypass security by wrapping dangerous functions inside safe-looking closures. DJson analyzes the actual implementation and blocks any dangerous code patterns.

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

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:

• Getting Started
• Template Functions
• Advanced Examples
• API Reference

License

MIT

Author

Qoliber - info@qoliber.com

Made with ❤️ by Qoliber | Documentation | GitHub