README

⚡ Risma

A Lightweight String Template Engine & Interpreter for PHP

📖 Read Full Documentation & Interactive Guides →

🔮 What is Risma?

The logic lives inside the string itself.

Risma is a zero-dependency PHP string template engine and interpreter. It embeds processing logic, conditionals, and transformation pipelines directly inside plain text strings.

No eval(). No runtime dependencies. Safe for user-provided templates.

use Nabeghe\Risma\Risma;

// The string IS the program:
// Combines variables, pipelines, built-in conditionals, and Direct Function Execution (@)
$template = 'Hi {user.trim.title}! You have {unread} unread {unread.plural("message", "messages")}. '
          . 'Server time: {@date("H:i")} | Status: {@phpversion.truncate(3, "").if_gte("8.0", "Modern 🚀 (%s)", "Legacy ⚠️ (%s)")}';

echo Risma::quick($template, [
    'user'   => '  sarah connor  ',
    'unread' => 5,
]);
// Output: Hi Sarah Connor! You have 5 unread messages. Server time: 14:30 | Status: Modern 🚀 (8.4)

💡 Real-World Use Cases

• 🌐 Dynamic Translations: Store translations with built-in pluralization and fallbacks directly in your lang files: '{count.plural("%s item", "%s items", "No items")}'
• 📧 Notification & Email Templates: Marketers and editors write smart strings without developers touching PHP: 'Hi {name.or("there")}! Order #{id} is {status.upper}. Details: {notes.flatten_lines.if_empty("None")}'
• 🧩 Safe CMS Sandboxing: Safe execution of user-authored templates with a deterministic lexer (strictly zero eval()).

⚡ Syntax at a Glance

• 🎯 Direct Execution (@): Run standalone functions or chain pipelines onto them without a variable: {@date('Y')} or {@rand(1, 100).if_gte('50', 'Pass (%s)', 'Fail (%s)')} or {@line}
• 🔗 Pipeline Chaining (.): Pipe data through functions using dot notation: {user.trim.lower.title}
• 🎯 Argument Routing ($): Pinpoint where the piped value should land: {slug.str_replace('-', ' ', '$')}
• 🪆 Deep Nesting: Recursively resolve placeholders inside arguments from inside out: {@sprintf("Hello %s", "{user.upper}")}
• 🎨 Custom Delimiters & Shared Globals (v2): Configure custom tags ([: :]) and app-wide shared variables.

🚀 Installation & Quick Start

composer require nabeghe/risma

use Nabeghe\Risma\Risma;

// 1. Instant static execution with direct functions (@) and pipelines:
echo Risma::quick(
    'Welcome {user.trim.title}! Server year: {@date("Y")} (PHP {@phpversion.truncate(3, "")})',
    ['user' => '  hadi  ']
);
// Output: Welcome Hadi! Server year: 2026 (PHP 8.3)

// 2. Instance execution with custom delimiters, shared globals, and direct execution:
$risma = (new Risma())
    ->share('app', 'CloudPortal')
    ->setDelimiters('[:', ':]');

echo $risma->render(
    '[:app:] © [:@date("Y"):] — Welcome, [:user.upper:]!',
    ['user' => 'Ali']
);
// Output: CloudPortal © 2026 — Welcome, ALI!

📖 Documentation & Guides

For the complete manual, interactive search, comprehensive API reference, and production recipes:

• 🌐 Interactive Documentation Site (GitHub Pages)
• 📄 Full In-Repo Documentation (docs/index.md)
  • Core Concepts & Safe Lexer
  • Direct Execution (@)
  • Built-in Functions Arsenal (30+ Helpers)
  • Extending Risma (addFunc, addClass, addObject)
  • Engine API Reference
  • Production Recipes & Scenarios

🧪 Testing

composer test
# or: vendor/bin/pest

📄 License

Risma is open-sourced software licensed under the MIT License.