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
  • 1️⃣ Créer une API REST simple
  • 2️⃣ Gérer un formulaire POST
  • 3️⃣ Travailler avec du JSON
  • 4️⃣ Gérer les sessions et l'authentification
  • 5️⃣ Redirections et headers HTTP
  • 6️⃣ Détecter le contexte de la requête
  • 7️⃣ Sécuriser ses tokens (CSRF)
  • 8️⃣ Exemple complet : Micro-framework minimaliste
• Pourquoi choisir wlib/http-server ?
  • Avantages
  • Quand l'utiliser ?
  • Quand éviter ?
• Référence rapide
  • Request – Lire la requête
  • Response – Construire la réponse
  • Session – Gérer les sessions
• 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 :

🚀 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

🎯 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é

1. Toujours valider les entrées – Ne faites pas confiance aux données utilisateur
2. Utiliser les filtres – $request->getServer() applique FILTER_SANITIZE_FULL_SPECIAL_CHARS par défaut
3. Régénérer les IDs de session – Appelez $session->regenerateId() après l'authentification
4. Protéger contre CSRF – Utilisez $session->setToken() et $session->checkToken()
5. Ne pas exposer d'informations sensibles – Vérifiez ce que vous retournez dans les réponses JSON
6. Gérer les erreurs proprement – Retournez les bons status codes (400, 401, 403, 404, etc.)
7. 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

© 2024 - wlib/http-server - Un package HTTP simple et efficace pour PHP