LightnCandy Documentation

When upgrading LightnCandy, follow these rules regarding template execution:

• Standalone templates: Templates compiled by older versions of LightnCandy remain safe and can be executed without changes when upgrading to a new version.
• Non-standalone templates: You must recompile all non-standalone templates whenever you upgrade LightnCandy to ensure compatibility with the current runtime.

Install LightnCandy using Composer to add it to your PHP project:

composer require zordius/lightncandy:dev-master

You can control how LightnCandy handles errors by passing specific flags in the $options array during compilation.

When errors are detected in the context:

• If 'flags' => ['errorlog' => 1] is set, errors are sent to the PHP error_log().
• If 'flags' => ['exception' => 1] is set, an \Exception is thrown containing the error messages.

Note: If neither flag is set, compile() will simply return false.

Due to changes in the render() debugging implementation, the rendering supporting class was renamed from LCRun2 to LCRun3 in version v0.12.

Action Required: If you compiled templates as non-standalone PHP code using LightnCandy v0.11 or earlier, you must recompile them to avoid a Class 'LCRun2' not found error.

You can replace the default LightnCandy\Runtime with your own implementation by providing the class name in the runtime option during compilation.

class MyRunTime extends LightnCandy\Runtime {
    public static function raw($cx, $v) {
        return '[[DEBUG:raw()=>' . var_export($v, true) . ']]';
    }
}

$php = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_HANDLEBARSJS,
    'runtime' => 'MyRunTime'
));

Note: The class must exist during both compilation and rendering (especially if using FLAG_STANDALONEPHP).

The renderex option allows you to inject custom PHP code into the generated render function. This code is executed inside the render function scope.

$php = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_HANDLEBARSJS,
    'renderex' => '// Compiled at ' . date('Y-m-d h:i:s')
));

Note: Ensure the passed string is valid PHP; LightnCandy does not validate it.

Register custom helpers by passing an associative array to the helpers key in the compile() options. Helpers receive $context and an $options array.

Block Helper Example (#mywith) To implement a block helper that changes context (similar to {{#with}}):

$php = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_HANDLEBARSJS,
    'helpers' => array(
        'mywith' => function ($context, $options) {
            return $options['fn']($context);
        }
    )
));

Helper Metadata

• Use isset($options['fn']) to detect if the helper is a block helper.
• Use isset($options['inverse']) to detect the existence of an {{else}} block.
• Access special data via $options['data'] (e.g., $options['data']['root'] for {{@root}}).
• Access current context via $options['_this'].

You can change the default {{ and }} delimiters using the delimiters option in compile(). This applies to the template and all included partials.

LightnCandy::compile('I wanna use <% foo %> as delimiters!', array(
    'delimiters' => array('<%', '%>')
));

Use the prepartial option in compile() to run a callback before a partial is compiled. This is useful for injecting metadata or modifying the partial content.

$php = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_HANDLEBARSJS,
    'prepartial' => function ($context, $template, $name) {
        return "<!-- partial start: $name -->$template<!-- partial end: $name -->";
    }
));

Use LightnCandy::compile($template, $options) to transform a Handlebars or Mustache template into pure PHP code. By default, it compiles to high-performance PHP. You can pass an array of flags to customize behavior, such as error handling or compatibility modes.

$php = LightnCandy::compile($template, array(
    'flags' => LightnCandy::FLAG_ERROR_LOG | LightnCandy::FLAG_STANDALONEPHP
));