Framework Laravel Package

Getting Started

Start by installing the framework via Composer (composer require spiral/framework) and bootstrapping with RoadRunner (roadrunner-server + spiral/roadrunner-bridge). The official spiral/app skeleton provides a production-ready starting point with DI, configuration, and bootstrap structure. First use cases typically involve:

• Creating a controller with route annotation (#[Route('/api')])
• Injecting services via constructor DI (e.g., RepositoryInterface $repo)
• Using built-in HTTP middleware (e.g., ValidationMiddleware) in app/src/Middleware
  Explore app/config/ for core configs (routes.php, services.php, middleware.php) and app/src/ for module structure (controllers, services, repositories).

Implementation Patterns

• Modular architecture: Organize features into modules/ directories (e.g., modules/User) with their own DI configs, controllers, and services—promoting decoupling and testability.
• Job-based processing: Queue work using spiral/jobs package: dispatch jobs (e.g., new SendEmailJob($user, $template)), configure workers via .rr.yaml, and consume via php spiral worker:consume.
• DI-driven design: Inject stateless services into controllers and domain logic; leverage spiral/core’s ScopeInterface for lifecycle control in long-running contexts.
• Middleware pipelines: Compose HTTP pipeline with PSR-15/PSR-17 compatible middleware, chaining validation, auth, caching, etc., via app/config/middleware.php.
• Testing first: Unit test domain logic in isolation (no bootstrap); use Spiral\Testify trait for integration testing with bootstrapped kernel and DB transactions.

Gotchas and Tips

• Long-running state awareness: Avoid caching request-scoped services (e.g., Request or Router) in singleton services—reset or use ContextInterface to fetch fresh instances per cycle.
• Config caching: Enable config caching (spiral/cache + spiral/config with ConfigCacheInterface) to avoid boot-time penalties in dev/prod—but remember to php spiral cache:clear after changes.
• DB connection pooling: Use spiral/database with persistent connections (via spiral/database-connection + spiral/transactions) but close long-running connections manually to avoid leaks.
• Debugging workers: Use spiral/debug package to profile request cycles; add #[Log] attribute to methods for structured logs or enable RoadRunner’s logs stderr for real-time output.
• Extensibility: Override framework defaults (e.g., HTTP kernel, DI container) by creating custom bootloaders in app/src/Bootloader and implementing BootloaderInterface.