Spintax - Modern PHP Text Variation Library

A modern, fully-typed PHP library for parsing and generating spintax text variations. Works with any PHP framework or standalone.

What is Spintax?

Spintax (spin syntax) represents multiple text variations using curly braces and pipes:

{Hello|Hi|Hey} {world|universe}!

Generates: "Hello world!", "Hi universe!", "Hey world!", etc.

Installation

composer require braseidon/spintax

Requirements: PHP 8.1 or higher

Quick Start

use Braseidon\Spintax\Spintax;

// Generate a random variation
$text = Spintax::spin('{Hello|Hi} {world|universe}!');
// → "Hello world!" or "Hi universe!" etc.

// Get all possible variations
$variations = Spintax::allVariations('{yes|no}');
// → ['yes', 'no']

// Count variations without generating them
$count = Spintax::countVariations('{a|b|c} {1|2}');
// → 6 (3 × 2 combinations)

// Generate using a specific path
$text = Spintax::replicate('{hello|hi}', [0]);
// → "hello"

Features

• ✅ Modern PHP 8.1+ - Full type safety with strict types
• ✅ Zero Dependencies - Works with Laravel, Symfony, WordPress, or standalone
• ✅ Nested Spintax - {The {quick|fast} {brown|red} fox|A lazy dog}
• ✅ Exception Handling - Validates balanced braces with clear error messages
• ✅ Comprehensive Tests - 27 tests, 52 assertions, 100% passing
• ✅ PSR-4 Autoloading - Standard Composer package

Documentation

Basic Usage

Generate Random Variation

$template = '{Welcome|Hello} back, {friend|user}!';
echo Spintax::spin($template);
// → "Welcome back, friend!" (random)

Get All Variations

$template = '{yes|no|maybe}';
$all = Spintax::allVariations($template);
// → ['yes', 'no', 'maybe']

Count Variations

$template = '{a|b} {1|2} {x|y}';
$count = Spintax::countVariations($template);
// → 8 (2 × 2 × 2)

Advanced Usage

Nested Spintax

$template = '{The {quick|fast} {brown|red} fox|A lazy dog}';
echo Spintax::spin($template);
// → "The quick brown fox" or "A lazy dog"

Optional Text

$template = 'This is{| very| extremely} cool';
echo Spintax::spin($template);
// → "This is cool" or "This is very cool"

Deterministic Generation

// Generate same variation for specific user
$template = Spintax::parse('{Hello|Hi}, {friend|buddy}!');

// Use specific path for reproducibility
echo Spintax::replicate($template, [0, 1]);
// → Always "Hello, buddy!"

// Or use path string
echo Spintax::replicate($template, '1,0');
// → Always "Hi, friend!"

Parse and Explore

$node = Spintax::parse('{a|b|c} {1|2}');

// Count combinations
echo count($node); // → 6

// Get all possible paths
$paths = $node->getPaths();
// → [[0,0], [0,1], [1,0], [1,1], [2,0], [2,1]]

// Dump back to spintax
echo Spintax::dump($node); // → "{a|b|c} {1|2}"

API Reference

Spintax Facade

spin(string $input): string

Generate a random variation from spintax text.

parse(string $input): SpintaxNode

Parse spintax into a tree structure for advanced manipulation.

replicate(string $input, array|string $path): string

Generate text using a specific path.

• Array path: [0, 1, 0] - index of choice at each branch
• String path: "0,1,0" - comma-separated indices

allVariations(string $input): array<string>

Get all possible text variations.

countVariations(string $input): int

Count variations without generating them.

dump(SpintaxNode $node): string

Convert a parsed tree back to spintax format.

SpintaxNode

Represents a node in the spintax tree. Get instances via Spintax::parse().

Methods:

• generate(array &$path = []): string - Generate text
• dump(): string - Convert to spintax format
• getPaths(): array - Get all possible paths
• count(): int - Count variations (Countable)
• getContent(): string - Get node's text
• getChildren(): array - Get child alternatives
• getNext(): ?SpintaxNode - Get next sequential node
• hasChildren(): bool - Check for alternatives
• hasNext(): bool - Check for next node

SpintaxParser

Lower-level parsing and generation. Usually use Spintax facade instead.

Methods:

• parse(string $input): SpintaxNode
• generate(string|SpintaxNode $content): string
• replicate(string|SpintaxNode $content, array|string $path): string

Exception Handling

The library validates spintax syntax and throws InvalidArgumentException for malformed input:

try {
    Spintax::spin('{unclosed brace');
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
    // → "Unbalanced braces in spintax input: unclosed opening brace"
}

Use Cases

Content Generation

$article = "Start by {leveling|grinding} in {Act 1|the first zone}. " .
           "{Focus on|Prioritize} {damage|survivability}.";

foreach (Spintax::allVariations($article) as $variation) {
    // Generate multiple unique articles
}

A/B Testing

$headline = '{Try|Start} {now|today} for {free|$0}!';
$variant = Spintax::spin($headline);

Email Templates

$greeting = '{Hi|Hello|Hey} {there|friend},';
$user_greeting = Spintax::spin($greeting);

SEO Meta Descriptions

$meta = 'Shop {affordable|cheap|budget} {shoes|footwear} {online|on the web}';
$description = Spintax::spin($meta);

Testing

composer test

All 27 tests pass with 52 assertions.

Framework Compatibility

Works with any PHP project:

• ✅ Laravel 8, 9, 10, 11, 12+
• ✅ Symfony 5, 6, 7+
• ✅ WordPress
• ✅ CodeIgniter, Yii, CakePHP
• ✅ Standalone PHP scripts

No framework-specific code or dependencies!

Performance

Efficient tree-based parsing with minimal memory usage:

• Handles deeply nested spintax
• Counts variations without generating them
• Fast random generation

Credits

Based on the ChillDev Spintax library by Rafał Wrzeszcz (2014).

Completely modernized and rewritten for PHP 8.4+ in 2025 with:

• Full type declarations
• Exception handling
• Improved API
• Comprehensive tests
• Modern PHP patterns

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Support

• Issues: GitHub Issues
• Docs: This README
• Tests: See tests/ directory for examples