webignition / stubble
A minimal library to replace mustache-like variables in strings
Installs: 2 050
Dependents: 2
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: ^8.0|^8.1
- webignition/stubble-resolvable: >=0.24,<1
Requires (Dev)
- phpstan/phpstan: ^1.3
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.6
README
A minimal library to replace mustache-like variables in strings, using PHP.
Installing
composer require webignition/stubble
Hello {{ name }}! Example
use webignition\Stubble\VariableResolver; use webignition\StubbleResolvable\Resolvable; // Using a VariableResolver instance $resolver = new VariableResolver(); $resolvable = new Resolvable( 'Hello {{ name }}!', [ 'name' => 'World', ] ); $resolvedTemplate = $resolver->resolve($resolvable); echo $resolvedTemplate; // Hello World!
Unresolved Variables
Variables remaining after resolving a template are considered unresolved variables. An unresolved variable in a template indicates that you are missing one or more values in the context. This is probably not what you want.
A UnresolvedVariableException
is thrown for the first unresolved variable.
use webignition\Stubble\UnresolvedVariableException; use webignition\Stubble\VariableResolver; use webignition\StubbleResolvable\Resolvable; $resolver = new VariableResolver(); $resolvable = new Resolvable( 'Hello {{ name }} and welcome to {{ location }}.', [ 'name' => 'World', ] ); try { $resolvedTemplate = $resolver->resolve($resolvable); } catch (UnresolvedVariableException $exception) { // Do something useful ... logging? $exception->getVariable(); // 'location' $exception->getTemplate(); // 'Hello {{ name }} and welcome to {{ location }}.' }
Selectively Allowing Unresolved Variables
Unresolved Variable Deciders
You may expect unresolved variables in resolved templates, for example if the content being generated is itself a template for use elsewhere.
Using a UnresolvedVariableFinder
, a resolver can make use of one or more unresolved variable deciders,
with each decider being a callable returning a boolean. The first decider to return true allows an
unresolved variable to be present without throwing an exception.
use webignition\Stubble\UnresolvedVariableFinder; use webignition\Stubble\VariableResolver; use webignition\StubbleResolvable\Resolvable; $resolver = new VariableResolver( new UnresolvedVariableFinder([ function (string $variable) { return 'location' === $variable; }, ]) ); $resolvable = new Resolvable( 'Hello {{ name }} and welcome to {{ location }}.', [ 'name' => 'World', ] ); $resolvedTemplate = $resolver->resolve($resolvable); echo $resolvedTemplate; // Hello Jon and welcome to {{ location }}.
Use the DeciderFactory to Create Common Deciders
use webignition\Stubble\DeciderFactory; use webignition\Stubble\VariableResolver; use webignition\Stubble\UnresolvedVariableFinder; $resolver = new VariableResolver( new UnresolvedVariableFinder([ // Allow all unresolved variables DeciderFactory::createAllowAllDecider(), // Disallow all unresolved variables DeciderFactory::createDisallowAllDecider(), // Allow unresolved variables by pattern (regular expression), DeciderFactory::createAllowByPatternDecider('/^variable[0-9]$/') ]) );