lukaswhite / token-strings
A library for replacing tokens in strings
Installs: 14
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Type:project
Requires (Dev)
- phpunit/php-code-coverage: ^6.0
- phpunit/phpunit: 7.0
This package is auto-updated.
Last update: 2024-12-24 05:38:24 UTC
README
This simple library allows you to create a string that includes tokens, for example:
Dear [[FORENAME]] [[SURNAME]],
Then provide values for the tokens at runtime:
[ 'FORENAME' => 'Joe', 'SURNAME' => 'Bloggs', ]
And run a token substitution:
Dear Joe Bloggs,
It's useful for things like page titles, notification templates, mail merge and more.
Installation
Install using Composer:
composer require lukaswhite/token-strings
Basic Usage
Create an instance:
use Lukaswhite\TokenStrings\Substitutor( ); $substitutor = new Substitutor( 'Dear [[FORENAME]] [[SURNAME]],', [ 'forename' => 'Joe', 'surname' => 'Bloggs', ] );
Then run it:
$replaced = $substitutor->run( ); // or $replaced = ( string ) $substitutor;
Advanced Usage
You can modify the content of the template at any time:
$substitutor->setContent( 'Hey [[FORENAME]]' );
To add tokens:
$substitutor->addToken( 'age', 43 );
To clear the tokens:
$substitutor->clearTokens( );
If you'd prefer differrnt markup for the tokens:
$substitutor->setOpeningTag( '{{' )->setClosingTag( '}}' );
Since the closing tag in the example above is simply the reverse of the opening tag, you can simply do this:
$substitutor->setOpeningTag( '{{' );
In addition to passing strings as token values, you can also pass an object, provided it implements the magic __toString()
method:
class Person { private $forename; private $surname; public function __construct( $forename, $surname ) { $this->forename = $forename; $this->surname = $surname; } public function __toString( ) { return sprintf( '%s %s', $this->forename, $this->surname ); } } $substitutor = new Substitutor( 'Dear [[NAME]],', [ 'NAME' => new Person( 'Joe', 'Bloggs' ), ] );
To get a list of the available tokens, call getAvailableTokens()
.
The validate()
method checks that the string you provide does not contain any tokens for which you haven't provided values.
Notes
- Tokens must only contain letters, numbers, dashes and underscores
- By convention tokens are uppercase, but if you provide an array with the tokens in lowercase, it'll convert them for you
- If the string contains tokens that you have not provide values for, it will replace them with empty strings