Dictionary Bundle Laravel Package

Technical Evaluation

Architecture fit. The problem the package targets is real and recurring: enumerated reference data (gender, civility/salutation, marital status, country, unit codes) gets copy-pasted into form types, validators, fixtures, API resources, and templates until the values drift apart. A single registry for these lists is a sound architectural instinct, and it is the kind of small, boring capability that pays off quietly across a codebase. That said, the framing of this as a "Laravel/PHP package" needs correction before anything else: the *Bundle naming, the vendor, and the repository name all point to a Symfony bundle, meaning a DependencyInjection extension, service definitions under Resources/config, and Symfony-version-coupled constraints. Symfony bundles are not natively consumable by Laravel's service-provider/package-discovery model. If our stack is Symfony, architectural fit is good. If our stack is Laravel, this is a port candidate or a reference implementation, not a dependency.

Integration feasibility. Low to moderate, and gated almost entirely on due diligence rather than on technology. Zero stars and zero dependents means there is no downstream pressure keeping this package compatible with anything, no public corpus of usage patterns, and no evidence that it has survived a real production upgrade cycle. The 3.34 score is a metadata-hygiene signal (license present, release cadence, description quality), not an adoption signal — do not read it as validation. The actual integration surface is likely small: a dictionary registry service, optional form types, optional Twig helpers, and translation resources. Small surfaces are cheap to integrate and cheap to replace, which is the main mitigating factor here.

Technical risk.

• Bus factor of one. A single maintainer with no co-maintainers and no dependents. If the maintainer stops, nothing breaks loudly; it breaks at the next PHP or Symfony major.
• Framework coupling. Symfony bundles that ship form types and DI configuration are tightly bound to framework majors. A composer.json constraint conflict can block unrelated security patches across the monorepo.
• Stability of value codes. These lists look static and are not. "Miss" vs "Ms", binary vs inclusive gender options, country code churn, and locale-specific civility forms are all politically and legally loaded and change on a timescale of years. If stored database values are keyed to the package's codes, a rename is a data migration.
• Scope ambiguity. The README will tell us it renders selects. It will not tell us whether it also owns validation, persistence, serialization, and translation, which determines whether this is a helper or a load-bearing dependency.
• The native-enum alternative. PHP 8.1+ backed enums plus a config file and symfony/translation cover ~80% of this use case in under a hundred lines with zero third-party risk. The package must beat that baseline to justify itself.

Key questions for the spike.

1. Symfony-only? Which Symfony and PHP versions are actually tested in CI, and is there a CI matrix at all?
2. Does it own only presentation, or also validation and persistence? Are values stored as string codes, integers, or enum cases?
3. Are the codes documented as stable, and is there a deprecation/migration story for retired values?
4. Which locales ship translation files, and what does the fallback render to a user — a translated label or a raw key?
5. Can dictionaries be extended or overridden per project without forking?
6. Is the 2025-12-27 release a substantive tag or a drive-by version bump? What does the changelog and commit history actually show?
7. Test coverage, static analysis, and a security disclosure path.

Integration Approach

Stack fit. On Symfony, adopt behind an interface and treat it as an implementation detail. On Laravel, do not attempt to install it; extract the content — the curated, ordered, translated choice lists — which is the real asset here, and reimplement the thin lookup layer natively. A Laravel-shaped version is a config/dictionaries.php, a DictionaryManager singleton, a Rule object for validation, and a Blade component for rendering. That is a day of work and eliminates the dependency entirely.

Migration path. Standard anti-corruption layer. Define an internal DictionaryProvider contract (values(string $key, ?string $locale): array, isValid(), label()), then bind the third-party bundle — or our own implementation — behind it. No call site ever references the package namespace. This costs a few hours up front and converts the build-vs-buy decision into a reversible, per-key choice rather than a one-way door.

Compatibility. Verify PHP constraint against our runtime, Symfony constraint against the framework version, and the transitive footprint (symfony/form, symfony/translation, Doctrine if entities are involved). Watch for conflicts with existing form themes, API Platform serialization, and any JSON schema we publish for enums.

Sequencing.

1. Spike (1–2 days): read the source, not the README. Run the test suite. Confirm framework and version support.
2. Interface first: land the DictionaryProvider contract and our own fallback implementation before evaluating the package.
3. Pilot: one non-critical surface — salutation on a profile edit form — with real locale coverage.
4. Decide: adopt, vendor the data and drop the code, or build natively. Record the decision as an ADR with the risk acceptance explicit.
5. Roll out key by key, with a test asserting that every persisted value maps to a current dictionary entry.

Operational Impact

Maintenance. The realistic plan is to assume we will own a fork. MIT licensing makes that legally trivial, and the code surface is small enough that a fork is a maintenance afternoon rather than a project — but it must be staffed and budgeted, not assumed away. Pin the version, vendor it if the maintainer goes quiet, and never let it float on a ^ constraint in a monorepo where a conflict can block security upgrades elsewhere.

Support. Effectively none. No issue-tracker corpus, no community, no Stack Overflow answers, and documentation that is likely a README. Our own team becomes the documentation owner; budget for writing internal usage notes, which is unusual for a package this small and is a real (if modest) cost.

Scaling. Runtime cost is a non-issue: in-memory array lookups, cacheable at build time, negligible memory. The scaling risk is organizational — as more teams adopt it, key naming and value semantics need governance, or we get the same drift the package was meant to prevent. Localization breadth is the growth axis to watch; each new locale is a translation contribution we may have to make ourselves.

Failure modes.

• Silent divergence: an upstream rename or added value desynchronizes the dictionary from existing database rows and constraints; submissions start failing validation without an obvious cause.
• Translation gaps: missing locales fall back to raw keys, which ship to production because nothing fails loudly.
• Framework-upgrade cliff: the next Symfony major arrives with no maintainer fix, forcing the fork at the worst possible moment.
• Composer stranding: constraint conflicts block patches in unrelated packages.
• Call-site lock-in: form types referenced directly everywhere, making replacement a refactor — mitigated entirely by the interface in step 2.

Ramp-up. Technically trivial: an engineer understands the package in an hour. The real cost is diligence — reading source and tests to substitute for absent ecosystem signal — and that cost lands on one person, typically the TPM's own engineering counterpart, before any code is written. Recommend a standing quality gate for dependencies of this profile: an active commit within twelve months, tests in CI, or an explicitly signed-off fork-and-own decision. This package should pass only under the third clause.