- Can I use kleijnweb/php-api-descriptions for Laravel API validation in production?
- Yes, but proceed with caution. The package supports OpenAPI 2.0 validation for requests/responses, but its archived status means no active PHP 8.2+ or Laravel 10+ compatibility guarantees. Test thoroughly in staging first, especially if using middleware for contract enforcement.
- How do I integrate this with Laravel’s built-in request validation?
- Avoid redundancy by choosing one system. Use this package’s `MessageValidator` for API contract validation (e.g., OpenAPI schemas) and Laravel’s `Validator` for form-level rules. Middleware like `ValidateApiContract` can bridge both, but prioritize contract validation for public APIs.
- Does this package support OpenAPI 3.x or JSON Schema?
- No, it only supports OpenAPI 2.0 (Swagger) and limited RAML 1.0. For OpenAPI 3.x, consider alternatives like `zircote/swagger-php` or `darkaonline/l5-swagger`, which offer broader spec compatibility and Laravel integrations.
- Will this work with Laravel Sanctum or Passport for API authentication?
- Indirectly, but requires manual setup. Use middleware to validate API contracts *after* auth checks (e.g., `auth:sanctum` then `ValidateApiContract`). The package doesn’t natively handle OAuth2/JWT claims, so you’ll need custom logic to map contract paths to auth scopes.
- How do I handle errors when API requests violate the contract?
- Return RFC 7807 Problem Details or custom JSON responses. The package’s `MessageValidator` throws exceptions on failure; catch these and format errors using Laravel’s `Problem` facade or a library like `filp/whoops` for structured error pages.
- Can I use this to generate API clients or documentation?
- Not directly. This package focuses on *validating* against contracts, not generating clients/docs. For clients, use `openapi-generator`; for docs, pair with `darkaonline/l5-swagger` or `zircote/swagger-php` to render OpenAPI specs in Swagger UI.
- How do I test API contracts in Laravel’s testing environment?
- Write contract-specific tests using PHPUnit/Pest. Mock `ServerRequestInterface` and `ResponseInterface` to validate requests/responses against your OpenAPI schema. Example: `assertTrue($validator->validateRequest($mockRequest, '/users'))`. For E2E tests, combine with Laravel’s `Http::fake()`.
- What’s the performance impact of runtime contract validation?
- Moderate. Parsing and validating OpenAPI schemas adds latency (~5–50ms per request, depending on schema complexity). Mitigate by caching parsed contracts (e.g., `Illuminate/Cache`) and avoiding over-fetching in schemas. Benchmark in staging before production.
- Are there alternatives with better Laravel support?
- Yes. For OpenAPI tooling, try `darkaonline/l5-swagger` (Laravel-specific) or `spatie/laravel-api` (contract-first with built-in validation). For JSON Schema, `webonyx/graphql-php` (if using GraphQL) or `justinrainbow/json-schema` offer more active maintenance.
- How do I handle API versioning with this package?
- Version contracts explicitly in your OpenAPI `paths` (e.g., `/v1/users`). Use middleware to route requests to the correct schema (e.g., `ValidateApiContract@v1`). For deprecation, add `deprecated: true` to paths and return `410 Gone` with a `Deprecation` header when contracts are removed.