README

Un kit HTTP léger pour PHP, sans framework, sans complexité

🚀 Découvrez aussi wlib/skeleton qui vous propose une structure de départ clé en main pour démarrer votre prochain projet.

📋 Sommaire

À quoi sert ce package ?
Installation
Cas d'usage concrets
Pourquoi choisir wlib/http-server ?
Référence rapide
Intégration avec d'autres outils
- Avec un router externe (ex: fast-route)
- Avec un middleware PSR-15
Bonnes pratiques de sécurité
Licence

🎯 À quoi sert ce package ?

wlib/http-server est conçu pour les développeurs PHP qui veulent gérer proprement les requêtes HTTP, les réponses et les sessions sans alourdir leur projet avec un framework complet. Que vous construisiez une API, un microservice ou un site web simple, ce package vous donne les outils essentiels pour :

Capacité	Exemple d'utilisation
Lire les données de requête	Récupérer les paramètres GET/POST, les headers, le corps JSON
Construire des réponses HTTP	Retourner du JSON, du HTML, des redirections avec le bon status code
Gérer les sessions	Stocker des données utilisateur, gérer l'authentification, sécuriser avec des tokens
Manipuler les headers	Ajouter des headers CORS, Cache-Control, Content-Type
Détecter le contexte	Savoir si la requête est AJAX, JSON, mobile, etc.

🚀 Installation

composer require wlib/http-server

Prérequis : PHP 7.4

📚 Cas d'usage concrets

1️⃣ Créer une API REST simple

<?php
require 'vendor/autoload.php';

use wlib\Http\Server\Request;
use wlib\Http\Server\Response;

$request = new Request();
$response = new Response($request);

// Récupérer l'ID depuis l'URL : /api/users/42
$id = $request->get('id');

if (!$id) {
    $response->json(['error' => 'ID manquant'], 400);
    exit;
}

// Simuler une recherche en base
$user = ['id' => $id, 'name' => 'Jean Dupont', 'email' => 'jean@example.com'];

$response->json(['user' => $user], 200);

Ce que ça fait :

Vérifie que l'ID est présent dans les paramètres GET
Retourne une erreur 400 si manquant
Retourne l'utilisateur en JSON avec status 200

2️⃣ Gérer un formulaire POST

<?php
require 'vendor/autoload.php';

use wlib\Http\Server\Request;
use wlib\Http\Server\Response;

$request = new Request();
$response = new Response($request);

// Vérifier que c'est un POST
if (!$request->isPost()) {
    $response->json(['error' => 'Méthode non autorisée'], 405);
    exit;
}

// Récupérer les données du formulaire
$email = $request->post('email');
$password = $request->post('password');

// Validation simple
if (empty($email) || empty($password)) {
    $response->json(['error' => 'Email et mot de passe requis'], 400);
    exit;
}

// Traitement...
$response->json(['success' => true, 'message' => 'Connexion réussie'], 200);

Points clés :

$request->isPost() vérifie la méthode HTTP
$request->post('email') récupère le champ du formulaire
La réponse JSON inclut le bon status code

3️⃣ Travailler avec du JSON

<?php
require 'vendor/autoload.php';

use wlib\Http\Server\Request;
use wlib\Http\Server\Response;

$request = new Request();
$response = new Response($request);

// Vérifier que la requête contient du JSON
if (!$request->isJson()) {
    $response->json(['error' => 'Content-Type doit être application/json'], 415);
    exit;
}

// Récupérer le corps brut et le décoder
$rawJson = $request->getRawInput();
$data = json_decode($rawJson, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    $response->json(['error' => 'JSON invalide'], 400);
    exit;
}

// Répondre en JSON
$response->json([
    'received' => $data,
    'timestamp' => time()
]);

Astuces :

$request->isJson() vérifie le header Content-Type: application/json
$request->getRawInput() donne accès au corps brut de la requête
$response->json() définit automatiquement le header Content-Type

4️⃣ Gérer les sessions et l'authentification

<?php
require 'vendor/autoload.php';

use wlib\Http\Server\Request;
use wlib\Http\Server\Response;
use wlib\Http\Server\Session;

$request = new Request();
$response = new Response($request);
$session = new Session($request);

// Démarrer la session
$session->start();

// Vérifier si l'utilisateur est connecté
if ($session->get('user_id')) {
    // Utilisateur déjà connecté
    $userId = $session->get('user_id');
    $response->json(['user_id' => $userId, 'status' => 'connected']);
    exit;
}

// Authentification (exemple simplifié)
$token = $request->post('token');
if ($token === 'SECRET_TOKEN') {
    // Stocker l'ID utilisateur en session
    $session->set('user_id', 123);
    $session->set('user_role', 'admin');
    
    // Régénérer l'ID de session pour éviter la fixation
    $session->regenerateId();
    
    $response->json(['status' => 'authenticated']);
} else {
    $response->json(['error' => 'Token invalide'], 401);
}

Bonnes pratiques :

Toujours appeler $session->start() avant d'utiliser la session
Utiliser $session->regenerateId() après l'authentification
Stocker les données sensibles avec prudence

5️⃣ Redirections et headers HTTP

<?php
require 'vendor/autoload.php';

use wlib\Http\Server\Request;
use wlib\Http\Server\Response;

$request = new Request();
$response = new Response($request);

// Redirection temporaire (307)
// $response->redirect('https://example.com/new-page');

// Redirection permanente (301)
// $response->redirect('https://example.com/new-page', 301);

// Ajouter des headers personnalisés
$response->setHeader('X-Custom-Header', 'MaValeur');
$response->setHeader('Cache-Control', 'no-cache, must-revalidate');

// Pour les API : autoriser CORS
$response->setHeader('Access-Control-Allow-Origin', '*');
$response->setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');

// Envoyer une réponse HTML simple
$response->html('<h1>Bienvenue sur mon site !</h1>', 200);

Status codes courants :

200 OK – Succès
201 Created – Ressource créée
301 Moved Permanently – Redirection permanente
307 Temporary Redirect – Redirection temporaire
400 Bad Request – Requête invalide
401 Unauthorized – Non autorisé
403 Forbidden – Interdit
404 Not Found – Ressource introuvable
405 Method Not Allowed – Méthode HTTP non autorisée

6️⃣ Détecter le contexte de la requête

<?php
require 'vendor/autoload.php';

use wlib\Http\Server\Request;

$request = new Request();

// Informations sur le client
$ip = $request->getIP();           // Adresse IP du client
$browser = $request->getBrowser();  // Navigateur (Chrome, Firefox, etc.)
$os = $request->getOS();             // Système d'exploitation
$userAgent = $request->getUserAgent(); // User-Agent complet

// Informations sur la requête
$method = $request->getMethod();   // GET, POST, PUT, DELETE, etc.
$path = $request->getPathInfo();   // Chemin de l'URL
$isAjax = $request->isAjax();      // true si requête AJAX
$isJson = $request->wantsJson();   // true si le client attend du JSON

// Headers spécifiques
$contentType = $request->getContentType();     // Type de contenu
$contentLength = $request->getContentLength(); // Longueur du corps
$referer = $request->getReferer();             // Page référente

// Exemple : adapter la réponse selon le client
if ($request->wantsJson()) {
    echo json_encode(['message' => 'Réponse JSON']);
} elseif ($request->isAjax()) {
    echo 'Réponse AJAX';
} else {
    echo '<html>... Réponse HTML ...</html>';
}

7️⃣ Sécuriser ses tokens (CSRF)

<?php
require 'vendor/autoload.php';

use wlib\Http\Server\Request;
use wlib\Http\Server\Session;

$request = new Request();
$session = new Session($request);

$session->start();

// Au chargement du formulaire : générer un token
if ($request->isGet()) {
    $privateKey = 'ma_cle_privee_securisee';
    $session->setToken($privateKey, 'user_123');
    
    // Afficher le formulaire avec le token
    echo '<form method="POST">';
    echo '<input type="hidden" name="token" value="' . $_SESSION['token'] . '">';
    echo '<input type="text" name="data">';
    echo '<button>Envoyer</button>';
    echo '</form>';
}

// À la soumission du formulaire : vérifier le token
if ($request->isPost()) {
    $userToken = $request->post('token');
    $privateKey = 'ma_cle_privee_securisee';
    
    if ($session->checkToken($privateKey, 'user_123', $userToken)) {
        echo 'Token valide ! Traitement du formulaire...';
    } else {
        echo 'Token invalide ! Action suspecte détectée.';
        exit;
    }
}

8️⃣ Exemple complet : Micro-framework minimaliste

<?php
// index.php
require 'vendor/autoload.php';

use wlib\Http\Server\Request;
use wlib\Http\Server\Response;
use wlib\Http\Server\Session;

$request = new Request();
$response = new Response($request);
$session = new Session($request);
$session->start();

// Router simple
$path = $request->getPathInfo();
$method = $request->getMethod();

// Route : GET /api/users
if ($path === '/api/users' && $method === 'GET') {
    $users = [
        ['id' => 1, 'name' => 'Alice'],
        ['id' => 2, 'name' => 'Bob']
    ];
    $response->json(['users' => $users]);
}

// Route : POST /api/users
elseif ($path === '/api/users' && $method === 'POST') {
    $data = json_decode($request->getRawInput(), true);
    // Validation et traitement...
    $response->json(['created' => true, 'id' => 3], 201);
}

// Route : GET /profile (nécessite authentification)
elseif ($path === '/profile' && $method === 'GET') {
    if (!$session->get('user_id')) {
        $response->json(['error' => 'Non autorisé'], 401);
        exit;
    }
    $response->json(['user' => ['id' => $session->get('user_id')]]);
}

// Route : GET / (page d'accueil)
elseif ($path === '/') {
    $response->html('<h1>Bienvenue !</h1><p>Consultez <a href="/api/users">/api/users</a></p>');
}

// 404 pour tout le reste
else {
    $response->json(['error' => 'Page non trouvée'], 404);
}

// Envoyer la réponse
$response->send();

💡 Pourquoi choisir wlib/http-server ?

✅ Avantages

Critère	wlib/http-server	Framework complet
Poids	~10 Ko	1-10 Mo
Dépendances	Aucune	Nombreuses
Courbe d'apprentissage	10 minutes	Jours/semaines
Flexibilité	Totale	Limitée par le framework
Performances	Optimales	Bonnes (mais overhead)

🎯 Quand l'utiliser ?

✔ Micro-services – Pour des endpoints API légers et rapides
✔ Scripts PHP – Pour ajouter du HTTP proprement dans vos scripts
✔ Prototypes – Pour valider une idée rapidement
✔ Intégration – Pour ajouter des fonctionnalités HTTP à un projet existant
✔ Apprentissage – Pour comprendre comment fonctionne HTTP en PHP

❌ Quand éviter ?

✖ Applications complexes – Si vous avez besoin de routing avancé, ORM, templates
✖ Équipes grandes – Si vous avez besoin de conventions strictes
✖ Projets longs – Si vous prévoyez d'ajouter beaucoup de fonctionnalités

📋 Référence rapide

Request – Lire la requête

$request = new wlib\Http\Server\Request();

// Paramètres GET/POST
$request->get('param');      // GET parameter
$request->post('param');     // POST parameter
$request->inputs();          // Tous les inputs (GET + POST)

// Headers
$request->getHeader('Authorization');
$request->getHeaders();              // Tous les headers

// Informations serveur
$request->getIP();          // Adresse IP
$request->getMethod();      // GET, POST, etc.
$request->getPathInfo();    // Chemin de l'URL
$request->getQueryString(); // Query string

// Détection
$request->isGet();          // true si GET
$request->isPost();         // true si POST
$request->isAjax();         // true si AJAX
$request->isJson();         // true si JSON
$request->wantsJson();      // true si client attend JSON

Response – Construire la réponse

$response = new wlib\Http\Server\Response($request);

// Réponses rapides
$response->json(['data' => 'value']);               // JSON avec status 200
$response->json(['error' => '...'], 404);          // JSON avec status 404
$response->html('<h1>Hello</h1>');                   // HTML avec status 200
$response->html('<h1>Error</h1>', 500);             // HTML avec status 500
$response->redirect('https://example.com');        // Redirection 307
$response->redirect('https://example.com', 301);   // Redirection 301

// Méthodes avancées
$response->setStatus(201);                          // Changer status code
$response->setHeader('X-Custom', 'value');          // Ajouter un header
$response->setHeaders(['X-A' => 'a', 'X-B' => 'b']); // Ajouter plusieurs headers
$response->push('Chunk 1');                         // Ajouter du contenu
$response->push('Chunk 2');                         // Ajouter plus de contenu
$response->send();                                  // Envoyer la réponse

Session – Gérer les sessions

$session = new wlib\Http\Server\Session($request);
$session->start();                  // Démarrer la session

// Manipulation des données
$session->set('key', 'value');      // Stocker une valeur
$session->get('key');               // Récupérer une valeur
$session->get('key', 'default');    // Avec valeur par défaut

// Gestion de la session
$session->regenerateId();           // Régénérer l'ID (sécurité)
$session->getId();                  // Récupérer l'ID de session
$session->destroy();                // Détruire la session
$session->close();                  // Fermer la session

// Tokens CSRF
$session->setToken('secret_key', 'user_id');        // Générer un token
$session->checkToken('secret_key', 'user_id');      // Vérifier un token

// Configuration
$session->setSessionTimeout(3600);  // 1 heure de timeout
$session->setPath('/');             // Chemin du cookie

📦 Intégration avec d'autres outils

Avec un router externe (ex: fast-route)

<?php
require 'vendor/autoload.php';

use wlib\Http\Server\Request;
use wlib\Http\Server\Response;

// Initialisation
$request = new Request();
$response = new Response($request);

// Dispatcher (exemple avec FastRoute)
$dispatcher = new Dispatcher($routes);
$routeInfo = $dispatcher->dispatch($request->getMethod(), $request->getPathInfo());

switch ($routeInfo[0]) {
    case FastRoute\Dispatcher::NOT_FOUND:
        $response->json(['error' => 'Not Found'], 404);
        break;
    case FastRoute\Dispatcher::METHOD_NOT_ALLOWED:
        $response->json(['error' => 'Method Not Allowed'], 405);
        break;
    case FastRoute\Dispatcher::FOUND:
        $handler = $routeInfo[1];
        $vars = $routeInfo[2];
        call_user_func($handler, $request, $response, $vars);
        break;
}

$response->send();

Avec un middleware PSR-15

<?php
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class MyMiddleware implements MiddlewareInterface {
    public function process(
        ServerRequestInterface $request, 
        RequestHandlerInterface $handler
    ): ResponseInterface {
        // Avant le traitement
        $wlibRequest = new \wlib\Http\Server\Request();
        // ... faire quelque chose avec $wlibRequest
        
        $response = $handler->handle($request);
        
        // Après le traitement
        return $response;
    }
}

🔒 Bonnes pratiques de sécurité

Toujours valider les entrées – Ne faites pas confiance aux données utilisateur
Utiliser les filtres – $request->getServer() applique FILTER_SANITIZE_FULL_SPECIAL_CHARS par défaut
Régénérer les IDs de session – Appelez $session->regenerateId() après l'authentification
Protéger contre CSRF – Utilisez $session->setToken() et $session->checkToken()
Ne pas exposer d'informations sensibles – Vérifiez ce que vous retournez dans les réponses JSON
Gérer les erreurs proprement – Retournez les bons status codes (400, 401, 403, 404, etc.)
Configurer le timeout de session – $session->setSessionTimeout(1800) pour 30 minutes

📖 Licence

Ce package est distribué sous la licence CeCILL 2.1, une licence open source française compatible avec la GPL.

CeCILL (CEA CNRS INRIA Logiciel Libre) est une licence qui garantit la liberté d'utiliser, modifier et redistribuer le logiciel.

Pour plus d'informations : http://www.cecill.info

wlib / http-server

Maintainers

Package info

Statistics

Security