Metadata Puli File Locator Laravel Package

Product Decisions This Supports

• Build vs. buy (and "buy vs. absorb"): Frames whether to adopt a metadata-backed Puli file locator as glue versus writing — or maintaining — a small custom resource-path resolver. Because the package is MIT and tiny, the real decision is not "buy or build" but "absorb and own" versus "replace with a maintained abstraction."
• Feature enablement: Supports evaluation of multi-package asset lookup, theme/plugin resource discovery, CMS/media asset routing, and config/template resolution across storage roots — use cases where resources are addressed by logical path rather than hardcoded filesystem location.
• Roadmap: Informs whether to standardize on Puli-style resource abstraction for modular Laravel apps, or keep path handling app-specific (Laravel Storage, Flysystem, symfony/file-locator).
• Architecture modernization: Provides a lens for legacy PHP/Symfony 2.x/3.x-era codebases already committed to Puli — deciding whether to bridge, containerize behind an owned interface, or plan retirement.
• Migration sequencing: Supports treating the package (and Puli) as a bridge, not a resting state, with a follow-up to swap the adapter for a maintained resolver.
• Opportunity signal: The 9.65 opportunity score suggests a valuable niche, but 0 stars and 0 dependents mean this is an investigation candidate, not a proven standard. It should be treated as a scoring artifact, not evidence of adoption.

When to Consider This Package

• Consider it if you already run a Puli repository as the authoritative path-resolution mechanism in the host application (typical of Symfony 2.x/3.x-era stacks, some early Sylius, and certain Behat/test-infrastructure setups from that period), have metadata describing resource locations, and want MIT-licensed glue rather than a custom locator.
• Consider it for Laravel/PHP apps with modular packages, plugins, themes, or multi-root storage where logical paths must resolve consistently — provided the Puli prerequisite is already satisfied by an existing dependency you cannot remove.
• Consider it only if your team can vendor, test, and own a small, effectively unmaintained dependency. Low adoption requires budget for code review, PHP-version compatibility checks, and a named owner.
• Look elsewhere if you need a widely adopted, actively maintained filesystem abstraction, Laravel-native Storage integration, community support, or security guarantees. The idiomatic equivalents — Storage::disk()->path(), Illuminate\Filesystem\FilesystemAdapter, symfony/file-locator, or a thin custom resolver — cover the same ground without importing a retired abstraction.
• Look elsewhere for greenfield projects unless Puli is already a strategic dependency. Puli has been unmaintained since roughly 2015, and its transitive webmozart/* constraints can collide with modern Symfony and Laravel packages; conflicts are unresolvable without forking.
• Gate aggressively: run composer require --dry-run against your actual PHP/Composer matrix in a branch before committing. A clean resolve is a genuine gate, not a formality — because Puli's constraint graph is frozen at PHP 5.x/7.x-era releases, expect --ignore-platform-reqs, a fork, or a polyfill layer on PHP 8.2+, none of which are supportable long-term positions.

How to Pitch It (Stakeholders)

• Executives: This is a small, MIT-licensed infrastructure package that could eliminate custom file-path logic in modular PHP/Laravel products by letting resources be addressed by logical path. It is not a proven market component — zero stars, zero dependents, and an unmaintained foundation — so position it as a low-cost, time-boxed spike, not a platform commitment. MIT licensing is the strongest signal: it converts the integration risk from "blocked" to "absorbable."
• Engineering: It is a thin adapter implementing a metadata file-locator contract on top of a Puli repository — path-based abstraction is the load-bearing dependency, and Puli is dead upstream. Fit is binary: good if a Puli repository already exists, absent otherwise. Adopt behind an application-owned interface (e.g., MetadataFileResolver::locate(string $assetId): string) so Puli's types are confined to one adapter and swapping to Laravel Storage or Symfony's locator is a one-class change. Verify PHP version, Composer 2.x resolution, and webmozart/* collisions first; vendor a fork under your org so patching doesn't require a PR against an inactive upstream. Budget about a day of reading before a mid-level engineer can safely modify the integration — versus near-zero ramp-up for Laravel Storage.
• Recommendation: Run a one-day spike (read the locator source, check the Composer constraint graph), a one-to-two-day proof against a real multi-package asset use case, then wrap it in an owned interface with tests. If it removes custom locator code and resolves end-to-end, vendor it with a named owner and a short runbook (Puli bindings, discovery cache invalidation, error semantics); otherwise build a thin internal locator or use Laravel-native filesystem APIs. Adopt it as a bridge, never as a resting state — file the retirement follow-up on day one.