Lody Laravel Package

Technical Evaluation

What we are actually evaluating. Lody is a class-and-file discovery utility, not a framework extension. It exposes a static facade (Lody::files, Lody::classes) that composes Symfony Finder, Composer's vendor/composer/autoload_psr4.php mapping, and Laravel's LazyCollection to return two custom collection types with chainable filters: classExists, isAbstract/isNotAbstract, isInstanceOf/isNotInstanceOf, hasTrait/doesNotHaveTrait, and hasMethod/hasStaticMethod/hasNonStaticMethod. There is no config file to publish, no migration, no persistence, and no service-provider surface beyond three optional static resolver registrations. The evaluation is therefore narrow and product-shaped: do we have a recurring need for convention-based discovery, and can we absorb a small single-maintainer 0.x dependency to get it?

Architecture fit.

• Strong fit for modular monoliths and plugin-style extension points where implementations live in agreed directories (app/Plugins, app/Workflow/Nodes, app/Billing/Handlers) and qualify via an interface, an abstract base, or a PHP attribute. Discovery replaces hand-maintained registration arrays — the classic source of merge conflicts and forgotten registrations in multi-team Laravel repositories.
• Good fit for internal platform glue: auto-registering Artisan commands, admin resources, export handlers, webhook processors, or health checks by trait or interface.
• Weak fit for a conventional CRUD product where a ten-line explicit list already works. Discovery there is added indirection with no user-facing payoff.
• Marginal fit outside Laravel. Lody::setBasePath() makes it usable, but the value proposition leans on base_path() and Laravel collections. A non-Laravel PHP service should use Symfony Finder directly.

Integration feasibility. Installation is one composer require and works on first call. The real effort is policy, not code: naming the discovery convention, defining and owning the qualifying contract, deciding whether discovery runs at boot or against a deploy-time manifest, and documenting the plugin contract for contributors. A competent Laravel engineer reaches a proof of concept inside a day. The costed work is the wrapper, the manifest cache, observability around count drift, and the authoring guide — roughly a one-to-two-week increment including tests, not a one-line adoption.

Technical risk.

• Supply chain and bus factor (high). 95 stars, zero dependents, 0.x versioning, single maintainer. This is a well-crafted utility with a small audience, not a community standard. Adopt only with an exact pin and a written exit plan; the low overall score here against a much higher opportunity score is a signal to replicate the pattern defensively rather than depend on it uncritically.
• Upgrade cadence coupled to Laravel majors. The release history is a consistent pattern: add the newest Laravel major, drop the oldest (v0.4.0 → Laravel 10, v0.5.0 → Laravel 11, v0.6.0 → Laravel 12, v0.7.0 → Laravel 13 while dropping Laravel 10). Reasonable for the maintainer; it means our framework upgrade calendar inherits their release timing, and any application lagging a major ends up pinned to an unsupported line.
• Silent under-discovery (highest severity). PSR-4 reverse-resolution is a heuristic. Files with multiple classes, conditionally declared classes, classmap-only or --classmap-authoritative autoloading, or namespaces that do not map cleanly to a directory resolve to names that fail classExists() and vanish without an error. v0.7.1 formalises this behaviour: a missing path returns an empty collection rather than throwing. For a plugin registry, "quietly registered fewer handlers than exist" is the failure mode that costs us production incidents.
• Autoload side effects during discovery. Instance and trait filters autoload candidates. One class with an include-time fatal (missing optional dependency, bad use, expensive static initializer) can break the boot path or slow it. Discovery is unsafe against untrusted or partially installed third-party code.
• Cost profile. Filesystem traversal plus reflection per candidate scales with files scanned. Unacceptable per request; acceptable once per worker boot, or once per deploy into a cache.

Key questions for engineering before we commit.

1. Where does discovery execute — every boot, queue-worker boot, or a manifest built at deploy? What is the measured cost at 100 / 1,000 / 10,000 files?
2. What is the qualifying contract (interface, abstract base, PHP attribute), and which team owns changes to it?
3. Do we scan first-party directories only, or vendor as well? If vendor, do we accept autoloading code we do not control?
4. Does production use optimized or authoritative classmaps, and does the deploy run composer dump-autoload before cache warm?
5. Who owns the pin-and-fork policy for a 0.x single-maintainer dependency, and what is the trigger to vendor or reimplement (~200 lines against Symfony Finder)?

Integration Approach

Stack fit. Native to Laravel 10–13 and PHP 8.1+; no PHP extension requirements, no published configuration, MIT licensed. It fits our existing stack without a Composer constraint fight, which is the main reason it is viable at all.

Migration path. Adoption is additive and reversible — nothing in the package touches existing wiring until we call it. Recommended path: (1) pick exactly one domain with an existing hand-maintained registry, (2) introduce Lody behind an internal DiscoveryService wrapper, (3) keep the old registry in place and assert both produce the same set, (4) flip the call site once parity holds, (5) replicate the wrapper across the next two domains without touching their registration code. This also gives us the seam to swap the implementation later without a repo-wide refactor.

Compatibility.

• Pin an exact version; do not float on ^0.7.
• Verify our Laravel major is on the supported line today, and record the next drop date against the maintainer's cadence.
• Confirm production autoload mode. If we run --classmap-authoritative, validate discovery against a staging build before trusting it — this is where the heuristic breaks quietly.
• Keep the wrapper free of Lody types in its public signatures so a future fork or reimplementation is a single-file change.

Sequencing.

1. Week 1 — spike and measure. Rebuild one existing registry through Lody in a branch; measure discovery time and memory at realistic and 10x file counts; capture the empty-collection-on-missing-path behaviour in a test.
2. Week 1 — decide the contract. Agree the qualifying interface/attribute and its owner; this is the durable design decision, not the library.
3. Week 2 — wrapper and manifest. DiscoveryService plus a deploy-time manifest cache (Artisan command writing discovered classnames to a cached file), with a boot-time fallback for local development.
4. Week 2 — observability and docs. Log discovered-vs-expected counts, add a health check for zero-discovery, and write the plugin authoring guide.
5. Week 3+ — rollout. Two or three domains maximum in the first increment; explicitly exclude vendor scanning.

Operational Impact

Maintenance. Low code surface, non-trivial dependency surface. No migrations, no runtime state, no background jobs. Our ongoing cost is the pin, the framework-upgrade coupling, and the wrapper we own. Budget roughly a half-day per Laravel major to validate the upgrade, plus a standing decision to fork or reimplement if the maintainer stops releasing.

Support. Community-only, single maintainer, no vendor SLA. Our wrapper is the support boundary: teams file against us, not GitHub. That means we own triage for the failure modes below, and we should carry a tested fallback (a small Symfony Finder implementation of the same interface) from day one rather than writing one during an incident.

Scaling. Discovery cost is O(files scanned) with autoload and reflection per candidate. It does not belong on the request path. The scaling answer is structural: build a manifest once at deploy, cache it, and at runtime read the manifest rather than the filesystem. That keeps boot cost flat as the codebase grows and makes discovery behaviour identical across web and queue workers. Without the manifest, expect boot-time regressions that surface as slow cold starts and unpredictable queue worker spin-up.

Failure modes to instrument.

• Silent under-discovery — new plugin not registered, no error. Mitigation: log discovered count, alert on zero, and assert expected minima per directory in CI.
• Missing/renamed path returning an empty collection — v0.7.1 behaviour converts a typo into a no-op. Mitigation: validate paths at manifest build time and fail the deploy, not the request.
• Autoload fatal during discovery — a broken class kills the boot path. Mitigation: run discovery at deploy with a hard failure, never inside a request; isolate third-party scanning entirely.
• Laravel major skew — package drops our framework version. Mitigation: pin, track the release cadence, and keep the wrapper implementation-agnostic.
• Autoload-mode drift — a deploy changes to authoritative classmaps and discovery quietly narrows. Mitigation: assert parity between manifest and a fresh scan in CI.

Ramp-up. Engineers familiar with Laravel collections will read the chainable API in minutes; the README is sufficient and the filter set is self-describing. The genuine onboarding load is on plugin authors, who must know the directory convention, the qualifying contract, and that classes must be autoloadable and PSR-4-resolvable to be discovered at all. That guide is the deliverable most likely to be under-scoped. Allocate a day for authoring it and a review pass with the first consuming team; without it, the convention degrades into tribal knowledge and the discovery mechanism becomes less predictable than the registry it replaced.