Foundation Laravel Package

Getting Started

Orchestra Foundation (orchestra/foundation) is not a package you composer require into an existing Laravel app. It's the runtime/bootstrap layer for Orchestra Platform — a modular Laravel admin/CMS framework. You consume it as the whole application skeleton.

Minimal path:

composer create-project orchestra/platform my-app
cd my-app
php artisan orchestra:install
php artisan serve

orchestra:install publishes config, runs the extension/ACL/memory migrations, and seeds the default admin role and user. Log in at /admin (prefix configurable).

Where to look first, in this order:

1. config/orchestra/foundation.php — extension paths, admin route prefix, auth guard.
2. config/orchestra/extension.php — where extensions are discovered and installed from.
3. The extension directory — where day-to-day work actually happens.
4. The published migrations for users, roles, permissions, extensions, and memory tables.

First use case to anchor your mental model: stand up the skeleton, log in to /admin, walk the Extensions page, install and enable one example extension, then confirm the admin menu, ACL gate, and theme all render. That single loop — extension → admin surface → permission gate — exercises the entire stack and is the fastest way to learn how the pieces fit.

Before any of this, pin your Laravel major and pick the matching Foundation release line. Read tagged releases, not the README — Foundation histories track specific Laravel majors.

Implementation Patterns

Treat every feature as an extension. The whole point of the package is the module model: a feature is an installable unit with its own service provider, routes, migrations, config, and optional admin UI. Build inside the extension boundary so a feature can be enabled, disabled, or extracted later. Keep domain logic in portable service classes; keep Foundation-specific wiring (routes, menus, ACL registration) at the edges.

Resource-oriented admin routing. Admin CRUD goes through Foundation's resource routing plus reusable layouts/forms, not hand-rolled controllers. Register a resource with its routes and let the scaffolding supply list/create/edit views. Lean on the provided form macros and layout partials instead of rebuilding Blade components — the payoff is consistency across modules and less surface to maintain.

// extension service provider — the manifest for everything
$this->app['router']->resource('admin/reports', ReportController::class);

ACL as a first-class registration step. Every resource and menu item should declare its permission in the extension's service provider, not inline in controllers. Roles and permissions are seeded and managed through the admin surface, so permissions must resolve at boot. Cross-check new resources against the default admin role so you don't lock yourself out.

Memory for configuration, not the DB. Use Orchestra\Memory for per-extension settings and admin-tunable options — that's exactly what it exists for. Resist adding your own settings table.

Themes via the unified API. Register admin and frontend themes through Foundation's theme layer so they appear in the admin theme switcher. Don't hardcode theme paths into views.

Day-to-day integration tips:

• Keep a single extension service provider as the manifest; everything routes through it.
• Use the framework's asset/notifier/widget helpers rather than re-implementing menus or flash messages.
• When bridging to native Laravel features (policies, Sanctum, queue jobs), do it inside the extension, not by reworking Foundation bootstrapping.
• If integrating alongside an existing app, isolate behind a route prefix and a separate DB connection and run it as a satellite admin service — do not graft Foundation onto a production Laravel app.

Gotchas and Tips

Version coupling is the biggest one. The Composer constraint is a hard lock — forbid automatic major Laravel upgrades in CI and test each minor bump against a spike. A Laravel security release that Foundation hasn't caught up to will freeze you on an unsupported framework.

Don't edit vendor code. Maintain a thin, documented patch layer for Foundation itself. With effectively one upstream maintainer, your realistic posture is fork-and-own; vendor edits make that fork painful later.

orchestra:configure-email encryption quirk (v5.1.1). email.username no longer needs to be encrypted when running the configure command. If you're on an earlier patch and your mail config looks mangled, this is likely why. Check the release notes for your exact version before debugging your SMTP settings.

Two idioms, one codebase. The most common failure mode is new engineers applying native Laravel conventions (policy-based authorization, package auto-discovery, Livewire/Inertia layouts) inside a Foundation app, producing inconsistent authorization and duplicated admin chrome. Write an ADR and an onboarding doc during the spike and enforce the extension boundary in code review.

Debug checklist when the admin surface misbehaves:

1. Is the extension enabled (not just installed)? Menu items and routes don't appear for disabled extensions.
2. Did you re-run migrations for the extension, and are the ACL rows seeded?
3. Clear compiled/cached artifacts (orchestra/route/config caches) after changing providers or routes.
4. Check the admin route prefix in config/orchestra/foundation.php — a wrong prefix silently 404s everything downstream.
5. Verify the auth guard the admin area expects matches auth.guards in config.

Module governance matters early. The extension model makes it trivially easy to spawn many small modules; without ownership and naming conventions you'll multiply the maintenance surface faster than one team can absorb. Set the rules (owner, prefix, dependency direction) before the module count grows.

Escape hatch. If the bet fails, the exit cost is a rewrite of the application's structural seams — not a package swap. Keep domain logic in portable classes so migrating off Foundation becomes a routing/wiring exercise rather than a re-derivation of your business logic.

Extension points to lean on: extension service providers (bootstrapping, route registration, menu/permission registration), Orchestra\Memory (settings), the theme API, and resource-routing scaffolding. Those four cover the vast majority of day-to-day additions without touching Foundation internals.