README

A framework-agnostic PHP package that generates HTTP responses cleanly and consistently across ecosystems.

About

LaqueResponses provides a single, composable API to build HTTP responses (success, error, paginated, streamed, file, and problem+json) that plug into any framework via PSR-7/PSR-17 (messages/factories), PSR-15 (middleware, optional), and PSR-11 (container, optional).

Features

Framework-agnostic: works with Laravel, Symfony, Slim, Mezzio, Spiral, or bespoke stacks
Consistent response envelopes across all your services
Content negotiation based on Accept headers
RFC 9457 Problem Details for HTTP APIs
File and stream responses with proper headers
Middleware for content negotiation and exception handling

Requirements

PHP 8.1+
PSR-7/PSR-17 implementation (nyholm/psr7, laminas/laminas-diactoros, etc.)

Installation

composer require vicent/laque-responses

Basic Usage

// 1. Set up the builder with a PSR-7/PSR-17 implementation
$factory = new \Nyholm\Psr7\Factory\Psr17Factory();
$registry = new \LaqueResponses\Registry\FormatterRegistry();
$registry->register(new \LaqueResponses\Formatters\JsonFormatter());
$registry->register(new \LaqueResponses\Formatters\TextFormatter());

$builder = new \LaqueResponses\Builder\ResponseBuilder(
    $factory, $factory, $registry
);

// 2. Create a response
$response = $builder->success([
    'user' => [
        'id' => 123,
        'name' => 'John Doe'
    ]
]);

// 3. Output the response (framework-specific)
// Laravel: return \Symfony\Bridge\PsrHttpMessage\Factory\HttpFoundationFactory::createResponse($response);
// Symfony: return $response;
// PHP-FPM/raw PHP:
foreach ($response->getHeaders() as $name => $values) {
    foreach ($values as $value) {
        header("{$name}: {$value}", false);
    }
}
http_response_code($response->getStatusCode());
echo $response->getBody();

Response Types

Success Response

$response = $builder->success(['user' => $user]);

Response:

{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "John Doe"
    }
  }
}

Error Response

$response = $builder->error(
    'Validation failed', 
    422, 
    ['email' => ['Email is required']]
);

Response:

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "email": ["Email is required"]
  }
}

Paginated Response

$response = $builder->paginated(
    $items,     // Array of items for current page
    $total,     // Total number of items
    $page,      // Current page number
    $perPage    // Items per page
);

Response:

{
  "status": "success",
  "meta": {
    "total": 100,
    "page": 2,
    "per_page": 15,
    "pages": 7
  },
  "data": [
    { "id": 16, "name": "Item 16" },
    ...
  ]
}

Created Response

$response = $builder->created(
    '/users/123',    // Location header value
    $createdUser     // Data to include in response
);

Response (with 201 status code and Location header):

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "John Doe"
  }
}

No Content Response

$response = $builder->noContent();

Returns a 204 No Content response.

Problem Details Response (RFC 9457)

$response = $builder->problem(
    'https://example.com/problems/out-of-stock',
    'Item Out of Stock',
    400,
    'Item #12345 is currently out of stock',
    '/orders/12345',
    ['available_at' => '2025-09-15T12:00:00Z']
);

Response (with application/problem+json content type):

{
  "type": "https://example.com/problems/out-of-stock",
  "title": "Item Out of Stock",
  "status": 400,
  "detail": "Item #12345 is currently out of stock",
  "instance": "/orders/12345",
  "available_at": "2025-09-15T12:00:00Z"
}

File Download

$streamBuilder = new \LaqueResponses\Builder\StreamResponseBuilder($factory, $factory);

$response = $streamBuilder->file(
    '/path/to/report.pdf',
    'quarterly-report-2025.pdf',
    'application/pdf'
);

Returns a response with appropriate headers for file download.

Streaming Response

$response = $streamBuilder->stream(
    function ($stream) {
        $stream->write('Line 1' . PHP_EOL);
        $stream->write('Line 2' . PHP_EOL);
        $stream->write('Line 3' . PHP_EOL);
    },
    200,
    'text/plain'
);

Framework Integration

Laravel

// In a service provider

use LaqueResponses\Builder\ResponseBuilder;
use LaqueResponses\Formatters\JsonFormatter;
use LaqueResponses\Formatters\TextFormatter;
use LaqueResponses\Registry\FormatterRegistry;
use Nyholm\Psr7\Factory\Psr17Factory;

public function register(): void
{
    $this->app->singleton(FormatterRegistry::class, function() {
        $registry = new FormatterRegistry();
        $registry->register(new JsonFormatter(prettyPrint: $this->app->isDebug()));
        $registry->register(new TextFormatter());
        return $registry;
    });
    
    $this->app->singleton(ResponseBuilder::class, function($app) {
        $factory = new Psr17Factory();
        return new ResponseBuilder(
            $factory,
            $factory,
            $app->make(FormatterRegistry::class)
        );
    });
}

// In a controller

use LaqueResponses\Builder\ResponseBuilder;
use Symfony\Bridge\PsrHttpMessage\Factory\HttpFoundationFactory;

class UserController extends Controller
{
    public function show(ResponseBuilder $builder, $id)
    {
        $user = User::findOrFail($id);
        $response = $builder->success($user);
        
        return HttpFoundationFactory::createResponse($response);
    }
}

Slim

// In your dependencies container

use LaqueResponses\Builder\ResponseBuilder;
use LaqueResponses\Error\DefaultExceptionMapper;
use LaqueResponses\Error\ProblemDetailsFactory;
use LaqueResponses\Formatters\JsonFormatter;
use LaqueResponses\Registry\FormatterRegistry;
use Psr\Container\ContainerInterface;

return [
    FormatterRegistry::class => function() {
        $registry = new FormatterRegistry();
        $registry->register(new JsonFormatter());
        return $registry;
    },
    
    ResponseBuilder::class => function(ContainerInterface $c) {
        return new ResponseBuilder(
            $c->get('responseFactory'),
            $c->get('streamFactory'),
            $c->get(FormatterRegistry::class)
        );
    },
    
    ProblemDetailsFactory::class => function(ContainerInterface $c) {
        return new ProblemDetailsFactory(
            $c->get(ResponseBuilder::class),
            new DefaultExceptionMapper(),
            $c->get('settings')['debug'] ?? false
        );
    }
];

// In your route handler

$app->get('/users/{id}', function($request, $response, $args) {
    $builder = $this->get(ResponseBuilder::class);
    
    try {
        $user = $this->get(UserRepository::class)->findById($args['id']);
        return $builder->success($user);
    } catch (NotFoundException $e) {
        return $builder->error('User not found', 404);
    }
});

Custom Formatters

You can create your own formatters by implementing the ResponseFormatterInterface:

use LaqueResponses\Contracts\ResponseFormatterInterface;

final class XmlFormatter implements ResponseFormatterInterface
{
    public function contentType(): string
    {
        return 'application/xml';
    }

    public function format(array|object|string|int|float|bool|null $payload): string
    {
        // Implementation to convert the payload to XML string
        // ...
        
        return $xml;
    }
}

// Register your formatter
$registry->register(new XmlFormatter());

Error Mapping

You can customize how exceptions are mapped to problem responses:

use LaqueResponses\Error\ExceptionMapperInterface;

class AppExceptionMapper implements ExceptionMapperInterface
{
    public function map(\Throwable $e, bool $debug = false): array
    {
        // Map specific exceptions to problem details
        return match (true) {
            $e instanceof RateLimitException => [
                'type' => 'https://problem/rate-limit',
                'title' => 'Too Many Requests',
                'status' => 429,
                'detail' => $e->getMessage(),
                'extensions' => [
                    'retry_after' => $e->getRetryAfter(),
                ]
            ],
            // Default mapping
            default => [
                'type' => 'about:blank',
                'title' => 'Internal Server Error',
                'status' => 500,
                'detail' => $debug ? $e->getMessage() : 'An unexpected error occurred',
                'extensions' => [],
            ],
        };
    }
}

// Use your custom mapper
$problemFactory = new ProblemDetailsFactory(
    $builder,
    new AppExceptionMapper(),
    $debug
);

Configuration

use LaqueResponses\Config;

// Create from array
$config = Config::fromArray([
    'default_content_type' => 'application/json',
    'dev_mode' => true,
    'cache_control_default' => 'no-store',
    'negotiation' => [
        'strict_406' => false,
    ],
    'problem' => [
        'include_trace_id' => true,
        'trace_header' => 'X-Trace-Id',
        'default_type' => 'about:blank',
    ],
    'pagination' => [
        'max_per_page' => 100,
        'default_per_page' => 20,
    ],
]);

// Or directly
$config = new Config(
    defaultContentType: 'application/json',
    devMode: true,
    defaultCacheControl: 'no-store',
    strict406: false
);

// Create a builder with config
$builder = new ResponseBuilder(
    $responseFactory,
    $streamFactory,
    $registry,
    $negotiator,
    $config->defaultContentType,
    $config->defaultCacheControl
);

License

MIT License. See LICENSE file for details.

vicent / laque-responses

Maintainers

Details

README

About

Features

Requirements

Installation

Basic Usage

Response Types

Success Response

Error Response

Paginated Response

Created Response

No Content Response

Problem Details Response (RFC 9457)

File Download

Streaming Response

Framework Integration

Laravel

Slim

Custom Formatters

Error Mapping

Configuration

License