Foundation Laravel Package

Getting Started

Start by creating or using a Laravel Zero application — this package is not intended for standalone use. When you scaffold a Laravel Zero project (e.g., laravel-zero new my-cli-tool), laravel-zero/foundation is automatically installed as a dependency. Your first interaction will be in bootstrap/app.php, where the Application instance uses LaravelZero\Foundation\Application instead of Laravel’s full framework. From there, register custom Artisan commands in app/Console/Commands and load them via the App\Console\Kernel::commands() method — discovery happens automatically thanks to the kernel’s load() method.

Implementation Patterns

• Command Development: Define commands as usual with Artisan::command() or as dedicated classes extending Illuminate\Console\Command. Register them explicitly in Kernel::commands() — auto-discovery works for app/Console/Commands due to Kernel::load().
• Service Container Usage: Register bindings via $app->singleton(), $app->bind(), or $app->instance() in bootstrap/app.php or service providers — same API as Laravel, but restricted to CLI concerns (no middleware, sessions, or request handling).
• Testing Console Commands: Use Laravel Zero’s modified InteractsWithTestCaseLifecycle trait in your tests — it safely skips queue teardown if the Queue component isn’t installed, preventing crashes in minimal environments.
• Conditional Logic: Leverage the copied MAIN_REQUEST constant (from HttpKernelInterface) only for light-weight startup detection (e.g., detecting the entrypoint in complex workflows), but avoid expecting full HTTP semantics.

Gotchas and Tips

• Path Handling Quirk: Console\Kernel::load() uses app_path() without canonicalizing absolute paths — symlinked or relative paths (e.g., ../../app) may cause commands to not be discovered. Use realpath(app_path()) or store paths absolutely in bootstrap/app.php.
• Missing HttpKernelInterface: The Application class does not implement HttpKernelInterface. Never type-hint it, pass it to Symfony HTTP components, or expect handle() methods — attempts will fail at runtime with fatal errors.
• Queue Teardown Dependency: When testing with the Queue component, ensure illuminate/queue is loaded before tearDown() runs. Otherwise, the conditional skip means your queue workers may leak resources.
• Sync Script as Ground Truth: The bin/sync script in the repo documents all patches over upstream Laravel — if behavior deviates unexpectedly (e.g., constant naming, path logic), compare against it directly. It reveals why MAIN_REQUEST exists and how load() diverges.
• Zero Dependency Warning: With 0 dependents and low maturity, this package isn’t meant for general adoption. Avoid using it outside Laravel Zero — mixing it with laravel/framework in one project will cause class/interface conflicts and fatal errors.