Metadata Puli File Locator Laravel Package

Technical Evaluation

Architecture fit

This is an adapter, not a platform component. It implements the mi/metadata file-locator contract on top of a Puli resource repository, so a logical path (/app/assets/foo) resolves to a readable resource without the caller knowing the physical filesystem layout. The value is real but conditional: it only exists where Puli is already the authoritative path-resolution mechanism. The load-bearing dependency is Puli, not this package, and Puli has been unmaintained since roughly 2015 and was superseded by Symfony's file-locator/asset components and, in application contexts, Flysystem or Laravel's Storage facade.

A TPM should therefore treat the architecture question as a single yes/no gate rather than a scored trade-off: does the host application already run a Puli repository? If yes, this package is a plausible small piece of glue. If no — which is the case for essentially all greenfield and modern Laravel work — adopting it means importing a retired abstraction to obtain a locator you could write in an afternoon against Laravel-native filesystem APIs.

One correction to the framing: despite the "Laravel/PHP" description, there is no evidence of framework integration — no service provider, no facade, no publishable config. It is a plain Composer library that Laravel would consume through manual container wiring. That is not disqualifying, but it removes the "framework-friendly" argument from the business case.

Integration feasibility

Mechanically straightforward, ecosystem-wise unvalidated. Installation is composer require mi/metadata-puli-file-locator mi/metadata plus a runtime puli/repository (and optionally puli/cli, puli/discovery, puli/manager for puli.json-driven setups). The friction is almost entirely dependency resolution:

• Puli's constraint graph is pinned to PHP 5.x/7.x-era releases. On PHP 8.2+ expect to need --ignore-platform-reqs, a fork, or a compatibility shim — none of which are supportable long-term positions.
• Zero stars and zero dependents mean there is no public evidence that this installs cleanly against any downstream stack. There is no known-good composer.lock combination to copy.
• MIT licensing is the strongest signal here: it lets you fork, patch, and vendor without legal review, converting the risk from "blocked" to "absorbable."

Technical risk

High, and concentrated upstream rather than in this repository's own code.

1. Abandoned foundation. No security response, no PHP/Composer major tracking, no bug fixes.
2. Bus factor of one. A single-vendor package (MovingImage24) with no external contributors or dependents is functionally an internal artifact published incidentally. If it breaks, nobody outside that org is coming.
3. Unknown surface area. Without reading the source it is unclear whether this only maps paths or also parses/validates the metadata payload. Parsing would make metadata format drift a maintenance obligation you inherit.
4. Contradictory signals. The opportunity: 9.65 score is not corroborated by 0 stars and 0 dependents and should be treated as a scoring artifact (recency- or license-weighted), not adoption evidence. It must not be used to justify the decision.

Key questions

• What Puli version does it constrain, and does that constraint resolve on PHP 8.1/8.2/8.3 without platform-req overrides?
• Does it implement a Puli interface, or does it require the application to supply the repository/bindings? The contract direction determines how much Puli you must own.
• Is it a pure locator (path → file), or does it also read and validate MovingImage metadata structures? If the latter, which format version?
• Are there tests, and do they exercise the locator against a real filesystem fixture?
• Was this published for internal use and left public incidentally, or is external adoption intended? Commit history and README language answer this quickly.
• Is there a maintained MovingImage successor, or is this the current upstream state?

Integration Approach

Stack fit

Binary. Good where a Puli repository is already present and cannot be removed — Symfony 2.x/3.x-era codebases, some early Sylius installations, certain Behat/test-infrastructure stacks. Absent everywhere else. In a Laravel application the idiomatic equivalents are Storage::disk()->path(), FilesystemAdapter, or a small owned path resolver; all cover the same ground without importing a dead abstraction. My recommendation to stakeholders is a hard "no" unless the Puli prerequisite is already satisfied.

Migration path

If adopted, adopt it behind an interface you own. Define a narrow application-level contract — e.g. MetadataFileResolver::locate(string $assetId): string — and implement it with this package in exactly one adapter class. Everything else in the codebase depends on the interface, not on Puli. That confines Puli's types to a single file, makes swapping to symfony/file-locator or Laravel Storage a one-class change, and lets you vendor-patch the adapter without touching call sites. Budget half a day for the adapter plus tests; budget the Puli bootstrap as the genuine unknown.

Compatibility

Run composer require --dry-run in a branch before committing anything, and treat a clean resolve as a real gate. Check the PHP version matrix, Composer 2.x resolution, and transitive collisions — specifically webmozart/* packages, which modern Symfony and some Laravel packages also pull. Because Puli is frozen, any conflict is unresolvable without forking, so a conflict is a stop condition, not a negotiation.

Sequencing

1. Spike (1 day). Clone, read the locator implementation, inspect the constraint graph against your PHP version. Kill the initiative here if Puli will not resolve cleanly.
2. Prove (1–2 days). Stand up a minimal Puli repository with one binding and resolve one real metadata file end-to-end. Validate behavior before writing integration code.
3. Wrap (1 day). Implement the owned interface and adapter, with tests pinning resolved-path behavior.
4. Vendor. Fork under your org, tag a version, and point Composer at the fork so patches do not require merging against an inactive upstream.
5. Retire. File a follow-up to replace the adapter with a maintained resolver. Adopt this as a bridge, never as a resting state.

Operational Impact

Maintenance

Effectively zero from upstream; entirely yours in practice. MIT plus a small codebase keeps cost low if the locator logic is simple — but any MovingImage metadata format change or PHP major upgrade becomes an unassisted patch. Assign a named owner before adoption. The failure mode to avoid is an unloved package sitting on the critical path to asset resolution.

Support

No SLA, no issue activity, no community. Internal support is a source-reading exercise. The highest-leverage artifact you can produce is a two-page runbook: which Puli paths are bound, where bindings are configured, what the discovery cache does, and how to invalidate it. That document is worth more than the integration code.

Scaling

The locator is stateless and cheap; per-request cost is bounded by filesystem stat calls. The real scaling risk is Puli's discovery layer, which builds and caches a repository index. On large or rapidly changing file trees this dominates cost and invites cache-coherence bugs — especially across horizontally scaled workers each holding its own cache. Plan for cache warm-up at deploy time rather than lazy population inside request paths.

Failure modes

• Unresolved paths surface as Puli repository exceptions rather than "file not found," so logging and alerting must be adjusted to a different error semantic.
• Discovery cache staleness after a deploy or file move yields silent wrong-file resolution — worse than a hard failure.
• Composer resolution failure on a future PHP upgrade is a deploy-time break that blocks the build with no upstream fix available.
• Metadata format drift, if this package parses the payload, degrades quietly.
• Transitive webmozart/* conflicts appear nondeterministically as other packages update, an awkward incident class to debug.

Ramp-up

Steep relative to footprint. Puli's model (repositories, bindings, discovery, resource types) is not intuitive to engineers who know only modern Symfony or Laravel filesystem abstractions, and the upstream docs are archived. Expect about a day of reading before a mid-level engineer can safely modify the integration — a recurring tax on every future hire and team rotation. Against Laravel Storage, that number is zero. The gap between one day and zero is the honest carrying cost of this dependency, and the number a TPM should put in front of the decision-maker.