Framework Laravel Package

## Getting Started

### Minimal Steps to Begin
1. **Installation**:
   ```bash
   composer create-project spiral/framework my-project

Or add to an existing project:

composer require spiral/framework

2. First Use Case:

   • Run the built-in scaffolding to generate a basic controller:

     php spiral.php make:controller Home
     

   • This creates a controller in app/Http/Controller/HomeController.php with a default index() method.

3. Where to Look First:

   • Core Configuration: config/app.php (defines bootloaders, kernel settings).
   • Routing: app/Http/routes.php (PSR-15 compatible router).
   • Dependency Injection: app/Provider/ (bootloaders for services).
   • Session Configuration: config/session.php (updated in 3.13.1 for path containment fixes).
   • Documentation: https://spiral.dev/docs (official guides and API references).

Implementation Patterns

Core Workflows

1. Bootloader-Based Initialization:

   • Define services in app/Provider/ (e.g., DatabaseProvider.php).
   • Use @Bootloader attributes or extend BootloaderInterface:

     #[Bootloader]
     class DatabaseProvider extends Bootloader
     {
         public function boot(IocContainer $container): void
         {
             $container->bindSingleton('db', fn() => new PDO(...));
         }
     }
     

2. PSR-15 Middleware:

   • Register middleware in app/Http/Middleware/:

     #[Middleware]
     class AuthMiddleware implements MiddlewareInterface
     {
         public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
         {
             // Logic...
             return $handler->handle($request);
         }
     }
     

   • Attach to routes:

     $router->group('/admin', [AuthMiddleware::class], function (Router $router) {
         $router->get('/dashboard', [DashboardController::class, 'index']);
     });
     

3. Session Management (Updated in 3.13.1):

   • Configure session storage in config/session.php:

     'handler' => [
         'type' => 'file',
         'path' => storage_path('framework/sessions'),
         'name' => 'spiral_session',
     ],
     

   • Ensure session ID validation is handled correctly (fixed in 3.13.1):

     $session = $container->get(SessionInterface::class);
     $session->start(); // Session ID will now be validated and path containment enforced
     

4. Cycle ORM Integration:

   • Define entities in app/Entity/ (e.g., User.php).
   • Use repositories:

     $user = $container->get(UserRepository::class)->find(1);
     

   • Migrations via CLI:

     php spiral.php cycle:migrate
     

5. Queue Workers:

   • Define jobs in app/Job/ (e.g., SendEmailJob.php).
   • Dispatch jobs:

     $queue->dispatch(new SendEmailJob($user));
     

   • Run workers via RoadRunner:

     rr get queue:consume
     

6. CLI Commands:

   • Scaffold a command:

     php spiral.php make:command SendEmail
     

   • Use attributes for configuration:

     #[Command(name: 'email:send', description: 'Send an email')]
     class SendEmailCommand extends Command
     {
         #[Argument(name: 'to', description: 'Recipient email')]
         private string $to;
     
         protected function execute(): int
         {
             // Logic...
             return self::SUCCESS;
         }
     }
     

7. Event-Driven Architecture:

   • Dispatch events:

     $dispatcher->dispatch(new UserRegisteredEvent($user));
     

   • Listen via bootloader:

     $dispatcher->listen(UserRegisteredEvent::class, [UserNotifier::class, 'notify']);
     

Integration Tips

• RoadRunner Bridge:
  • Use spiral/roadrunner-bridge for HTTP, queues, and WebSockets.
  • Configure in config/roadrunner.php:

    return [
        'servers' => [
            'http' => [
                'addr' => '0.0.0.0:8080',
            ],
        ],
    ];
    

• Temporal Workflows:
  • Define workflows in app/Workflow/ (e.g., OrderProcessingWorkflow.php).
  • Integrate with spiral/temporal-bridge for distributed task orchestration.
• Scaffolding:
  • Generate CRUD interfaces:

    php spiral.php make:crud User
    

  • Customize templates in config/scaffolder.php.

Gotchas and Tips

Common Pitfalls

1. Session Path Containment (Fixed in 3.13.1):

   • Ensure storage_path('framework/sessions') is writable and properly configured in config/session.php.
   • If using custom session paths, validate they are contained within the expected directory structure to avoid path traversal issues.

2. Memory Leaks:

   • Spiral uses a resident memory kernel (via RoadRunner). Avoid circular dependencies or unbound singletons.
   • Debug with:

     php spiral.php debug:memory
     

3. RoadRunner Configuration:

   • Ensure roadrunner.json is properly configured for your environment (e.g., static vs. dynamic workers).
   • Common issue: Forgetting to bind services to the container in bootloaders (e.g., QueueInterface).

4. Queue Retries:

   • Configure retry policies in config/queue.php:

     'retry_policy' => [
         'max_attempts' => 3,
         'delay' => 1000, // ms
     ],
     

   • Use RetryPolicyInterceptor for automatic retries:

     $queue->addInterceptor(new RetryPolicyInterceptor());
     

5. ORM Eager Loading:

   • Cycle ORM uses lazy loading by default. Force eager loading in repositories:

     $user = $repository->with(['posts'])->find(1);
     

6. Middleware Order:

   • Middleware runs in registration order. Use #[Priority] to adjust:

     #[Middleware(priority: -100)] // Runs first
     class AuthMiddleware implements MiddlewareInterface { ... }
     

7. Environment Variables:

   • Load .env files in app/Provider/KernelProvider.php:

     $container->bindSingleton(EnvironmentInterface::class, fn() => new DotEnv());
     

Debugging Tips

1. Debugging Routes:

   • List all routes:

     php spiral.php debug:routes
     

   • Dump route details:

     $router->get('/debug', function () use ($router) {
         return json_encode($router->getRoutes());
     });
     

2. Container Inspection:

   • List all bindings:

     php spiral.php debug:container
     

   • Inspect a specific binding:

     $container->has('db') ? $container->get('db') : 'Not bound';
     

3. Logging:

   • Configure Monolog in config/monolog.php:

     'format' => '%datetime% [%level_name%] %message% %context% %extra%',
     

   • Use LogTracer for performance:

     $tracer = new LogTracer($logger);
     $tracer->start('operation');
     // ... code ...
     $tracer->finish();
     

4. Tokenizer Issues:

   • Validate listeners:

     php spiral.php tokenizer:validate
     

   • Debug info:

     php spiral.php tokenizer:info
     

5. Session Debugging (3.13.1):

   • Verify session ID generation and validation:

     $session = $container->get(SessionInterface::class);
     $session->start();
     error_log($session->getId()); // Check if ID is valid and properly formatted
     

Extension Points

1. Custom Bootloaders:

   • Extend Bootloader for reusable logic:

     class CacheBootloader extends Bootloader
     {
         public function boot(IocContainer $container): void
         {
             $container->bindSingleton('cache', fn() => new RedisCache());
         }
     }
     

2. Dynamic Route Patterns:

   • Register custom patterns in app/Provider/RoutingProvider.php:

     $container->bindSingleton(
         RoutePatternRegistryInterface::class,
         fn() => new RoutePatternRegistry(['uuid' => '[0-9a-f]{8}-[0