Skip to content
🔣 A simple templating engine for PHP
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
example
src/Spackle
.gitignore
LICENSE
README.md
composer.json

README.md

Spackle

A simple templating engine for PHP

StyleCI Total Downloads Latest Stable Version Latest Unstable Version License

Spackle allows you to add code blocks and substitutions to any file.

Creating Templates

Substitutions

Substitution Notation: {{...}}

<body>
   Hello, my name is {{name}}.
</body>

Substitutions will be replaced based on the configuration of their Parser.

Code Blocks

Code Block Notation: {{> ... <}}

<body>
  {{>
    echo "Hello, Word!";
  <}}
</body>

Code blocks are always parsed last, this way you can use substitutions and other plugins within code blocks.

<ul>
{{> 
  foreach ({{likes}} as $likeable) {
    echo '<li>';
    echo $likeable;
    echo '</li>';
  }
<}}
</ul>

Plugins

Plugin Notation: {{key ... <}}

You can create your own plugins to parse custom template keys.

See CodeBlockParser.php for an example of a plugin.

class MyPlugin extends \Spackle\Plugin
{
    // The key used to notate the beginning of this element.
    public $key = 'url';

    // Parse each element found matching this plugin.
    // {{url some/data <}} woud come out to https://localhost/some/data
    public function parse($data)
    {
        return 'https://localhost/'.$data;
    }
}

. . .

// Add on a global scope
\Spackle\Plugin::add(new MyPlugin());

// Add to a specific parser
$parser->addPlugin(new MyPlugin());

Parsing Templates

Once you've created a template, you can parse it in PHP. To parse the template you need to create an instance of \Spackle\TemplateParser. In the following example, we will use the \Spackle\FileParser class. It is a subclass of the TemplateParser, the only difference being that it loads the contents of a file in instead of using a string.

For this example, we will use the following Spackle Template stored in ./test.spackle.

<h4>Welcome to Spackle!</h4>

Spackle was created by <a href="{{github_url}}" target="_blank">{{name}}</a>.<br />

Some things that {{name}} likes are:<br />
<ul>

{{> 
    foreach ({{likes}} as $likeable) {
        echo '<li>';
        echo $likeable;
        echo '</li>';
    }
<}}

</ul>

<b>Bound: {{> echo $this->bound; <}}

Now, to parse it we will need to tell it what values to use.

<?php

include_once __DIR__.'/vendor/autoload.php';

use \Spackle\FileParser;

// The FileParser extends the TemplateParser
// and instead of cunstructing with a string
// is uses a file path.
$parser = new FileParser(
    // Template File Path
    __DIR__.'/test.spackle',

    // Optional Substitutions (add more with $parser->setSubstitution($key, $val))
    [
        'github_url' => 'https://github.com/nathan-fiscaletti/',
    ]
);

// You can set substitutions easily using the setSubstitution
// member function of a TemplateParser.
$parser->setSubstitution('name', 'Nathan Fiscaletti');

// You can also bind the Parser to a specific object.
// Anytime you reference `$this` in your code blocks
// within the template, this bound object will be
// referenced.
$bindTest = (object)[
    'bound' => 'Yes, Bound.'
];
$parser->bindTo($bindTest);

// You can use functions for substitutions.
// When the return value is an integer or
// a string, it will be directly substituted.
// Otherwise, the value will be used.
$parser->setSubstitution('likes', function() {
    return ['Coding', 'PHP', 'Trial by Combat'];
});

// The ->parse() function will parse the template
// and return the parsed value.
echo $parser->parse();

This should output something like this:

Welcome to Spackle!

Spackle was created by Nathan Fiscaletti.

Some things that Nathan Fiscaletti likes are:
    * Coding
    * PHP
    * Trial by Combat

Bound: Yes, Bound.

(You can find this example in ./example/

Why stop there?

You can use Spackle for any file type you want, since it's a glorified regex matcher.

For example, JavaScript:

console.log("Hello, {{name}}!");
You can’t perform that action at this time.