feat: add ResponseEntity class for dynamic HTTP status codes with #[ResponseBody]

Introduce ResponseEntity that wraps body, status code, and content type,
allowing methods to return different HTTP status codes based on runtime logic.

Includes static factory methods: ok(), created(), noContent(), badRequest(),
unauthorized(), forbidden(), notFound(), error().

When handleMethodResponse() detects a ResponseEntity return value, it uses
its status and content type instead of the annotation defaults.

Closes #107

Author: Ibrahim BinAlshikh

WebFiori/Http/ResponseEntity.php

@@ -0,0 +1,149 @@
+<?php
+
+/**
+ * This file is licensed under MIT License.
+ * 
+ * Copyright (c) 2026-present WebFiori Framework
+ * 
+ * For more information on the license, please visit: 
+ * https://github.com/WebFiori/.github/blob/main/LICENSE
+ * 
+ */
+namespace WebFiori\Http;
+
+/**
+ * A wrapper class that allows methods annotated with #[ResponseBody] to return
+ * dynamic HTTP status codes and content types along with the response body.
+ * 
+ * @author Ibrahim
+ */
+class ResponseEntity {
+    /**
+     * Creates a new ResponseEntity instance.
+     * 
+     * @param mixed $body The response body content. Can be a Json object, array, string, or null.
+     * 
+     * @param int $status The HTTP status code to send with the response. Default is 200.
+     * 
+     * @param string $contentType The content type header value. Default is 'application/json'.
+     */
+    public function __construct(
+        private mixed $body,
+        private int $status = 200,
+        private string $contentType = 'application/json'
+    ) {
+    }
+
+    /**
+     * Returns the response body.
+     * 
+     * @return mixed The body content of the response.
+     */
+    public function getBody(): mixed {
+        return $this->body;
+    }
+
+    /**
+     * Returns the HTTP status code.
+     * 
+     * @return int The HTTP status code.
+     */
+    public function getStatus(): int {
+        return $this->status;
+    }
+
+    /**
+     * Returns the content type of the response.
+     * 
+     * @return string The content type header value.
+     */
+    public function getContentType(): string {
+        return $this->contentType;
+    }
+
+    /**
+     * Creates a ResponseEntity with HTTP 200 OK status.
+     * 
+     * @param mixed $body The response body content.
+     * 
+     * @return self A new ResponseEntity instance with status 200.
+     */
+    public static function ok(mixed $body): self {
+        return new self($body, 200);
+    }
+
+    /**
+     * Creates a ResponseEntity with HTTP 201 Created status.
+     * 
+     * @param mixed $body The response body content.
+     * 
+     * @return self A new ResponseEntity instance with status 201.
+     */
+    public static function created(mixed $body): self {
+        return new self($body, 201);
+    }
+
+    /**
+     * Creates a ResponseEntity with HTTP 204 No Content status and null body.
+     * 
+     * @return self A new ResponseEntity instance with status 204 and no body.
+     */
+    public static function noContent(): self {
+        return new self(null, 204);
+    }
+
+    /**
+     * Creates a ResponseEntity with HTTP 400 Bad Request status.
+     * 
+     * @param mixed $body The response body content describing the error.
+     * 
+     * @return self A new ResponseEntity instance with status 400.
+     */
+    public static function badRequest(mixed $body): self {
+        return new self($body, 400);
+    }
+
+    /**
+     * Creates a ResponseEntity with HTTP 401 Unauthorized status.
+     * 
+     * @param mixed $body The response body content describing the authentication failure.
+     * 
+     * @return self A new ResponseEntity instance with status 401.
+     */
+    public static function unauthorized(mixed $body): self {
+        return new self($body, 401);
+    }
+
+    /**
+     * Creates a ResponseEntity with HTTP 403 Forbidden status.
+     * 
+     * @param mixed $body The response body content describing the authorization failure.
+     * 
+     * @return self A new ResponseEntity instance with status 403.
+     */
+    public static function forbidden(mixed $body): self {
+        return new self($body, 403);
+    }
+
+    /**
+     * Creates a ResponseEntity with HTTP 404 Not Found status.
+     * 
+     * @param mixed $body The response body content describing what was not found.
+     * 
+     * @return self A new ResponseEntity instance with status 404.
+     */
+    public static function notFound(mixed $body): self {
+        return new self($body, 404);
+    }
+
+    /**
+     * Creates a ResponseEntity with HTTP 500 Internal Server Error status.
+     * 
+     * @param mixed $body The response body content describing the error.
+     * 
+     * @return self A new ResponseEntity instance with status 500.
+     */
+    public static function error(mixed $body): self {
+        return new self($body, 500);
+    }
+}

WebFiori/Http/WebService.php

@@ -1488,6 +1488,25 @@ protected function handleMethodResponse(mixed $result, string $methodName): void
             return;
         }
 
+        // Handle ResponseEntity for dynamic status codes
+        if ($result instanceof ResponseEntity) {
+            $body = $result->getBody();
+            if ($body === null) {
+                $this->send($result->getContentType(), "", $result->getStatus());
+            } else if ($body instanceof Json || $body instanceof JsonI) {
+                $json = $body instanceof JsonI ? $body->toJSON() : $body;
+                $this->send($result->getContentType(), $json, $result->getStatus());
+            } else if (is_array($body) || is_object($body)) {
+                $json = new Json();
+                $asObj = is_array($body) && !array_is_list($body);
+                $json->add("data", $body, $asObj);
+                $this->send($result->getContentType(), $json, $result->getStatus());
+            } else {
+                $this->send($result->getContentType(), $body, $result->getStatus());
+            }
+            return;
+        }
+
         // Auto-convert return value to JSON response
         if ($result === null) {
             // Null return = empty response with configured status