Merge Token Bundle Laravel Package

Getting Started

Read the package before installing it. idci/merge-token-bundle is a Symfony bundle, not a Laravel package — there is no ServiceProvider, no extra.laravel block, and no facade, so composer require will not auto-discover or bootstrap anything for you. Day-to-day leverage in a Laravel codebase is almost always pattern-borrowing, not dependency adoption.

Minimal steps:

1. Clone, don't require. git clone the repo and read three files first: the *Bundle.php class (to see what services are registered), the DependencyInjection/ extension (to see config shape), and the token parser/resolver classes (the actual algorithm). That's usually the majority of the value.
2. Check compatibility before any spike. Inspect its composer.json constraints (symfony/*, php) and run composer require --dry-run idci/merge-token-bundle in the Laravel app. Symfony bundles of this vintage commonly pin EOL stacks; a hard conflict with Laravel 10/11/12's Symfony 6/7 components is the likely outcome.
3. Decide the path immediately:
   • On Symfony and prepared to own the code: vendor/fork it, pin the commit SHA, and register the bundle in config/bundles.php.
   • On Laravel (the normal case): treat it as a reference implementation and build a first-party resolver behind your own interface.
4. First use case to target: personalized transactional notification emails (internal, non-customer-facing) — resolve tokens before Blade renders, so the template engine only ever sees plain text. Hello [[first_name]], your invoice [[invoice_number]] is ready → Hello Ada, your invoice INV-1042 is ready. Never start with customer-facing PDFs or contract generation.

Implementation Patterns

The single most important pattern: isolate the capability behind your own interface so the vendor code — or its absence — is a detail.

interface MergeTokenResolver
{
    public function resolve(string $template, array $context): string;
}

Every call site depends on MergeTokenResolver, never on a vendor class. Then:

• Bind a first-party implementation (App\Support\TokenResolver) in a service provider. Its ~200–400 lines: a regex parser for the token syntax the bundle uses (confirm whether it's {{ token }}, [[token]], or %token% — read the parser, don't guess), a lookup against a typed context map, and a formatter hook for dates/currency.
• Resolution before rendering. Resolve into a plain string and pass that to Blade/Mail::raw/PDF renderers. Do not resolve inside Blade directives — double-rendering and escaping ambiguity follow.
• Allowlist tokens. Define the set of resolvable token names explicitly (invoice_number, first_name, due_date), rejecting anything else. This is both a security control and a documentation artifact.
• Typed formatters per token, not per template: due_date knows it renders as d/m/Y; the template author doesn't specify format. This keeps templates dumb and the resolver testable.
• Strict vs. lenient mode by environment. In local/testing, throw on unknown tokens; in production, log and render a safe placeholder ([[invoice_number]] left visibly intact beats silent empty string).
• Cache resolved templates keyed by hash(template) + schema(context keys) — not by context values, which would explode the cache. Invalidate on template edit (a Template model saved observer is the natural hook).
• Symfony-only path (if it applies): register the bundle, move its YAML config into config/packages/merge_token.yaml, tag your custom resolver services, and add an integration test per resolver so a future dependency bump fails loudly.

A useful migration sequence if you ever had adopted it: define the interface → POC vendor code behind it → reimplement in-house → swap the container binding (a one-line config change because call sites only know the interface).

Gotchas and Tips

• It is not a Laravel package. The Bundle suffix and IDCI-Consulting namespace are the tells. Expecting Artisan auto-discovery will waste an afternoon.
• Unmaintained by every signal: 0 stars, 0 dependents, no visible releases or CI. If you adopt, you are the maintainer from day one. Budget a named owner and your own test suite; token merging is deceptively easy to get subtly wrong (whitespace inside {{ token }}, case sensitivity, trailing newlines).
• Silent unresolved tokens are the worst failure. Hello [[first_name]] reaching a customer is the highest-probability embarrassment. Assert on it: a test that renders every template with a synthetic context and fails if any [[ or {{ survives. Gate it in CI.
• Distinguish "absent" from "empty." A missing context key and a deliberately blank name must not both collapse to ''. Throw (strict) or render a visible placeholder (lenient); never silently produce an empty string.
• Escaping is the resolver's job, not the caller's. If token values flow into HTML email or PDF, escape at the resolver boundary based on an explicit target mode (html, text). Token merging is a classic injection surface when templates or values are user-supplied.
• Cap recursion depth. If you support nested tokens, guard against token-in-token expansion loops and amplification with a fixed max depth (e.g. 5) and a test that proves the cap fires.
• Unknown-token behaviour must be documented, not discovered. Decide and write it down: throw, log-and-placeholder, or strip. This is the single question your security review will ask.
• Verify the LICENSE before vendoring any code, and pin a commit SHA with a documented diff so fork drift is visible.
• Configuration mismatch: Symfony's DI extension and compiler passes do not execute under Laravel. Any config.yml the bundle expects must be re-expressed as config/merge_token.php and bound manually in a service provider.
• Don't benchmark CPU. String substitution is microseconds and will never be your bottleneck; the scaling decision is caching resolved templates, not optimizing the parser.
• Ramp-up is low, knowledge concentration is high. With no upstream docs or community, understanding lives with whoever reads the source. Pair on it and commit the behaviour matrix (token syntax, escaping rules, unknown-token policy, recursion cap) into the repo so at least two engineers can modify the resolver.

Bottom line for day-to-day use: read it once as prior art, then own a small, tested, allowlisted resolver behind your own interface. The feature is a few days of work; inheriting a Symfony bundle into Laravel is not.