A library for replacing tokens in strings

1.0 2018-10-23 10:50 UTC

This package is auto-updated.

Last update: 2020-07-23 19:54:01 UTC


This simple library allows you to create a string that includes tokens, for example:


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.


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.


  • 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