README

Composable HTTP controller building blocks for PHP 8.4+, built on Slim and Twig.

📚 Documentation

User guides (FR + EN), with narrative explanations and examples:

Auto-generated API reference (phpDocumentor):
👉 https://bcommebois.github.io/oihana-php-controllers

🧠 What is it?

oihana/php-controllers provides a composable Controller base class and a set of focused traits and helpers for building HTTP controllers on top of Slim and Twig: typed request-parameter extraction, pagination, language negotiation, file responses (download, streaming, HTTP range, ETag / 304), archives, uploads, encryption, CSRF, HTTP caching and JSON/CBOR serialization.

use DI\Container;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

use oihana\controllers\Controller;

use function oihana\controllers\helpers\getParamInt;

class HelloController extends Controller
{
    public function index( ServerRequestInterface $request, ResponseInterface $response, array $args ): ResponseInterface
    {
        $page = getParamInt( $request, 'page', 1 );
        return $this->json( $response, [ 'page' => $page ] );
    }
}

🚀 Features

• 🎛️ A composable Controller base and focused traits — params, pagination, languages, routing, status, Twig, JSON/CBOR.
• 🧩 Typed request-parameter extraction & strategies — ParamsTrait, ParamsStrategyTrait, the getParam*() helpers.
• 📥 File responses — download, streaming, HTTP range, ETag & 304 Not Modified, content headers.
• 🗜️ Archives, uploads & encryption — zip/tar, file upload and OpenSSL file encryption.
• 🛡️ CSRF, HTTP cache and language negotiation on top of Slim & Twig.
• 🖼️ Image responses & resizing via ext-imagick.
• 🧪 Full unit-test coverage ensuring reliability and maintainability.

💡 Designed to be composable, testable, and compatible with any PHP 8.4+ project.

📦 Installation

Requires PHP 8.4+ and the ext-imagick extension.

Install via Composer:

composer require oihana/php-controllers

✅ Tests & coverage

Run the full unit-test suite (PHPUnit, strict mode):

composer test

Run a single test case:

./vendor/bin/phpunit --filter PaginationTraitTest

Measure coverage (requires Xdebug or PCOV):

composer coverage        # text + Clover + HTML under build/coverage/
composer coverage:md     # readable Markdown summary (build/coverage/COVERAGE.md)

The suite runs in strict mode and targets 100% line coverage.

🧾 License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

👤 About the author

• Author : Marc ALCARAZ (aka eKameleon)
• Mail : marc@ooop.fr
• Website : http://www.ooop.fr

🛠️ Generate the Documentation

We use phpDocumentor to generate the documentation into the ./docs folder.

Usage

Run the command :

composer doc

🔗 Related packages

• oihana/php-models – document/PDO models used by the data controllers.
• oihana/php-files – file, archive and encryption helpers behind the file responses.
• oihana/php-core – core helpers and utilities used by this library.
• oihana/php-enums – strongly-typed constant enumerations for PHP.