Puli Metadata File Locator Bundle Laravel Package

Product Decisions This Supports

• Config/resource discovery strategy (build vs. buy vs. defer). The package solves one narrow problem — resolving logical resource paths (e.g. /vendor/package/config/validation.yml) to real filesystem paths so Symfony's metadata loaders can find them. The PM decision it informs is how your platform lets packages and tenants ship their own config: hardcoded paths, framework-native conventions, or an indirection layer. A short spike is enough to learn whether that indirection is worth owning.
• Roadmap: plugin/extension architecture. If your roadmap includes third-party or per-tenant modules contributing validator, serializer, Doctrine, translation, or routing metadata, this bundle is a reference implementation of the pattern. Use it to validate the developer experience of "packages declare resources by logical name" before committing that as a public contract — once packages ship logical paths in their config, you owe them backward compatibility.
• Deployment-target portability. Abstracting metadata location away from the filesystem keeps the same artifact runnable from a read-only container, a PHAR, a mounted config volume, or a tenant overlay directory. Relevant if on-prem, air-gapped, or multi-tenant deployment is on the roadmap.
• Migration sequencing (brownfield bridge). For a legacy Symfony 2.x/3.x app, this is a bridge that lets you move metadata resolution behind a locator now and swap the underlying repository later, instead of blocking abstraction work behind a full framework upgrade.
• Deprecation/adoption triage. With 0 stars, 0 dependents, and no release cadence, the actionable decision is fork-and-own vs. replicate in-house. The functional surface is a thin decorator around file_locator; a bespoke service is often cheaper than inheriting an orphaned dependency tree.
• Explicitly not a Laravel decision. There is no MetadataFileLocator, no bundle kernel, and no compiler pass to hook in Laravel; the integration point does not exist. If the roadmap is Laravel, the analogous decision — package-provided config, resource_path(), vendor:publish, composer.json extra.laravel discovery — is already solved natively and should be treated as a separate evaluation.

When to Consider This Package

Adopt only when all of the following hold:

• You are already running Puli (webmozart/puli) in a Symfony 2.x/3.x application and need Symfony's metadata loaders to see Puli-resolved paths — without this bundle, file_locator only understands filesystem paths and @Bundle notation.
• You have verified composer resolution in a throwaway branch against your actual PHP and Symfony constraints; expect legacy PHP floors and conflicting symfony/* requirements.
• You have a named internal owner who will vendor or mirror the code, pin it, and patch it — you are adopting source, not a support contract.
• The blast radius is contained to metadata loading (validator, serializer, Doctrine mapping), not request routing or security policy.
• MIT licensing is compatible with your distribution model (it is, for essentially all commercial cases).

Look elsewhere — the default position — when:

• Greenfield, Laravel, or Symfony 4+/5+/6+/7+. Puli is effectively end-of-life and this bundle has no maintainer and no downstream users to absorb compatibility breakage on your behalf.
• You need a security response commitment. Zero dependents means zero upstream pressure to patch; a CVE in the transitive Puli stack becomes permanently yours.
• The real requirement is "let packages ship config." Framework-native paths, %kernel.project_dir% parameters, Laravel's publish/discovery mechanisms, or a small custom FileLocatorInterface decorator solve it without an abandoned dependency.
• You are evaluating this as a long-term architectural commitment rather than a time-boxed migration bridge. Supply-chain and bus-factor risk outweigh the convenience.
• Any stakeholder will ask "who maintains this?" and the honest answer is "we would."

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed integration layer that lets metadata files be addressed by logical name rather than physical path — a de-risking input to a decision we need to make anyway: whether resource indirection belongs in our platform contract. License cost is zero; ownership cost is not. Upstream has no active maintainer and no downstream users, so I recommend treating it as a time-boxed spike or a fork we own, never as a dependency we adopt. Ask: approve one engineer-week to prototype behind a feature flag, with a documented exit plan and no exposure in shipped package contracts until we commit to owning that contract.

To engineering: The bundle decorates Symfony's file_locator so LoaderInterface implementations resolve Puli-style resource paths. That is a narrow, well-understood seam — which is also the argument against taking the dependency: we can reproduce it in-house in less time than it takes to audit and pin the transitive Puli tree. Recommendation: spike it to validate the developer experience, then either fork with a named internal maintainer in the repo, or reimplement the decorator against the current Symfony service definition. Note for the record: this is a Symfony bundle, not a Laravel package — in a Laravel codebase there is no integration seam, and the requirement maps onto native config publishing and resource_path() instead. In either case, do not sequence this ahead of a framework upgrade; that work deletes this dependency regardless.

Bottom line for the decision log: Evaluate, don't adopt. Use it to answer the architecture question, budget for ownership from day one, and document the metadata resolution order explicitly — that knowledge leaves with whoever introduces it.