Php Text Template Laravel Package

Getting Started

Install via Composer: composer require phpunit/php-text-template. This is a purely functional templating tool—no service provider, no config, no Laravel integration. Use the SebastianBergmann\Template\Template class directly to replace {placeholder} (escaped) or {!placeholder} (raw) markers. Start with a minimal example:

use SebastianBergmann\Template\Template;

$template = new Template('Welcome, {username}! Your balance is ${balance}.');
$output = $template->render([
    'username' => 'Alex',
    'balance'  => '1,250.00'
]);

echo $output; // "Welcome, Alex! Your balance is $1,250.00."

First use case: Generate CLI output, config stubs, or test fixtures—e.g., scaffolding .env.example files or static API response samples for docs.

Implementation Patterns

• Template-as-source: Store templates in plain .tpl or .txt files and load via file_get_contents(). Ideal for pre-rendered artifacts (e.g., README snippets, migration stubs).

  $template = new Template(file_get_contents('stubs/migration.tpl'));
  file_put_contents('database/migrations/'.date('Y_m_d_His').'_create_users.php', $template->render(['table' => 'users']));
  

• Composable templates: Embed raw output of one template inside another using {!inner}—useful for building multi-layer scaffolds (e.g., a controller template embedding a model template).
• Test-driven generation: Use this to assert exact output from generators in tests (e.g., verify a config writer produces config/app.php matching a golden template).
• CLI tooling: Wrap the engine in an artisan command to generate project boilerplate—e.g., php artisan make:template user-invite → populates resources/emails/user-invite.txt.
• Caching strategy: Since render() compiles on every call, pre-instantiate templates for high-frequency use:

  $cachedTemplates = [];
  function getTemplate(string $name): Template {
      return $cachedTemplates[$name] ??= new Template(file_get_contents("templates/$name.tpl"));
  }
  

Gotchas and Tips

• Zero logic, no helpers: No @if, @foreach, or @include—all branching/looping must be done before calling render(). Prepare arrays of data and flatten nested structures manually.
• Escaping is subtle: {foo} escapes &, <, >, ", '—but only ASCII. {!foo} is raw HTML injection risk if used with user content. Override escaping via Template::escape() for custom behavior (e.g., JSON-safe output).
• Placeholder precision matters: Whitespace like { foo } will not match ['foo' => 'bar']. Use exact keys with no spaces.
• PHP version churn: v6.0 dropped PHP 8.3; v5.0 dropped 8.2. Lock your version pin (^4.0) if targeting newer PHP runtimes—this isn’t stable for broad adoption.
• Debugging blank output: Common causes: missing keys (key mismatches), template file not found (silent file_get_contents failure), or NULL values (silently rendered as empty string). Log array_keys() against the template string to validate.
• Wrap, don’t extend: Since the class is final and has no DI hooks, create your own TextTemplateRenderer service to handle defaults, validation, and error logging—this keeps Laravel’s lifecycle clean.
• Security: Never render untrusted input as template data without explicit validation—this engine assumes you sanitize the data array first.