Rafał Wrzeszcz - Wrzasq.pl

ChillDevSpintax library - objective PHP library for spintax texts

Friday, 24 January 2014, 21:03

I'm working right now on a SEO tool and a must-have feature for such tools is support for spintax texts. It's a really common requirement so I though that there are planty of libraries for PHP to work with it. To my surprise I've hardly found any code snippet, not even a "complete" libraries and what's more most of them was… let's say it straight - crappy. Especially that project I'm working on requires a little more then just generating random texts, I need to remember and exclude already generated combinations etc. I had no other way than developing own library to deal with it, but since it's a completely stand-alone solution I decided to publish it as open source project - ChillDevSpintax library.

Spintax - what's that?

What is this spintax at all? It is the specific syntax for embedding multiple variations of text within one article. It is especially useful for SEO, when you need to generate unique content for multiple pages. Here is a sample spintax text:

{Hello|Hi} {World|people}!

From this snippet spintax library can generate 4 disctinct variations:

  • Hello World!
  • Hello people!
  • Hi World!
  • Hi people!

ChillDevSpintax library

The library is available for free under MIT license so you can use it even in your commericial projects. How to use it? The easiest and recommended way to obtain it is through Composer package:

"chilldev/spintax": "0.0.1"

Just add the definition above to your composer.json file in dependencies section and run composer.phar update. After doing that you should be able to use library in your code.

Doing this is really easy. To parse the spitnax source text you need to use Parser::parse() method:

use ChillDev\Spintax\Parser;

$source = 'Schrödinger’s Cat is {dead|alive}.';
$spintax = Parser::parse($source);

Now, with $spintax object you can do a lot of interesting things. Most notably you can generate random variant of the spintax text:

echo $spintax->generate();


Ok, but as I wrote on the begining of this article simple generate() is not enough for me. And maybe also not for you, so lets see what more we can do with this $spintax object. But for doing that we need at least a little more complicated example. In all following examples we will assume that $spintax was generated in following way:

use ChillDev\Spintax\Parser;

$source = 'I {love {PHP|Java|C|C++|JavaScript|Python}|hate Ruby}.';
$spintax = Parser::parse($source);

What I called a path is a sequence of particular steps needed to produce given outcome of spintax source permutation. It may be extremely important to know this way. To find it out you can use a parameter that is optional and passed by reference - it's an array that contains sequence of choices that were picked by generator to generate current outcome:

$path = [];
$outcome = $spintax->generate($path);

// now calling $spintax->generate($path); again
// will always generate the same output

// this on the other hand will produce "I love JavaScript"
$path = [1, 4];
echo $spintax->generate($path);

Note that this parameter is bi-directional - when it's empty it's being filled during computation of random string, when it's already filled it's items are used to select desired variant. But that's not all: path can even be incomplete - may contains just some initial steps and the missing ones will be choosen randomly and also pushed to the returning $path argument. Following example will generate one of the I love variants and the resulting $path variable will contain full path:

$path = [0];
$outcome = $spintax->generate($path);

But sometimes you need to need all the possible paths before you generate any string. Don't worry, there are two additional useful methods - count() returns number of all possible combinations and getPaths() returns list of all possible paths.

Here is an example that lists all possible combinations possible to be generated from source spintax:

foreach ($spintax->getPaths() as $path) {
    echo $spintax->generate($path), "\n";

Another handy example - generating random strings without repetitions:

$paths = $spintax->getPaths();
$count = 4;

while (!empty($paths) && --$count > 0) {
    $path = array_pop($paths);
    echo $spintax->generate($path), "\n";


It's still not everything. There is one more method you may be interested in - Parser::replicate(). Basically it's a shorthand method that you can use to immediately generate pre-defined or random variants from spintax source:

use ChillDev\Spintax\Parser;

$source = 'I {love {PHP|Java|C|C++|JavaScript|Python}|hate Ruby}.';

// this will print "I love PHP."
echo Parser::replicate($source, [0, 0]);

This method has following differences from using instance of parsed spintax directly:

  • first argument can be parsed spintax, but can aswell be a plain spintax source string;
  • second argument is not passed by reference so you can pass a literal value, however, on the other hand, you can't retrive resulted path (this methos is mainly there for re-creating already known paths);
  • second argument is mendatory - although you can still provide empty array (like above - main use of this method is to repreduce already known paths);
  • and finally second argument can be either an array or a plain string - in case of string it should contain list of steps separated by commas (for example 0,4 for I love JavaScript.).


This is MIT-licensed open-source project published on GitHub. You don't need to ask if you can, just do all the awesome things you want!

Tags: Web, SEO, Code, Tutorial, Spintax, ChillDev, PHP