Foundation Laravel Package

Getting Started

• composer require innmind/foundation — but check your PHP version first. As of 2.2.0 the package no longer supports PHP 8.4; you need 8.1–8.3. If composer require fails with a constraint conflict, run composer why-not innmind/foundation 2.2.0 before assuming it's a Laravel conflict.
• There is no Laravel service provider, no config/foundation.php to publish, and no facade. This is a framework-agnostic package that ships its own bootstrapping/composition concepts. Do not expect php artisan vendor:publish to do anything useful.
• First place to look: the README, then the root of src/ — the entry points are the bootstrap/composition classes, not controllers or models. Skim the public interfaces before reading implementations.
• Best first use case: a single, framework-independent unit — a console command, a queued job's domain logic, or a small subsystem you want to unit-test without booting Laravel. Prove the value there before considering it for anything the HTTP layer touches.
• Sanity check before committing: composer show innmind/foundation and confirm the resolved version. If you're on PHP 8.4 you'll be pinned to 2.1.0 or lower, and you should decide that deliberately rather than discovering it in CI.

Implementation Patterns

• Adapter, not integration. The package knows nothing about Laravel's container. Wrap its objects in a small service class and bind that in a service provider. Your controllers, jobs, and Livewire components should never type-hint a foundation class directly — that keeps the blast radius of a future upgrade small.
• Composition root at the edge. Construct foundation objects inside a dedicated factory or service provider register()/boot(), then inject the result. Avoid building them lazily inside request handlers where failures surface mid-response.
• Keep it out of Eloquent. Don't mix foundation types into models, casts, or accessors. If you need to persist something, convert at the boundary — a repository or a DTO — so the ORM stays a Laravel concern and the package stays a domain concern.
• Lean on it for testability. The main day-to-day payoff is being able to test a unit with new and no RefreshDatabase, no CreatesApplication, no container. Write those tests first; they're what justifies the dependency.
• Constraint discipline. Pin "innmind/foundation": "^2.2" and, in CI/Docker/Herd, pin PHP to 8.3.*. Add composer update --dry-run to your pre-merge checks — this is the sort of transitive dependency that gets bumped by an unrelated composer update and takes the build down.
• Upgrade path if you need 8.4. Stay on 2.1.0 with a composer.json comment or an ADR explaining why, and watch upstream for a re-add. Don't fork for a version constraint.

Gotchas and Tips

• 2.2.0 is a minor release with a platform-level consequence. "Drop PHP 8.4 support" means Composer will refuse to install this version on 8.4 at all — not a runtime warning, a resolution failure. Semver says minor, but for anyone on 8.4 it's breaking. Audit your CI matrix, Dockerfile base image, Herd/Valet/Sail PHP version, and any monorepo packages with a different php constraint.
• No Laravel observability. No Telescope integration, no debugbar panel, no log channel wiring. Failures typically throw from the composition root before the framework has fully booted, so storage/logs/laravel.log may be empty. Reproduce in a plain php script.php and read the raw stack trace.
• Extension points are the package's own interfaces, not Laravel's container. Blindly calling $this->app->bind(SomeInnmindInterface::class, ...) will appear to work and then be ignored, because the package resolves through its own mechanism. Read how the package wires itself before assuming Laravel's container participates.
• Dependency weight. Check composer why innmind/foundation — if it only arrives transitively and you're not calling it, remove the caller rather than adopting the constraint.
• Debugging tip: when a method returns something unexpected, dump the concrete class (dd($value::class)), not just the value. These packages lean on small value objects and interfaces, and var_dump output is uninformative compared to knowing which implementation you actually got.
• Pin exact versions in libraries you publish. If you maintain a package that depends on this, a ^2.1 constraint silently became un-installable for PHP 8.4 consumers on this release; consider >=2.1 <2.2 || ^2.2 style ranges only if upstream confirms 8.4 returns.