Php Loader Laravel Package

Technical Evaluation

Architecture fit

morningtrain/php-loader is a single-purpose utility: given a path, require/include a PHP file and optionally instantiate a class from it. In a Laravel codebase, this is a layer that Laravel already owns at three levels: Composer's PSR-4 autoloader handles class-level loading, the service container handles instantiation and dependency resolution, and ServiceProvider::load*From() handles registration of migrations, routes, views, translations, and commands. A TPM should treat the package as non-core, adjunct tooling — appropriate only in narrow cases where files genuinely cannot be autoloaded: user-supplied or tenant-supplied PHP drop-ins, a runtime plugin/module directory scanned from disk, legacy code being progressively migrated, or a package that must work in both Laravel and non-framework contexts (Morning Train publishes Laravel and WordPress-adjacent tooling).

It is not a substitute for autoloading, and any proposal to use it for application-domain class resolution should be rejected. Its only defensible architectural role is as a thin seam over filesystem-driven inclusion, ideally hidden behind an in-house interface.

Integration feasibility

Mechanically trivial: MIT-licensed, no evident dependency chain, likely a handful of files. composer require is a five-minute spike. The gating factors are not technical difficulty but confidence:

• 1 GitHub star, 0 dependents, package score 0.035. These are signals of a package published for the maintainer's own reuse rather than one with a user base.
• The opportunity score (25.86) hints at a real, if modest, demand niche — dynamic file/class loading outside the autoloader — but the package has not captured it.
• No evidence of a test suite, CI matrix, static analysis, or a declared PHP/Laravel version range in the metadata presented.

Because the surface is small, the source itself is the due-diligence artefact. A senior engineer can read the entire package in under an hour and make a definitive judgement; that is the cheapest possible risk reduction and should be a prerequisite.

Technical risk

• Abandonment / single-maintainer risk (high). With one star and no dependents, expect no inbound issue triage. You are effectively forking.
• Arbitrary code inclusion (high, if misused). Any loader that takes a path and requires it is a code-execution primitive. If a path or class name ever derives from request input, user content, or a database row, this becomes a remote-code-execution vector. The loader must be constrained to a fixed allowlist of directories with canonicalised paths.
• Contract ambiguity (medium). "Optionally initializing PHP classes" implies constructor instantiation without a container — meaning no DI, no resolution of constructor dependencies, no singleton lifecycle. Confirm whether it returns instances, stores them, or discards them.
• Long-lived process state (medium). If the loader caches instances internally, behaviour under Octane, Horizon, or queue workers may diverge from fpm: stale instances, memory growth, or state leaking between requests.
• Load-time side effects (medium). File inclusion executes top-level code. Errors become fatal E_COMPILE_ERROR/E_ERROR, not catchable exceptions, unless the loader converts them — verify.

Key questions

1. What PHP and Laravel version constraints are declared, and is Laravel 11/12 supported?
2. Is there a test suite, and does CI run it across the supported matrix?
3. Does it use require or require_once, and how does it prevent double-inclusion / class redeclaration?
4. How are missing files and thrown errors surfaced — exceptions, false, or fatal?
5. Are paths canonicalised and confined to a configured root?
6. Does it cache loaded classes or instances across calls?
7. Is this package used internally at Morning Train (de facto dogfooding), and what is the release/versioning history?
8. Does it work outside Laravel, or does it depend on framework helpers?

Integration Approach

Stack fit

Poor fit for standard Laravel application code; acceptable fit for module/plugin discovery, tenant-scoped extensions, or a legacy bridge layer. If the codebase is conventional Laravel, the honest recommendation is: do not adopt, replicate the ~30 lines you need internally with tests and a clear contract.

Migration path

Adopt behind an adapter, never directly:

1. Define an in-house FileLoader interface (load(string $path): void, loadClass(string $path, string $class): object) in your domain layer.
2. Implement it with a thin wrapper over morningtrain/php-loader — or, preferably, over native require_once + new $class() if the package's added value is just error normalisation.
3. Bind the wrapper as a singleton in a service provider. Inject the interface; never call the static/global API from controllers or models.
4. Pin the exact version in composer.json and enable Dependabot/Renovate so a hypothetical upstream release is reviewed, not silently pulled.

This keeps the swap cost near zero if the package is abandoned — which, on the evidence, is the base case.

Compatibility

Verify PHP constraint against your runtime, and confirm the loader does not rely on framework globals (app(), base_path()) if you intend to use it in queue workers or CLI contexts. Check for conflicts with OPcache settings and with composer dump-autoload --optimize (classmap-authoritative mode will not interfere, but any dynamic class name resolution should be validated under it).

Sequencing

1. Source review + spike (1–2 days). Read the code; write a 10-test harness covering missing file, double include, bad class, path traversal attempt, and constructor with dependencies.
2. Decision gate. If the review shows no error normalisation or path confinement, build in-house instead — the package adds no value and imports risk.
3. Pilot (1 sprint). Single low-traffic module behind the adapter, non-production first.
4. Production rollout, contingent on logging around every dynamic include (path, caller, outcome) so inclusion becomes observable.
5. Re-evaluate at 90 days against fork-and-own cost.

Operational Impact

Maintenance

You will own this. No evidence of a security policy, release cadence, or dependency-update automation. Budget for a periodic manual review — cheap given the size, but non-zero, and it must be scheduled or it will not happen. Consider vendoring or forking into an internal namespace to make ownership explicit.

Support

Effectively none. GitHub issues on a 1-star repository should be assumed unanswered. Internal documentation is mandatory: what the loader does, where it may be called from, and the allowlisted roots.

Scaling

Runtime cost is negligible in absolute terms, but the model is eager, not lazy. Loading N files on every request scales linearly where Composer's autoloader scales with classes actually used. Keep usage bounded and out of hot paths; avoid it in middleware or per-request bootstrapping.

Failure modes

• Fatal error on a missing or malformed file — request death, not a handled exception.
• Class redeclaration on double inclusion if caching semantics are unclear.
• Autoloader collision when a dynamically loaded class shares a namespace with a PSR-4-mapped one.
• Initialisation-order bugs: included files with top-level side effects (hooks, registrations) run at include time, making behaviour order-dependent.
• Path traversal → arbitrary code execution if any input is untrusted.
• Under Octane/queue workers, retained instances causing stale state or memory growth.

Each of these needs a named owner and a mitigation before production: path allowlist, require_once semantics confirmed, structured logging, and a documented "trusted input only" rule.

Ramp-up

Minimal — an hour for a mid-level engineer to understand the API. The real onboarding cost is policy, not code: teams must know when not to reach for it. Without that, it becomes a convenient bypass around the container and autoloader, and the codebase drifts toward filesystem-coupled loading that is harder to test, refactor, and statically analyse. Document the exception, not just the tool.