Php Loader Laravel Package

Getting Started

Install it with an exact constraint. With one star and zero dependents, do not rely on a floating version:

composer require morningtrain/php-loader --prefer-dist

Then pin the resolved version or commit in composer.json. If there is no stable tag, use dev-main#<commit-sha>.

Look first at:

1. composer.json — PHP version, autoloading, dependencies, Laravel auto-discovery.
2. README.md — intended usage and any initialization semantics.
3. src/Loader.php or the package’s single class — confirm:
   • Does it accept a file, a directory, or both?
   • Is loading recursive?
   • Does it use require or require_once?
   • What does “initializing classes” mean: new $class, a static init(), or an interface method?
   • What happens with constructors that require arguments?

Because the public API is small and adoption is low, wrap it immediately behind one application-owned class. That gives you a single place to adapt if method names or behavior differ from expectations:

<?php

namespace App\Support;

use MorningTrain\PhpLoader\Loader;

final class ModuleLoader
{
    public function __construct(private Loader $loader)
    {
    }

    public function load(string $path): void
    {
        // Adjust this call to the actual public method in src/Loader.php.
        $this->loader->load($path);
    }
}

First practical use case: replace scattered bootstrap require calls in a Laravel app. For example, load modular files from app/Modules during application registration:

// AppServiceProvider::register()
$this->app->singleton(ModuleLoader::class, function () {
    return new ModuleLoader(new Loader());
});

$this->app->make(ModuleLoader::class)->load(app_path('Modules'));

Keep class initialization out of register(). If the package can instantiate classes, do that in boot() after the container and config are ready.

Implementation Patterns

Split “load files” from “initialize classes.” File inclusion is usually safe in register(); instantiation often needs the container, config, routes, or database. Use register() to require files and boot() to initialize discovered classes.

Use it for module bootstrapping, not autoloading. This package loads PHP files; Composer handles PSR-4 autoloading. A good pattern is one bootstrap file per module:

// app/Modules/Billing/bootstrap.php
return function (Application $app): void {
    $app->register(BillingServiceProvider::class);
};

Then let your loader include all bootstrap.php files and invoke the returned closures yourself. This keeps dependency injection and ordering under your control.

If auto-initialization is supported, constrain the classes it can instantiate. Require a marker interface and a no-argument constructor:

interface Bootable
{
    public function boot(): void;
}

// Only point the loader at classes implementing Bootable.

If constructors need dependencies, do not use auto-initialization. Load the file, then resolve through Laravel:

app(MyBootstrapper::class)->boot();

Control ordering explicitly. Filesystem iteration order is not guaranteed. Prefix files by priority:

00-register-core.php
10-register-billing.php
20-register-reporting.php

If the package does not sort, sort the file list before passing it in or create one aggregate bootstrap file with explicit calls.

Use environment guards. Load development-only modules conditionally:

if (app()->environment('local', 'testing')) {
    $moduleLoader->load(app_path('Modules/Debug'));
}

Test with temporary fixture directories. Create files in tests/fixtures/modules, assert they were included, assert classes were or were not initialized, and clean up with require_once behavior in mind. This is especially important because the package has little external usage.

Keep a replacement path. The package is a thin wrapper around PHP inclusion. If maintenance stops, replacing it with an internal helper is trivial:

foreach (glob(app_path('Modules/*/bootstrap.php')) as $file) {
    require_once $file;
}

Do that if the package adds no meaningful behavior beyond require_once.

Gotchas and Tips

• Class redeclaration is the main risk. If a file declares a class already autoloaded by Composer, a plain require can fatal with “Cannot declare class.” Use the package only for side-effect files or ensure it uses require_once.
• Auto-initialization will fail on abstract classes, interfaces, traits, and constructors with required arguments. Inspect the source before enabling it. Prefer a marker interface and no-arg constructors.
• Relative paths resolve from the current working directory. Always pass absolute paths such as app_path(), base_path(), or __DIR__-based paths.
• Do not load user-writable directories. Loading every PHP file from a path is effectively code execution. Never point it at uploads, cache, or storage directories.
• Initialization during register() can fail silently or throw container errors. Move it to boot() unless the class is completely stateless.
• Return values from included files may be discarded. Do not rely on a bootstrap file’s return value unless you have confirmed the loader preserves it.
• Debug by logging the file list first. Before invoking the loader, log the exact paths and ordering. Afterward, use get_included_files() and class_exists() to verify what happened.
• Composer optimization can mask issues. Run composer dump-autoload -o and test a fresh deploy; classmap behavior differs from development.
• Deployment and OPcache. If you deploy by replacing files, reset OPcache so changed bootstrap files are picked up.
• There is no meaningful ecosystem safety net. Pin the commit, review src/ before use, and consider copying the class into app/Support with MIT attribution if it is genuinely small. That is often lower risk than depending on a one-star package in a critical bootstrap path.
• Extension points are likely limited to subclassing or wrapping. Do not edit vendor code. Put ordering, filtering, logging, and error handling in your own ModuleLoader wrapper so the package remains replaceable.