Skip to main content

​
Creating a Response

Every response class must extend AbstractApivalkResponse and implement:
  • getStatusCode(): Returns the HTTP status code (e.g., 200, 201, 404).
  • getDocumentation(): Defines the schema for OpenAPI generation.
  • toArray(): Returns the data to be rendered (usually as JSON).

​
Example

namespace App\Http\Response\Pet;

use apivalk\apivalk\Http\Response\AbstractApivalkResponse;
use apivalk\apivalk\Documentation\ApivalkResponseDocumentation;
use apivalk\apivalk\Documentation\Property\StringProperty;

class GetPetResponse extends AbstractApivalkResponse
{
    private $pet;

    public function __construct(array $pet)
    {
        $this->pet = $pet;
    }

    public static function getStatusCode(): int
    {
        return self::HTTP_200_OK;
    }

    public static function getDocumentation(): ApivalkResponseDocumentation
    {
        $doc = new ApivalkResponseDocumentation();
        $doc->addProperty(new StringProperty('name', 'Name of the pet'));
        // ... add more properties
        return $doc;
    }

    public function toArray(): array
    {
        return [
            'id' => $this->pet['id'],
            'name' => $this->pet['name'],
        ];
    }
}

​
Built-in Error Responses

Apivalk provides several pre-defined error responses for common scenarios:
  • BadRequestApivalkResponse (400)
  • UnauthorizedApivalkResponse (401)
  • ForbiddenApivalkResponse (403)
  • NotFoundApivalkResponse (404)
  • MethodNotAllowedApivalkResponse (405)
  • TooManyRequestsApivalkResponse (429)
  • InternalServerErrorApivalkResponse (500)
  • BadValidationApivalkResponse (422) - Used automatically by the RequestValidationMiddleware.

​
Headers

You can add custom headers to any response object: 
$response->setHeaders([
    'X-Custom-Header' => 'Value'
]);

$response->addHeaders(['APP-ID' => '213']);

​
Automatic Rate Limit Headers

When the Rate Limit Middleware is active, Apivalk automatically appends rate limit information to the response headers. This ensures that clients are always aware of their current quota and remaining requests. The following headers are automatically added:
  • X-RateLimit-Limit: The maximum number of requests allowed in the current window.
  • X-RateLimit-Remaining: The number of requests left for the current window.
  • X-RateLimit-Reset: The time at which the current rate limit window resets (UTC timestamp).
If the rate limit is exceeded (429 Too Many Requests), the Retry-After header is also included.

​
Rendering

The JsonRenderer is the default renderer. It takes the array from toArray() and converts it to a JSON string, handling headers and status codes automatically.