Framework X Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require clue/framework-x:^0.17
   

2. Basic index.php:

   <?php
   require __DIR__ . '/../vendor/autoload.php';
   
   $app = new FrameworkX\App();
   $app->get('/', fn() => React\Http\Message\Response::plaintext("Hello World!"));
   $app->run();
   

3. Run:

   php index.php
   

   Access via http://localhost:8080.

First Use Case: REST API Endpoint

$app->get('/api/users/{id}', function (ServerRequestInterface $request) {
    $id = $request->getAttribute('id');
    return Response::json(['user_id' => $id]);
});

Key Entry Points

• FrameworkX\App: Core application class.
• Route Methods: get(), post(), put(), delete(), patch(), options().
• Middleware: Global and route-specific via middleware().
• Dependency Injection: Class-based or explicit container.

Implementation Patterns

1. Reactive Middleware

Leverage async/await for non-blocking operations:

$app->middleware(function (ServerRequestInterface $request, callable $next) {
    $start = microtime(true);
    $response = $next($request);
    $duration = microtime(true) - $start;
    return $response->withHeader('X-Response-Time', $duration);
});

2. Dependency Injection

Automatic (Class-Based):

$app->get('/users', UserController::class); // Resolves via constructor

Explicit Container:

$container = new FrameworkX\Container([
    UserService::class => fn() => new UserService($db),
]);
$app = new FrameworkX\App($container);

3. Fiber-Based Request Handling

PHP 8.1+ auto-spawns fibers per request. For older versions, enable fiber mode:

$app = new FrameworkX\App(['fiber_mode' => true]);

4. Environment Configuration

Use X_LISTEN env var to override default port/host:

X_LISTEN=0.0.0.0:8080 php index.php

5. Error Handling

Customize error output via middleware:

$app->middleware(function ($request, $next) use ($app) {
    try {
        return $next($request);
    } catch (Throwable $e) {
        return Response::json(['error' => $e->getMessage()], 500);
    }
});

6. Integration with ReactPHP

Extend FrameworkX\App for custom integrations:

$app = new FrameworkX\App();
$app->on('start', function () {
    echo "Server started!\n";
});

Gotchas and Tips

Pitfalls

1. Fiber Mode Quirks:

   • PHP < 8.1: Explicitly enable fiber_mode (may cause performance overhead).
   • PHP 8.1+: Fibers auto-spawn, but nested fibers (e.g., in middleware) require await for coroutines.

2. Route Matching:

   • Trailing slashes are not automatically normalized. Use /{param?} for optional params.
   • Example: /users/{id?} matches /users and /users/123.

3. Dependency Injection:

   • Circular dependencies break the container. Use interfaces or lazy-loading.
   • Explicit container bindings override autowiring.

4. Environment Variables:

   • X_LISTEN overrides SERVER_NAME/PORT but does not support Unix sockets.

5. Response Headers:

   • Headers set after Response::json()/Response::html() will not be included. Use withHeader() before body generation.

Debugging Tips

1. Log Requests:

   $app->middleware(function ($request, $next) {
       error_log($request->getUri());
       return $next($request);
   });
   

2. Check Fiber Context:

   if (\React\Async\isRunningInFiber()) {
       echo "Running in fiber!\n";
   }
   

3. Validate Middleware:

   • Middleware must call $next() or return a Response. Omitting $next() breaks the chain.

4. Test Locally:

   php -S localhost:8080 public/index.php
   

Extension Points

1. Custom Handlers: Override FrameworkX\Handler\RouteHandler for advanced routing logic.

2. Async Database: Use React\Mysql\Connection or React\Redis with await:

   $app->get('/data', async function () {
       $db = new React\Mysql\Connection($config);
       $result = await $db->query('SELECT * FROM users');
       return Response::json($result);
   });
   

3. Signal Handling: Listen for SIGINT/SIGTERM via:

   $app->on('shutdown', function () {
       echo "Shutting down gracefully...\n";
   });
   

4. Docker Integration: Use the provided Dockerfile or configure X_LISTEN in docker-compose.yml:

   environment:
     X_LISTEN: 0.0.0.0:8080
   

Performance Quirks

• Access Logging: Disable with X_ACCESS_LOG=/dev/null to skip log writes.
• Fiber Overhead: Disable fiber mode (fiber_mode: false) for CPU-bound tasks in PHP < 8.1.
• Response Streaming: Use Response::stream() for large files to avoid memory spikes.

Configuration Deep Dive

• App Constructor Options:

  $app = new FrameworkX\App([
      'fiber_mode' => true,       // Force fiber mode (PHP < 8.1)
      'access_log' => '/var/log/app.log', // Custom log path
      'error_handler' => null,   // Disable default error handler
  ]);
  

• Middleware Order: Middleware runs top-to-bottom in registration order. Use array_unshift() for priority.