Application Laravel Package

Getting Started

This is a read-only subtree split of the Application component from the MindyPHP monorepo, not a general-purpose library and not a Laravel package. The description's "Laravel/PHP" framing is misleading — there is no Laravel integration surface here. Treat it as the bootstrap/kernel layer of a small, opinionated MVC framework.

Minimal steps to get productive:

1. Don't start here. Install the framework entry point (mindy/framework or the published skeleton), not mindy/application directly. Requiring this package alone gives you a kernel class with no router, no HTTP layer, and no container wiring — you'd rebuild the framework to use it.
2. Read in this order:
   • composer.json — PHP floor, PSR-4 namespace, and the sibling components actually required (Container, Config, Routing, Http). This tells you the real dependency graph.
   • The kernel/Application class — this is the composition root. Each public method reveals what the framework expects from the outside world: request in, response out, lifecycle around it.
   • Any Interface under src/ — these are your extension points if you later swap components.
3. First use case: a single public/index.php that requires the autoloader, constructs the Application with a base path and config array, dispatches one route to one closure, and echoes the response. Then swap the closure for a controller class. Resist building the whole app on day one — the component is thin, and you'll discover missing pieces one at a time (validation, session, DB, logging).

Implementation Patterns

• Bootstrap-then-run. One entry file: autoloader → construct Application with base path + config → call the run()/handle() entry point. After that, treat the application object as opaque. Don't scatter new Application() across the codebase.
• Extend, don't fork. Anything you change inside vendor/mindy/application vanishes on the next composer update — and because it's a subtree split, upstream fixes arrive via a monorepo release, not via this repo. If the kernel is 90% right, subclass it in your app/ layer and override hook methods.
• Config through the constructor, not globals. Pass configuration at bootstrap. Laravel developers will reach for env() and facades out of habit — neither exists here. Resolve services off the container if one is exposed, or inject explicitly.
• Thin controllers, namespace dispatch. Point config at a controller namespace and let PSR-4 autoloading plus the dispatcher do the routing. Keep controllers to request-in/response-out; push domain logic into services you instantiate.
• Integration tips: wrap framework services in your own small interfaces at the boundary. When Mindy lacks a feature (queue, mailer, ORM), you'll wire in a third-party PSR-compliant library — having your own adapter interface means the vendor stays swappable and your call sites stay clean.
• Testing pattern. There's no Laravel-style TestCase base class, so favor integration tests that boot the Application in-process and assert on the response object rather than mocking the kernel. Reserve a small number of unit tests for your own controllers/services where the framework isn't in play.
• Dependency hygiene. Pin exact versions of every Mindy component. There's no visible semver discipline; subtree splits routinely ship breaking changes on minor bumps alongside monorepo releases. Enforce lockfiles and gate dependency updates through review.

Gotchas and Tips

• Two-kernel anti-pattern. Never introduce this alongside a Laravel or Symfony app. Laravel's kernel already owns bootstrap and lifecycle; adding Mindy's creates competing bootstraps and confusing, hard-to-trace failures. This package's adoption decision is binary: adopt MindyPHP end-to-end, or don't adopt it at all.
• Subtree drift. The split can lag or diverge from the monorepo. A bug you see here may already be fixed upstream, and a fix you need has to go through a monorepo PR, a release, then a split. If you need guaranteed consistency, vendor the code with a named internal owner.
• Fixing in place is a dead end. Editing vendor/ is temporary by construction. Any real patch means owning a fork — a staffing and roadmap commitment, not a two-line change.
• Version-pin everything. No caret ranges. Assume breaking changes can land on a minor bump until proven otherwise.
• No community safety net. Effectively no Stack Overflow coverage, tutorials, or third-party integrations. Every question becomes a read-the-source task. Budget for internal runbooks authored from the source, and for a senior PHP engineer to spend days (not weeks) reading it — the surface area is genuinely small.
• Debugging without observability tooling. There's no Telescope equivalent, no debug bar, no structured error page you'd recognize from Laravel. Add your own logging at the bootstrap and dispatch boundaries early; that's where failures surface.
• Extension points are interfaces, not events. If the kernel exposes interfaces for swapping components, use those rather than monkey-patching. Where it doesn't, your exit is subclass hooks — verify they exist before committing to the architecture.
• Security posture. No published security policy, advisory feed, or LTS branch, and a single maintainer. Any fix for a CVE requires a monorepo PR and a split release, so remediation latency sits outside your control. If this ever touches regulated data or an SLA-backed service, the answer is no.
• When to reach for something else. Need routing, ORM, queues, auth, validation, and a hiring pool? Laravel or Symfony. Want a thin layer with far more community validation? Slim. This package is a reasonable input only for a timeboxed spike, internal tooling, or teaching material — and only with an internal owner and a written exit plan logged at the same time.