Download the PHP package webfiori/rest-easy without Composer

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.

Table of Contents

• Motivation
• 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

• Dynamic Status Codes with ResponseEntity

• Testing
• Examples

Motivation

With well-established PHP HTTP libraries available, you might wonder why this one exists.

Validation is not optional. In most frameworks, input validation is a separate step you wire up after defining your routes. Here, you cannot define an endpoint without declaring exactly what data it accepts, its type, and how it should be validated. The API contract is the code.

Minimal dependencies. The library has a single runtime dependency (webfiori/jsonx). No PSR-7 stack, no framework coupling, no transitive dependency tree. What you install is what you get.

One service, one unit. Each endpoint is a self-contained object with its own parameters, authorization logic, and processing — independently testable and self-documenting. Built-in OpenAPI spec generation is a natural result of this design.

Full control. Request parsing, header management, content negotiation, and response handling are all implemented internally. No hidden layers, no framework tax.

Supported PHP Versions

Build Status

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
• Per-Method Content Type Control: #[Consumes] annotation to accept custom content types (e.g. application/octet-stream, application/xml) on specific methods
• Object Mapping: Automatic mapping of request parameters to PHP objects
• Comprehensive Testing: Built-in testing utilities with ServiceTestCase 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)

Manual Installation

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

Quick Start

Modern Approach with Attributes (Recommended)

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

Traditional Approach

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

Both approaches work with RequestProcessor (recommended) or WebServicesManager:

Core Concepts

Terminology

Architecture Overview

The library follows a service-oriented architecture:

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

Creating Web Services

Using Attributes (Recommended)

PHP 8+ attributes provide a modern, declarative approach:

Traditional Class-Based Approach

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

Service Configuration

Setting Request Methods

Service Metadata

Parameter Management

Parameter Types

The library supports various parameter types through ParamType:

Adding Parameters

Simple Parameter Addition

Batch Parameter Addition

Parameter Options

Available options through ParamOption:

Custom Validation

Retrieving Parameter Values

Positional Parameter Injection

When using #[ResponseBody], method parameters are matched positionally to #[RequestParam] attributes. The PHP variable names do not need to match the request parameter names:

Allowing Empty Strings

By default, sending an empty string for a string parameter results in a validation error. Use allowEmpty: true in the #[RequestParam] attribute to accept empty strings:

This is the attribute equivalent of ParamOption::EMPTY => true in the array-based approach.

Reusable Parameter Sets

Implement the ParameterSet interface to group related parameters:

Use with attributes:

Or traditionally:

Cross-Field Validation

For validation rules that depend on multiple parameters together, use the #[Validate] attribute or override the validate() method:

Method-Specific Validation (Attribute)

Service-Wide Validation (Override)

Both run if defined — service-wide first, then method-specific. Errors are merged. If any errors exist, the request returns 422 with the error details.

Dynamic Status Codes with ResponseEntity

The ResponseEntity class allows #[ResponseBody] methods to return different HTTP status codes based on runtime logic:

Available Factory Methods

You can also use the constructor directly for custom status codes:

Testing

Using ServiceTestCase

Examples

Complete CRUD Service Example

For more examples, check the examples directory in this repository.

Key Classes Documentation

• AbstractWebService - Base class for web services
• WebServicesManager - Services management
• RequestParameter - Parameter definition and validation
• APIFilter - Input filtering and validation
• Request - HTTP request utilities
• Response - HTTP response utilities
• ErrorResponse - Standardized error response generation
• OpenAPIGenerator - Standalone OpenAPI spec generation

Content Negotiation

Use #[Produces] to declare what content types a method can return. The framework matches against the client's Accept header:

• No #[Produces] → always JSON (default, unchanged)
• Accept header doesn't match → 406 Not Acceptable
• Accept: */* or not set → server's first preference

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Examples: Examples Directory

Changelog

See CHANGELOG.md for a list of changes and version history.