$meta Optional metadata (pagination, counts, etc.) * @return array */ 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 $items The list items * @param int $total Total count (for pagination) * @param int $page Current page * @param int $limit Items per page * @return array */ 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|null $details Additional error details * @return array */ 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 */ 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 $fieldErrors Field-specific errors * @return array */ 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 */ 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 */ public function ok(?string $message = null): array { return $this->success(null, $message); } }