Merge Token Bundle Laravel Package

Technical Evaluation

Architecture fit idci/merge-token-bundle solves a narrow, well-understood problem: locate named placeholders in a string and substitute runtime values. That capability maps cleanly onto several roadmap items a TPM is likely already tracking — personalized transactional email, statement/invoice rendering, contract generation, white-label copy, notification templating. Evaluated as a capability, it fits. Evaluated as a dependency, it does not: this is a Symfony bundle (*Bundle suffix, IDCI vendor namespace, expected DependencyInjection/, Resources/config/, kernel registration), while our application is Laravel. There is no ServiceProvider, no facade, no extra.laravel autodiscovery block, and no Symfony kernel to register the bundle against. The TPM's read is that the package is a useful reference for scoping the problem and a poor candidate for the solution.

Integration feasibility Two credible paths, one of which is really a decision to build:

1. Consume as-is in Laravel — pull symfony/framework-bundle and its transitive tree into a Laravel app solely to obtain a string-substitution utility, then manually wire the bundle's services around Laravel's container. High blast radius, low payoff, and an ongoing upgrade tax every time Laravel bumps its Symfony component constraints.
2. Port the pattern — take the token-parsing and resolver-registration ideas, define our own interface, and implement in-house (or on top of Blade components / a maintained engine). The algorithm is small; the value here is the prior art, not the artifact.

With 0 stars and 0 dependents there is no Laravel bridge to lean on and no community pressure sustaining one. Building a bridge would mean maintaining someone else's abandoned code inside our stack — a cost the TPM should refuse on principle.

Technical risk

• Abandonment risk: high. Zero stars, zero dependents, no visible release or CI signal. The honest planning assumption is that we become the maintainer the day we install it.
• Version skew: high. Symfony bundles of this shape typically pin symfony/* to 2.x/3.x and PHP 5.6–7.x. Modern Laravel requires PHP 8.1+ and Symfony 6/7 components, so a Composer conflict is more likely than not. This is a schedule risk, not just a technical one — it surfaces mid-sprint if not front-loaded.
• Security surface: moderate and conditional. Token merging is a classic injection and PII-egress path. If templates or token values are user-supplied, we need defined escaping, unknown-token behaviour, and expansion limits. There is no evidence of a threat model here, so we would be adopting an unaudited component on a PII-adjacent code path.
• Feature ceiling: low but adequate for v1. Flat substitution is table stakes; conditionals, loops, formatters (dates, currency, locale), HTML-vs-plaintext escaping modes, and missing-token fallbacks are typically absent in bundles this small. A TPM should assume we will outgrow it.
• Licensing: low risk, unverified. Confirm the LICENSE file before any vendoring or copying.

Key questions

• Does it support PHP 8.1+ and Symfony 6/7, or is it pinned to an EOL stack? What does composer require --dry-run say against our composer.lock?
• What is the last commit date, open-issue count, and whether any release was tagged in the last 24 months?
• What is the token syntax ([[token]], {{ token }}, %token%), and does it support defaults, typed formatting, or nested tokens?
• How are unknown tokens handled — throw, leave literal, or empty string? This drives our failure-mode design regardless of implementation.
• Is there recursion protection on token-in-token expansion?
• Who is the named engineer who owns this capability if we fork or reimplement it?

Integration Approach

Stack fit Poor as a dependency; good as a specification. Our stack is Laravel (PHP 8.x) on Composer, Laravel's service container, and Blade for rendering. A Symfony bundle's kernel/extension/compiler-pass model has no natural entry point. The correct fit is either a Laravel-native package we control or a framework-agnostic resolver with zero Symfony coupling. The TPM's framing for stakeholders: we are not buying a component, we are buying a design reference at the cost of one POC sprint.

Migration path Recommend wrap-then-replace, which keeps the roadmap date intact while removing dependency risk:

1. Define the seam first. Introduce MergeTokenResolver::resolve(string $template, array $context): string as a first-party interface. Every consumer (mailer, PDF renderer, notification service) depends on the interface only — never on a vendor class. This is the single most important TPM-level constraint because it makes the eventual swap a one-line container binding.
2. POC the vendor code behind the seam in a throwaway branch to extract a behaviour matrix: unknown tokens, missing keys, nesting, escaping, performance on large templates, error handling.
3. Reimplement in-house once the POC confirms the logic is small — the expected outcome. Ship it as a first-party package with our release cadence and our tests.
4. Swap the binding and delete the POC branch and the vendor dependency.

This converts an unmaintained third-party risk into a few engineer-days of scoped work, and gives us the functional requirements for free.

Compatibility

• PHP/Composer: validate constraints before committing to any plan; assume conflict until proven otherwise.
• Container semantics: any config.yml the bundle expects must be re-expressed as config/merge_token.php and bound manually — a translation cost the TPM should budget for rather than discover.
• Rendering boundary: decide up front whether resolution happens before Blade (strongly preferred — tokens become plain text, escaping stays predictable) or inside Blade directives (double-rendering and escaping ambiguity). This is an architecture decision, not an implementation detail, and should be recorded as such.

Sequencing

• Week 1 — dependency and licence audit, composer dry-run against our lock, POC branch, behaviour matrix documented.
• Week 2 — interface definition, in-house resolver, unit tests for unknown tokens, missing keys, nested tokens, large templates, escaping.
• Week 3 — bind in the container, migrate one low-risk consumer (internal notification emails), instrument for unresolved tokens.
• Week 4+ — roll out to customer-facing email and document generation, retire the POC branch, close out the vendor dependency.

Operational Impact

Maintenance Adopting as-is means forking unmaintained code — the worst position: we pay the upgrade cost without controlling upstream. A 200–400 line in-house resolver is cheaper over a 2–3 year horizon and removes a supply-chain node. Either way, assign a named owner. Token merging is deceptively easy to get subtly wrong (whitespace, case sensitivity, absent-vs-empty keys), so it needs a test suite we control and can evolve.

Support There is no meaningful upstream support channel. Zero dependents means no Stack Overflow corpus, no community patches, no third-party security advisories, and no escalation path. Any production issue becomes a first-party incident. That is an acceptable posture for a utility we wrote and understand; it is not acceptable for an inherited dependency on a customer-facing, PII-adjacent path.

Scaling Runtime cost is negligible — parsing is microsecond-scale and will never be the bottleneck. The real scaling concern is template volume and cache strategy: cache resolved templates keyed by template hash plus context schema, and invalidate on template change. Design this in from the start for high-volume transactional email rather than retrofitting it after volume arrives.

Failure modes

• Silent unresolved tokens reaching customers (Hello [[first_name]]) — highest probability, highest embarrassment. Mitigate with a strict mode that throws outside production, logs a warning in production, and an assertion in the email-rendering test suite.
• Missing context keys rendering as empty strings — distinguish "absent" from "empty" explicitly.
• Injection where token values contain markup later rendered into HTML email — enforce escaping at the resolver boundary, never at the caller.
• Recursive or nested token expansion looping or amplifying — cap expansion depth.
• Composer conflict discovered mid-sprint — front-load the dry-run check.
• Fork drift if vendored — pin the commit SHA and document the diff.

Ramp-up Conceptually low ramp-up, but knowledge concentration risk is high: with no upstream docs or community, understanding lives entirely with whoever runs the POC. Mitigate by pairing, committing the behaviour matrix to the repo, and ensuring at least two engineers can modify the resolver. Budget roughly 3–5 engineer-days for the port-and-test path. The alternative — keeping a Symfony bundle alive inside Laravel — is open-ended and almost certainly larger.

Recommendation: evaluate and do not adopt as a dependency. Treat it as prior art, implement the capability behind a first-party interface, and close the package out as "evaluated, not adopted."