bin | ||
src | ||
.gitignore | ||
composer.json | ||
composer.lock | ||
LICENCE | ||
Makefile | ||
README.md |
twigc
twigc is a user-friendly command-line utility for rendering (compiling) Twig templates. It's well suited for testing and for interacting with Twig through shell scripts and other command-line applications.
Usage overview
Usage:
twigc [options] [--] [<template>]
Arguments:
template Twig template file to render (use `-` for STDIN)
Options:
-h, --help Display this usage help
-V, --version Display version information
--credits Display dependency credits (including Twig version)
-d, --dir=DIR Add search directory to loader (multiple values allowed)
-e, --escape=ESCAPE Set autoescape environment option
-j, --json=JSON Pass variables as JSON (dictionary string or file path)
-p, --pair=PAIR Pass variable as key=value pair (multiple values allowed)
--query=QUERY Pass variables as URL query string
-s, --strict Enable strict_variables environment option
twigc can render Twig templates supplied via either standard input or a file path. Input data can be passed to the template using a simple key=value syntax:
% twigc -p 'name=dana' <<< 'Hello, {{ name }}!'
Hello, dana!
Of course, only simple string values can be provided this way. For more complex data, you can use the JSON option:
% twigc -j '{ "numbers": [1, 2, 3] }' <<< '{{ numbers|join("... ") }}!'
1... 2... 3!
JSON data can also be provided by file path or on standard input:
% cat numbers.json
{ "numbers": [1, 2, 3] }
% twigc -j numbers.json <<< '{{ numbers|join("... ") }}!'
1... 2... 3!
% cat numbers.twig
{{ numbers|join("... ") }}!
% twigc -j - numbers.twig <<< '{ "numbers": [1, 2, 3] }'
Normally, input data is auto-escaped for HTML before rendering, but this is configurable:
% twigc -p 'html=<p>Hello!</p>' <<< '{{ html }}'
<p>Hello!</p>
% twigc -p 'html=<p>Hello!</p>' -e 'url' <<< '{{ html }}'
%3Cp%3EHello%21%3C%2Fp%3E
% twigc -p 'html=<p>Hello!</p>' -e 'js' <<< '{{ html }}'
\x3Cp\x3EHello\x21\x3C\x2Fp\x3E
% twigc -p 'html=<p>Hello!</p>' -e 'false' <<< '{{ html }}'
<p>Hello!</p>
By default, references in the template to undefined variables are silently ignored; you can make Twig return an error instead:
% twigc <<< 'Hello, {{ name }}!'
Hello, !
% twigc -s <<< 'Hello, {{ name }}!'
[Twig_Error_Runtime]
Variable "name" does not exist in "-" at line 1
If a template file name was provided, the file's parent directory is used for Twig's include search path; if standard input was used, no search path is set at all by default. In either case, one or more additional search paths can be explicitly supplied on the command line:
% cat include.twig
Hello!
% twigc <<< '{% include "include.twig" %}'
[Twig_Error_Loader]
Template "include.twig" is not defined in "-" at line 1.
% twigc -d '.' <<< '{% include "include.twig" %}'
Hello!
Installation
twigc is provided as a self-contained executable archive; to download it, see the releases page.
Of course, you can also build and install it from source:
% git clone https://github.com/okdana/twigc
% cd twigc
% make
Requirements
The twigc executable is bundled with Twig and all of its other dependencies; the only thing you need to run it is PHP version 5.5 or higher.
Licence and acknowledgements
twigc is available under the MIT licence. For information about the licences
of its dependencies, run twigc --credits
.
The \Dana\Twigc\PharCompiler
class used to build the executable archive is
based on
\Composer\Compiler
.
See also
- twigphp/Twig — The Twig project on GitHub.
- farazdagi/twig-cli — Another project that aims to bring Twig to the command line. It's actually quite similar in design (though no code is shared); it just didn't have the features i wanted.
- twigjs/twig.js —
A pure JavaScript implementation of Twig. It comes with its own command-line
tool,
twigjs
, which can be used to render Twig templates, but it's quite limited. - indigojs/twig-cli —
Another command-line Twig renderer based on Twig.js. Its functionality is very
similar to (almost exactly the same as?)
twigjs
. - mattrobenolt/jinja2-cli — A command-line Jinja2 renderer. Very comparable to twigc in terms of features.