Backup #792

Dateiinhalt

<?php

namespace Infrastructure\Formatter;

/**
 * Formats API responses with a consistent structure.
 *
 * Success response:
 * {
 *   "success": true,
 *   "data": {...},
 *   "message": "optional message",
 *   "meta": {"timestamp": "...", "count": N}
 * }
 *
 * Error response:
 * {
 *   "success": false,
 *   "error": "error message",
 *   "code": "ERROR_CODE",
 *   "details": {...}
 * }
 */
final class ApiResponseFormatter
{
    /**
     * Format a success response.
     *
     * @param mixed $data The response data
     * @param string|null $message Optional success message
     * @param array<string, mixed> $meta Optional metadata (pagination, counts, etc.)
     * @return array<string, mixed>
     */
    public function success(mixed $data, ?string $message = null, array $meta = []): array
    {
        $response = [
            'success' => true,
            'data' => $data,
        ];

        if ($message !== null) {
            $response['message'] = $message;
        }

        if ($meta !== []) {
            $response['meta'] = $meta;
        }

        return $response;
    }

    /**
     * Format a list response with pagination metadata.
     *
     * @param array<mixed> $items The list items
     * @param int $total Total count (for pagination)
     * @param int $page Current page
     * @param int $limit Items per page
     * @return array<string, mixed>
     */
    public function list(array $items, int $total, int $page = 1, int $limit = 10): array
    {
        return $this->success($items, null, [
            'total' => $total,
            'page' => $page,
            'limit' => $limit,
            'pages' => (int) ceil($total / max(1, $limit)),
        ]);
    }

    /**
     * Format an error response.
     *
     * @param string $message Error message
     * @param string|null $code Machine-readable error code
     * @param array<string, mixed>|null $details Additional error details
     * @return array<string, mixed>
     */
    public function error(string $message, ?string $code = null, ?array $details = null): array
    {
        $response = [
            'success' => false,
            'error' => $message,
        ];

        if ($code !== null) {
            $response['code'] = $code;
        }

        if ($details !== null) {
            $response['details'] = $details;
        }

        return $response;
    }

    /**
     * Format a not found error.
     *
     * @param string $resource The resource type that was not found
     * @return array<string, mixed>
     */
    public function notFound(string $resource = 'Resource'): array
    {
        return $this->error("{$resource} nicht gefunden", 'NOT_FOUND');
    }

    /**
     * Format a validation error.
     *
     * @param string $message Error message
     * @param array<string, string> $fieldErrors Field-specific errors
     * @return array<string, mixed>
     */
    public function validationError(string $message, array $fieldErrors = []): array
    {
        return $this->error($message, 'VALIDATION_ERROR', $fieldErrors !== [] ? ['fields' => $fieldErrors] : null);
    }

    /**
     * Format a created response with the new resource ID.
     *
     * @param int|string $id The created resource ID
     * @param string|null $message Optional success message
     * @return array<string, mixed>
     */
    public function created(int|string $id, ?string $message = null): array
    {
        return $this->success(['id' => $id], $message ?? 'Erfolgreich erstellt');
    }

    /**
     * Format a deleted/updated confirmation.
     *
     * @param string|null $message Optional message
     * @return array<string, mixed>
     */
    public function ok(?string $message = null): array
    {
        return $this->success(null, $message);
    }
}

Vollständig herunterladen

Aktionen

← Zurück zur Übersicht