WebFiori HTTP

A powerful and flexible PHP library for creating RESTful web APIs with built-in input filtering, data validation, and comprehensive HTTP utilities. The library provides a clean, object-oriented approach to building web services with automatic parameter validation, authentication support, and JSON response handling.

Supported PHP Versions
Key Features
Installation
Quick Start
- Modern Approach with Attributes
- Traditional Approach
Core Concepts
Creating Web Services
- Using Attributes (Recommended)
- Traditional Class-Based Approach
Parameter Management
Testing
Examples

Supported PHP Versions

| Build Status | |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| | <a target="_blank" href="https://github.com/WebFiori/http/actions/workflows/php81.yaml"><img src="https://github.com/WebFiori/http/actions/workflows/php81.yaml/badge.svg?branch=main"></a> | | <a target="_blank" href="https://github.com/WebFiori/http/actions/workflows/php82.yaml"><img src="https://github.com/WebFiori/http/actions/workflows/php82.yaml/badge.svg?branch=main"></a> | | <a target="_blank" href="https://github.com/WebFiori/http/actions/workflows/php83.yaml"><img src="https://github.com/WebFiori/http/actions/workflows/php83.yaml/badge.svg?branch=main"></a> | | <a target="_blank" href="https://github.com/WebFiori/http/actions/workflows/php84.yaml"><img src="https://github.com/WebFiori/http/actions/workflows/php84.yaml/badge.svg?branch=main"></a> | | <a target="_blank" href="https://github.com/WebFiori/http/actions/workflows/php85.yaml"><img src="https://github.com/WebFiori/http/actions/workflows/php85.yaml/badge.svg?branch=main"></a> |

Key Features

RESTful API Development: Full support for creating REST services with JSON request/response handling
Automatic Input Validation: Built-in parameter validation with support for multiple data types
Custom Filtering: Ability to create user-defined input filters and validation rules
Authentication Support: Built-in support for various authentication schemes (Basic, Bearer, etc.)
HTTP Method Support: Support for all standard HTTP methods (GET, POST, PUT, DELETE, etc.)
Content Type Handling: Support for application/json, application/x-www-form-urlencoded, and multipart/form-data
Object Mapping: Automatic mapping of request parameters to PHP objects
Comprehensive Testing: Built-in testing utilities with APITestCase class
Error Handling: Structured error responses with appropriate HTTP status codes
Stream Support: Custom input/output stream handling for advanced use cases

Installation

Using Composer (Recommended)

composer require webfiori/http

Manual Installation

Download the latest release from GitHub Releases and include the autoloader:

require_once 'path/to/webfiori-http/vendor/autoload.php';

Quick Start

Modern Approach with Attributes (Recommended)

PHP 8+ attributes provide a clean, declarative way to define web services:

<?php
use WebFiori\Http\WebService;
use WebFiori\Http\Annotations\RestController;
use WebFiori\Http\Annotations\GetMapping;
use WebFiori\Http\Annotations\PostMapping;
use WebFiori\Http\Annotations\RequestParam;
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]
    #[RequestParam('name', ParamType::STRING, true)]
    public function sayHello(?string $name): string {
        return $name ? "Hello, $name!" : "Hello, World!";
    }
    
    #[PostMapping]
    #[ResponseBody]
    #[AllowAnonymous]
    #[RequestParam('message', ParamType::STRING)]
    public function customGreeting(string $message): array {
        return ['greeting' => $message, 'timestamp' => time()];
    }
}

Traditional Approach

For comparison, here's the traditional approach using constructor configuration:

<?php
use WebFiori\Http\AbstractWebService;
use WebFiori\Http\RequestMethod;
use WebFiori\Http\ParamType;
use WebFiori\Http\ParamOption;

class HelloService extends AbstractWebService {
    public function __construct() {
        parent::__construct('hello');
        $this->setRequestMethods([RequestMethod::GET]);
        
        $this->addParameters([
            'name' => [
                ParamOption::TYPE => ParamType::STRING,
                ParamOption::OPTIONAL => true
            ]
        ]);
    }
    
    public function isAuthorized() {
        return true;
    }
    
    public function processRequest() {
        $name = $this->getParamVal('name');
        $this->sendResponse($name ? "Hello, $name!" : "Hello, World!");
    }
}

Both approaches work with WebServicesManager:

$manager = new WebServicesManager();
$manager->addService(new HelloService());
$manager->process();

Core Concepts

Terminology

| Term | Definition | |:-----|:-----------| | Web Service | A single endpoint that implements a REST service, represented by AbstractWebService | | Services Manager | An entity that manages multiple web services, represented by WebServicesManager | | Request Parameter | A way to pass values from client to server, represented by RequestParameter | | API Filter | A component that validates and sanitizes request parameters |

Architecture Overview

The library follows a service-oriented architecture:

AbstractWebService: Base class for all web services
WebServicesManager: Manages multiple services and handles request routing
RequestParameter: Defines and validates individual parameters
APIFilter: Handles parameter filtering and validation
Request/Response: Utilities for handling HTTP requests and responses

Creating Web Services

Using Attributes (Recommended)

PHP 8+ attributes provide a modern, declarative approach:

<?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\RequestParam;
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]
    #[RequestParam('id', ParamType::INT, true)]
    public function getUser(?int $id): array {
        return ['id' => $id ?? 1, 'name' => 'John Doe'];
    }
    
    #[PostMapping]
    #[ResponseBody]
    #[RequestParam('name', ParamType::STRING)]
    #[RequestParam('email', ParamType::EMAIL)]
    public function createUser(string $name, string $email): array {
        return ['id' => 2, 'name' => $name, 'email' => $email];
    }
    
    #[PutMapping]
    #[ResponseBody]
    #[RequestParam('id', ParamType::INT)]
    #[RequestParam('name', ParamType::STRING)]
    public function updateUser(int $id, string $name): array {
        return ['id' => $id, 'name' => $name];
    }
    
    #[DeleteMapping]
    #[ResponseBody]
    #[RequestParam('id', ParamType::INT)]
    public function deleteUser(int $id): array {
        return ['deleted' => $id];
    }
}

Traditional Class-Based Approach

Every web service must extend AbstractWebService and implement the processRequest() method:

<?php
use WebFiori\Http\AbstractWebService;
use WebFiori\Http\RequestMethod;

class MyService extends AbstractWebService {
    public function __construct() {
        parent::__construct('my-service');
        $this->setRequestMethods([RequestMethod::GET, RequestMethod::POST]);
        $this->setDescription('A sample web service');
    }
    
    public function isAuthorized() {
        // Implement authorization logic
        return true;
    }
    
    public function processRequest() {
        // Implement service logic
        $this->sendResponse('Service executed successfully');
    }
}

Service Configuration

Setting Request Methods

// Single method
$this->addRequestMethod(RequestMethod::POST);

// Multiple methods
$this->setRequestMethods([
    RequestMethod::GET,
    RequestMethod::POST,
    RequestMethod::PUT
]);

Http

Install / Use

README