⚡ StubEngine

Hierarchical template and stub scaffolding engine with token interpolation and host overrides for PHP and Laravel.

Why This Exists • Key Features • Requirements • Installation • Quickstart • Usage & Recipes • Documentation • API Reference • Testing • Changelog • License

Why This Exists

Generators, module builders, manifest installers, and CLI scaffolding tools repeatedly reinvent low-level filesystem operations:

1. Interpolating token placeholders in file contents.
2. Interpolating token placeholders in directory and file names (e.g. src/{{ ClassName }}.php.stub).
3. Stripping template extensions (.stub).
4. Enabling consumer applications to override default stubs without modifying vendor packages.
5. Handling single-file stubs (e.g. compiling a standalone script or configuration) alongside multi-file directory trees.

StubEngine extracts this entire lifecycle into a lightweight, zero-bloat service. Whether you need to render an in-memory string, scaffold an individual file with host overrides, or generate an entire directory hierarchy, StubEngine provides a clean, unified API.

Key Features

• Dual Override Strategies (Overlay vs Replace):
  • OverrideStrategy::Overlay (Default): Cascading file-by-file overlay. If a host project customizes 1 file out of 10, the other 9 package defaults are preserved.
  • OverrideStrategy::Replace: Complete directory substitution ("all-or-nothing"). Perfect for document bundles, template suites, or thematic assets where a custom template completely replaces the default directory layout.
• Extensible Token Modifiers (Open-Closed Principle):
  • Built-in string casing: studly, camel, kebab, snake, lower, upper, title, plural, and singular.
  • Register custom modifiers via StubEngine::registerModifier('custom', fn ($val) => ...).
• High-Performance Single-Pass Compilation: Token dictionaries are pre-compiled and sorted once upfront per tree operation, eliminating $O(N \times M)$ overhead.
• Configurable Delimiters & Zero-Trust Fallbacks:
  • Globally customize placeholder delimiters (e.g. <% %> or [[ ]]) via config/stub-engine.php to eliminate syntax collisions with Blade ({{ $var }}), Vue, Jinja, or bash.
  • Override delimiters on a per-call basis at runtime.
  • Zero-trust resilience: falls back gracefully to default delimiters ({{ and }}) even if config is absent or empty.
• Global & Dynamic Tokens:
  • Define application-wide global tokens (e.g. company_name, year, author) in config/stub-engine.php.
  • Runtime tokens seamlessly merge and take precedence over global tokens.
• Dual-Axis Token Interpolation: Replace tokens in both file contents AND file/directory pathnames simultaneously (e.g. src/<% Module|studly %>.php.stub).
• Path Normalization: Cross-platform path handling for seamless generation on Windows, macOS, and Linux.
• Binary & Raw Asset Protection: Files without .stub extension are safely copied without string interpolation, and system junk files (.DS_Store, Thumbs.db, .gitkeep) are automatically filtered out.
• Strict Diagnostics Mode: Discover required tokens in templates via extractTokens(), or pass strict: true to fail fast before deploying broken code.
• Safe Overwrite & Dry-Run Modes: Prevent accidental file overwrites (force: false) and simulate execution non-destructively for CLI commands (dryRun: true).
• Decoupled Architecture: Pure constructor DI with Illuminate\Filesystem\Filesystem and array config. Usable across Laravel console commands, service providers, background jobs, or standalone pure PHP CLI tools.
• Rich DTO Architecture: Returns a typed ScaffoldResult object with granular file status arrays (createdFiles, overwrittenFiles, skippedFiles, overrideFiles, rawCopiedFiles, unresolvedTokens) and combined $renderedFiles for clear inspection.

Requirements

• PHP: ^8.2 | ^8.3 | ^8.4
• Laravel Framework (or Components): ^11.0 | ^12.0 | ^13.0
  • illuminate/filesystem
  • illuminate/support

Installation

Install via Composer:

If you are using Laravel, the service provider and StubEngine facade are automatically registered via package discovery.

Quickstart

1. Scaffold a Single File (e.g. CLI Runner or Config)

2. Render In-Memory Content from a Stub

3. Scaffold a Complete Directory Tree

Organize your stubs directory keeping the natural folder hierarchy:

Execute scaffolding:

Usage & Recipes

1. Dependency Injection in Console Commands

In clean architecture, inject AlexKassel\StubEngine\StubEngine directly into your console commands:

2. Configuration & Global Tokens

Publish the package configuration file to customize delimiters and register application-wide tokens:

The published config/stub-engine.php file:

3. Dual Override Strategies: Overlay vs Replace

When consumer applications provide custom stubs, choose between two distinct strategies using OverrideStrategy:

4. Custom Delimiters (Preventing Syntax Collisions)

When scaffolding templates that already contain Blade, Vue, or bash syntax, specify custom delimiters at runtime or via config:

In your stubs and file paths, use <% entity|studly %> or <% entity|kebab %>, while preserving native Blade syntax like {{ $user->name }} without interference.

5. Built-in Token Case Modifiers

Tokens can be automatically transformed using built-in pipe modifiers in both file contents and file paths:

In any stub file or file path, you can use:

• {{ entity|studly }} → UserProfile
• {{ entity|camel }} → userProfile
• {{ entity|kebab }} → user-profile
• {{ entity|snake }} → user_profile
• {{ entity|lower }} → user profile
• {{ entity|upper }} → USER PROFILE
• {{ entity|title }} → User Profile
• {{ entity|plural }} → user profiles
• {{ entity|singular }} → user profile
• {{ entity|trim }} → user profile (whitespace stripped)

Registering Custom Modifiers

Extend the engine at runtime with custom domain modifiers:

6. Strict Mode Diagnostics

Prevent broken PHP code caused by forgotten placeholder variables:

7. Inspecting Scaffold Results & Dry-Run Mode

The ScaffoldResult DTO provides fine-grained visibility into file operations through strongly-typed, public readonly properties:

Documentation

Comprehensive deep-dive guides are available in the docs/ directory:

• Fluent ScaffoldBuilder Guide: Complete guide to the chainable builder API (from(), to(), withTokens(), override()), conditional steps (when(), unless()), macro extensions, and detailed operational flags (force(), dryRun(), strict(), delimiters(), ignore(), onProgress()).
• Token Modifiers Guide: Exhaustive reference for built-in string transformations (studly, camel, kebab, snake, lower, upper, title, plural, singular, trim), modifier chaining ({{ model|snake|plural }}), custom modifier registration, and Blade @{{ ... }} escaping.
• Architecture & Guide: Architecture overview, DI singleton lifecycle, custom macros on the engine, and raw token diagnostics via extractTokens().

API Reference

StubEngine::from

Starts a fluent scaffolding pipeline for a source stub file or directory.

StubEngine::renderFile

Renders a single stub file into a string with token replacements using a ScaffoldRequest DTO. Throws InvalidArgumentException if the source is a directory.

StubEngine::scaffold

Executes scaffolding for either a single file or a complete directory tree (automatically determined from $request->source). Returns a ScaffoldResult object detailing created, overwritten, and skipped files.

StubEngine::registerModifier

Registers a custom runtime token modifier function (e.g. {{ var|name }}) delegated to the Interpolator service.

StubEngine::extractTokens

Scans raw template or generated content and returns an array of unique unescaped token names (before any modifier pipes) found within delimiters.

Testing

Run the test suite using PHPUnit:

Or via direct PHPUnit binary:

Changelog

Please see CHANGELOG.md for more information on recent changes.

Contributing

Contributions are welcome! Please review CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.