chore: Merge pull request #89 from WebFiori/dev

Release-As: v5.0.0

Author: usernane

.gitignore

@@ -17,3 +17,4 @@ php-cs-fixer.phar
 /.vscode
 tests/WebFiori/Tests/Http/output-stream.txt
 /OpenAPI_files
+/examples/01-core/04-file-uploads/uploads

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
- Copyright 2019 Ibrahim BinAlshikh, WebFiori HTTP.
+ Copyright 2019-present, WebFiori Framework.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -26,12 +26,18 @@ A powerful and flexible PHP library for creating RESTful web APIs with built-in
 - [Key Features](#key-features)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+  - [Modern Approach with Attributes](#modern-approach-with-attributes)
+  - [Traditional Approach](#traditional-approach)
 - [Core Concepts](#core-concepts)
 - [Creating Web Services](#creating-web-services)
+  - [Using Attributes (Recommended)](#using-attributes-recommended)
+  - [Traditional Class-Based Approach](#traditional-class-based-approach)
 - [Parameter Management](#parameter-management)
 - [Authentication & Authorization](#authentication--authorization)
 - [Request & Response Handling](#request--response-handling)
 - [Advanced Features](#advanced-features)
+  - [Object Mapping](#object-mapping-1)
+  - [OpenAPI Documentation](#openapi-documentation)
 - [Testing](#testing)
 - [Examples](#examples)
 - [API Documentation](#api-documentation)
@@ -77,19 +83,53 @@ require_once 'path/to/webfiori-http/vendor/autoload.php';
 
 ## Quick Start
 
-Here's a simple example to get you started:
+### Modern Approach with Attributes
+
+PHP 8+ attributes provide a clean, declarative way to define web services:
 
 ```php
 <?php
-require_once 'vendor/autoload.php';
+use WebFiori\Http\WebService;
+use WebFiori\Http\Annotations\RestController;
+use WebFiori\Http\Annotations\GetMapping;
+use WebFiori\Http\Annotations\PostMapping;
+use WebFiori\Http\Annotations\Param;
+use WebFiori\Http\Annotations\ResponseBody;
+use WebFiori\Http\Annotations\AllowAnonymous;
+use WebFiori\Http\ParamType;
+
+#[RestController('hello', 'A simple greeting service')]
+class HelloService extends WebService {
+    
+    #[GetMapping]
+    #[ResponseBody]
+    #[AllowAnonymous]
+    #[Param('name', ParamType::STRING, 'Your name')]
+    public function sayHello(?string $name): string {
+        return $name ? "Hello, $name!" : "Hello, World!";
+    }
+    
+    #[PostMapping]
+    #[ResponseBody]
+    #[AllowAnonymous]
+    #[Param('message', ParamType::STRING, 'Custom message')]
+    public function customGreeting(string $message): array {
+        return ['greeting' => $message, 'timestamp' => time()];
+    }
+}
+```
 
+### Traditional Approach
+
+The traditional approach using constructor configuration:
+
+```php
+<?php
 use WebFiori\Http\AbstractWebService;
-use WebFiori\Http\WebServicesManager;
 use WebFiori\Http\RequestMethod;
 use WebFiori\Http\ParamType;
 use WebFiori\Http\ParamOption;
 
-// Create a simple web service
 class HelloService extends AbstractWebService {
     public function __construct() {
         parent::__construct('hello');
@@ -104,22 +144,19 @@ class HelloService extends AbstractWebService {
     }
 
     public function isAuthorized() {
-        // No authentication required
         return true;
     }
 
     public function processRequest() {
         $name = $this->getParamVal('name');
-        
-        if ($name !== null) {
-            $this->sendResponse("Hello, $name!");
-        } else {
-            $this->sendResponse("Hello, World!");
-        }
+        $this->sendResponse($name ? "Hello, $name!" : "Hello, World!");
     }
 }
+```
+
+Both approaches work with `WebServicesManager`:
 
-// Set up the services manager
+```php
 $manager = new WebServicesManager();
 $manager->addService(new HelloService());
 $manager->process();
@@ -148,7 +185,60 @@ The library follows a service-oriented architecture:
 
 ## Creating Web Services
 
-### Basic Service Structure
+### Using Attributes (Recommended)
+
+PHP 8+ attributes provide a modern, declarative approach:
+
+```php
+<?php
+use WebFiori\Http\WebService;
+use WebFiori\Http\Annotations\RestController;
+use WebFiori\Http\Annotations\GetMapping;
+use WebFiori\Http\Annotations\PostMapping;
+use WebFiori\Http\Annotations\PutMapping;
+use WebFiori\Http\Annotations\DeleteMapping;
+use WebFiori\Http\Annotations\Param;
+use WebFiori\Http\Annotations\ResponseBody;
+use WebFiori\Http\Annotations\RequiresAuth;
+use WebFiori\Http\ParamType;
+
+#[RestController('users', 'User management operations')]
+#[RequiresAuth]
+class UserService extends WebService {
+    
+    #[GetMapping]
+    #[ResponseBody]
+    #[Param('id', ParamType::INT, 'User ID', min: 1)]
+    public function getUser(?int $id): array {
+        return ['id' => $id ?? 1, 'name' => 'John Doe'];
+    }
+    
+    #[PostMapping]
+    #[ResponseBody]
+    #[Param('name', ParamType::STRING, 'User name', minLength: 2)]
+    #[Param('email', ParamType::EMAIL, 'User email')]
+    public function createUser(string $name, string $email): array {
+        return ['id' => 2, 'name' => $name, 'email' => $email];
+    }
+    
+    #[PutMapping]
+    #[ResponseBody]
+    #[Param('id', ParamType::INT, 'User ID')]
+    #[Param('name', ParamType::STRING, 'User name')]
+    public function updateUser(int $id, string $name): array {
+        return ['id' => $id, 'name' => $name];
+    }
+    
+    #[DeleteMapping]
+    #[ResponseBody]
+    #[Param('id', ParamType::INT, 'User ID')]
+    public function deleteUser(int $id): array {
+        return ['deleted' => $id];
+    }
+}
+```
+
+### Traditional Class-Based Approach
 
 Every web service must extend `AbstractWebService` and implement the `processRequest()` method:
 
@@ -527,7 +617,7 @@ $customFilter = function($original, $filtered) {
 
     // Additional processing
     return strtoupper($filtered);
-};
+];
 
 $this->addParameters([
     'code' => [
@@ -537,6 +627,36 @@ $this->addParameters([
 ]);
 ```
 
+### OpenAPI Documentation
+
+Generate OpenAPI 3.1.0 specification for your API:
+
+```php
+$manager = new WebServicesManager();
+$manager->setVersion('1.0.0');
+$manager->setDescription('My REST API');
+
+// Add your services
+$manager->addService(new UserService());
+$manager->addService(new ProductService());
+
+// Generate OpenAPI specification
+$openApiObj = $manager->toOpenAPI();
+
+// Customize if needed
+$info = $openApiObj->getInfo();
+$info->setTermsOfService('https://example.com/terms');
+
+// Output as JSON
+header('Content-Type: application/json');
+echo $openApiObj->toJSON();
+```
+
+The generated specification can be used with:
+- Swagger UI for interactive documentation
+- Postman for API testing
+- Code generators for client SDKs
+
 ## Testing
 
 ### Using APITestCase
@@ -735,9 +855,6 @@ class FileUploadService extends AbstractWebService {
 
 For more examples, check the [examples](examples/) directory in this repository.
 
-## API Documentation
-
-This library is part of the WebFiori Framework. For complete API documentation, visit: https://webfiori.com/docs/webfiori/http
 
 ### Key Classes Documentation
 

WebFiori/Http/APIFilter.php

@@ -2,7 +2,7 @@
 /**
  * This file is licensed under MIT License.
  * 
- * Copyright (c) 2019 WebFiori Framework
+ * Copyright (c) 2019-present WebFiori Framework
  * 
  * For more information on the license, please visit: 
  * https://github.com/WebFiori/http/blob/master/LICENSE

WebFiori/Http/APITestCase.php

@@ -2,7 +2,7 @@
 /**
  * This file is licensed under MIT License.
  * 
- * Copyright (c) 2019 WebFiori Framework
+ * Copyright (c) 2019-present WebFiori Framework
  * 
  * For more information on the license, please visit: 
  * https://github.com/WebFiori/http/blob/master/LICENSE
@@ -128,13 +128,13 @@ public function addFile(string $fileIdx, string $filePath, bool $reset = false)
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
-     * @param UserInterface|null $user Optional user to authenticate the request with.
+     * @param SecurityPrincipal|null $user Optional user to authenticate the request with.
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      *  
      * @return string The method will return the output of the endpoint.
      */
-    public function callEndpoint(WebServicesManager $manager, string $requestMethod, string $apiEndpointName, array $parameters = [], array $httpHeaders = [], ?UserInterface $user = null) : string {
+    public function callEndpoint(WebServicesManager $manager, string $requestMethod, string $apiEndpointName, array $parameters = [], array $httpHeaders = [], ?SecurityPrincipal $user = null) : string {
         $method = strtoupper($requestMethod);
         $serviceName = $this->resolveServiceName($apiEndpointName);
 
@@ -188,7 +188,7 @@ private function resolveServiceName(string $nameOrClass): string {
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
-     * @param UserInterface|null $user Optional user to authenticate the request with.
+     * @param SecurityPrincipal|null $user Optional user to authenticate the request with.
      */
     private function setupRequest(string $method, string $serviceName, array $parameters, array $httpHeaders) {
         putenv('REQUEST_METHOD=' . $method);
@@ -267,14 +267,14 @@ public function format(string $output) {
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
-     * @param UserInterface|null $user Optional user to authenticate the request with.
+     * @param SecurityPrincipal|null $user Optional user to authenticate the request with.
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
      * @return string The method will return the output that was produced by
      * the endpoint as string.
      */
-    public function deleteRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?UserInterface $user = null) : string {
+    public function deleteRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?SecurityPrincipal $user = null) : string {
         return $this->callEndpoint($manager, RequestMethod::DELETE, $endpoint, $parameters, $httpHeaders, $user);
     }
     /**
@@ -290,7 +290,7 @@ public function deleteRequest(WebServicesManager $manager, string $endpoint, arr
      * @return string The method will return the output that was produced by
      * the endpoint as string.
      */
-    public function getRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?UserInterface $user = null) : string {
+    public function getRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?SecurityPrincipal $user = null) : string {
         return $this->callEndpoint($manager, RequestMethod::GET, $endpoint, $parameters, $httpHeaders, $user);
     }
     /**
@@ -307,14 +307,14 @@ public function getRequest(WebServicesManager $manager, string $endpoint, array
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
-     * @param UserInterface|null $user Optional user to authenticate the request with.
+     * @param SecurityPrincipal|null $user Optional user to authenticate the request with.
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
      * @return string The method will return the output that was produced by
      * the endpoint as string.
      */
-    public function postRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?UserInterface $user = null) : string {
+    public function postRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?SecurityPrincipal $user = null) : string {
         return $this->callEndpoint($manager, RequestMethod::POST, $endpoint, $parameters, $httpHeaders, $user);
     }
     /**
@@ -331,14 +331,14 @@ public function postRequest(WebServicesManager $manager, string $endpoint, array
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
-     * @param UserInterface|null $user Optional user to authenticate the request with.
+     * @param SecurityPrincipal|null $user Optional user to authenticate the request with.
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
      * @return string The method will return the output that was produced by
      * the endpoint as string.
      */
-    public function putRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?UserInterface $user = null) : string {
+    public function putRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?SecurityPrincipal $user = null) : string {
         return $this->callEndpoint($manager, RequestMethod::PUT, $endpoint, $parameters, $httpHeaders, $user);
     }
     /**
@@ -355,14 +355,14 @@ public function putRequest(WebServicesManager $manager, string $endpoint, array
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
-     * @param UserInterface|null $user Optional user to authenticate the request with.
+     * @param SecurityPrincipal|null $user Optional user to authenticate the request with.
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
      * @return string The method will return the output that was produced by
      * the endpoint as string.
      */
-    public function patchRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?UserInterface $user = null) : string {
+    public function patchRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?SecurityPrincipal $user = null) : string {
         return $this->callEndpoint($manager, RequestMethod::PATCH, $endpoint, $parameters, $httpHeaders, $user);
     }
     /**
@@ -379,14 +379,14 @@ public function patchRequest(WebServicesManager $manager, string $endpoint, arra
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
-     * @param UserInterface|null $user Optional user to authenticate the request with.
+     * @param SecurityPrincipal|null $user Optional user to authenticate the request with.
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
      * @return string The method will return the output that was produced by
      * the endpoint as string.
      */
-    public function optionsRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?UserInterface $user = null) : string {
+    public function optionsRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?SecurityPrincipal $user = null) : string {
         return $this->callEndpoint($manager, RequestMethod::OPTIONS, $endpoint, $parameters, $httpHeaders, $user);
     }
     /**
@@ -403,14 +403,14 @@ public function optionsRequest(WebServicesManager $manager, string $endpoint, ar
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
-     * @param UserInterface|null $user Optional user to authenticate the request with.
+     * @param SecurityPrincipal|null $user Optional user to authenticate the request with.
      * to mimic HTTP request headers. The keys of the array are names of headers
      * and the value of each key represents the value of the header.
      * 
      * @return string The method will return the output that was produced by
      * the endpoint as string.
      */
-    public function headRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?UserInterface $user = null) : string {
+    public function headRequest(WebServicesManager $manager, string $endpoint, array $parameters = [], array $httpHeaders = [], ?SecurityPrincipal $user = null) : string {
         return $this->callEndpoint($manager, RequestMethod::HEAD, $endpoint, $parameters, $httpHeaders, $user);
     }
     private function extractPathAndName($absPath): array {