Roadrunner Api Dto Laravel Package

Getting Started

Start by installing the package via Composer:

composer require roadrunner-php/roadrunner-api-dto

The package provides no runtime logic—it’s only a collection of auto-generated, typed DTO classes that mirror RoadRunner’s internal protocol (e.g., jobs, responses, errors, metadata). Your first use case is likely in a custom RoadRunner worker (e.g., HTTP server, queue consumer, or gRPC service). For example, when handling an HTTP job:

use RoadRunnerAPI\Dto\Http\Request;

// In your worker loop
$job = $worker->waitJob();
$requestDto = Request::fromArray($job->getPayload());

// Now $requestDto->getMethod(), ->getUri(), ->getHeaders(), etc.

Check src/ (via GitHub) or run composer show roadrunner-php/roadrunner-api-dto --path to see available DTOs (e.g., Http\Request, Http\Response, Jobs\Job, Http\Error, Values\Headers, etc.).

Implementation Patterns

• Explicit payload modeling: Replace json_decode($payload, true) with typed DTOs to avoid fragile array access and improve IDE autocomplete.
• Validation layer integration: Pass DTOs to your validation libraries (e.g., Symfony Validator, Laravel Validation) via custom rules—DTO properties are strictly typed.
• Middleware chains: Build reusable middleware that inspects/modifies structured payloads:

  // Example: Logging middleware
  $request = Http\Request::fromArray($job->getPayload());
  $logger->info('HTTP request', [
    'method' => $request->getMethod(),
    'path'   => $request->getUri()->getPath(),
  ]);
  

• Response composition: Use DTOs to build standardized responses:

  $response = (new Http\Response())
    ->withStatus(200)
    ->withHeader('Content-Type', 'application/json')
    ->withBody(json_encode(['data' => $item]));
  $worker->respond($response->toArray());
  

• Custom job payloads: Define your own domain DTOs that extend or wrap RoadRunner’s primitives (e.g., class OrderProcessedJob extends Jobs\Job {}) to enforce domain contracts.

Gotchas and Tips

• No runtime server interaction: This package only provides DTOs—it does not replace spiral/roadrunner or spiral/roadrunner-http. You’ll still need a RoadRunner worker client to send/receive jobs.
• Version skew is critical: DTOs match a specific RoadRunner protocol version. Ensure your roadrunner-api-dto version aligns with your RoadRunner binary and worker SDK (e.g., spiral/roadrunner ≥2.0 vs ≥3.0 have different payloads). Mismatch can cause UndefinedProperty or deserialization errors.
• Null safety: Many proto fields are ?string/?int. Use null checks or null-coalescing before accessing (e.g., $request->getHeaders()?->get('Host')), especially for optional headers or metadata.
• Extending DTOs safely: You can add methods to DTOs in your codebase (e.g., class MyRequest extends Http\Request { public function getNormalizedPath(): string { ... } }), but avoid modifying the generated classes directly—they’re auto-updated.
• Debugging deserialization issues: If fromArray() throws InvalidPayloadException, inspect the raw payload ($job->getPayload()) and compare against the proto spec. Common culprits: snake_case vs camelCase keys, missing required fields (marked @required in PHPDoc), or wrong types (e.g., array where a scalar is expected).
• Auto-sync tip: Add a post-merge hook to regenerate DTOs (make generate or manual php bin/generate.php) when RoadRunner’s proto files update—this package likely ships pre-generated classes, so track changelogs for breaking changes.