Manager Laravel Package

Technical Evaluation

Architecture fit

• puli/manager is not a Laravel package. It is a framework-agnostic Composer library that owns read/write access to a project's puli.json manifest and the associated .puli/ metadata store. There is no service provider, facade, config publisher, or Artisan command — Laravel fit is zero without bespoke glue.
• Architecturally it sits between puli/repository (the on-disk key-value metadata store) and puli/cli / puli/discovery. Its job is validating, mutating, and persisting path-mappings and package bindings. That is a narrow configuration-management concern, not an application runtime concern.
• The problem it solves — resolving /@vendor/package/resource URLs across package boundaries — is now addressed by Symfony Flex recipes, Composer 2's bin/extra conventions, and Laravel's own Vite manifest plus asset()/resource_path() helpers. The abstraction is obsolete relative to our stack.

Integration feasibility

• Technically installable (composer require puli/manager), but the transitive graph is a graveyard: webmozart/json, webmozart/key-value-store, puli/discovery, puli/repository are all archived. Composer will resolve, then pin us to PHP 5.x/7.x-era constraints.
• Symfony 2/3 components in the dependency chain collide directly with Laravel 9/10/11 (Symfony 6/7). Installation would require --ignore-platform-req suppression, which is disqualifying for production.
• The MIT license is clean; that is the only unambiguously positive signal.

Technical risk

• High. Last release 2016-01-14, upstream archived, no CVE pipeline, no PHP 8 support. The package metadata itself is degraded ("Repository: unknown"), which is a reliable signal of decay.
• Writes are file-based and non-transactional. An interrupted puli.json write can desync the manifest from the .puli/ store with no recovery path.
• The 1.08 score is consistent with our independent read: viable only as a migration target, never as an adoption.

Key questions

• Do we own an existing codebase that already depends on Puli, or is this a greenfield evaluation? (Greenfield should be closed out immediately.)
• Which PHP and Laravel versions are in scope, and is any current dependency still pulling puli/* transitively?
• Is a build-time-only translation (Puli mappings → Vite aliases / config/ entries) sufficient, or does runtime resolution occur per-request?
• Can we tolerate in-house ownership, or must this be removed entirely within one release cycle?
• What is the business justification for the path-mapping abstraction versus framework-native asset handling?

Integration Approach

Stack fit

• None out of the box. Any integration is custom: a service provider binding a Puli factory, a manifest reader, and an exporter that maps Puli resource URLs onto Laravel paths. The existing puli/symfony-bridge is a DI/templating integration for Symfony and does not transfer.
• Best-fit posture: treat Puli as a build-time configuration source only — never instantiate it in the request lifecycle.

Migration path

1. Freeze: no new Puli manifest entries; pin the existing dependency lockfile.
2. Inventory: enumerate every path-mapping and binding in puli.json, plus all call sites resolving Puli resource URLs.
3. Translate: map each entry to a Laravel-native equivalent — Vite alias, config/view.php paths, filesystem disk, or public_path().
4. Dual-run behind a feature flag; diff resolved paths against Puli output.
5. Cut over, remove puli/* from composer.json, regenerate autoloads, delete .puli/.

Compatibility

• PHP 5.x–7.x only; Symfony 2/3 constraints. Not compatible with Laravel 9+ without platform-requirement suppression. Do not attempt an in-place upgrade — there is no newer Puli to upgrade to.

Sequencing

• Assessment and codebase inventory (1 sprint) → translation layer (1–2 sprints, effort scales with manifest size and URL call-site count) → parallel validation (1 sprint) → removal and cleanup (0.5 sprint). Total: roughly 3–5 sprints for a mid-size application, dominated by call-site discovery rather than the library itself.

Operational Impact

Maintenance

• Zero upstream maintenance. Archived repository, no successor, no security response. Budget for full in-house ownership if retained; otherwise treat as disposable and schedule removal.

Support

• No community. 68 stars and no maintainer means Stack Overflow coverage is stale and the primary documentation site (puli.io) is offline. Incident debugging will be archaeology.

Scaling

• Acceptable at build time; unacceptable per-request. The manifest parse plus file-based key-value lookups add I/O on every invocation, with no caching story. If resolution must happen at runtime, this is a hard blocker irrespective of scale.

Failure modes

• Manifest corruption on interrupted write; silent desync between puli.json and .puli/.
• Path mappings resolving to the wrong package after a Composer update, producing missing-asset 404s that surface as front-end bugs rather than config errors.
• Hard failure on any PHP runtime bump (8.0+) or Laravel major upgrade.
• Dependency-resolution failure at composer install when unrelated packages modernize.

Ramp-up

• Deceptively steep. The resource-URL abstraction (/app/views/foo.html, /@vendor/pkg/...) is non-obvious and there is no current documentation to learn from. Expect 2–3 days per engineer for conceptual fluency, with high knowledge-loss risk since nothing can be Googled. Prefer to keep the blast radius small: one or two engineers own the migration, and nobody learns Puli beyond what is needed to remove it.