README

Couche d'abstraction HTTP pour PHP 8.2+ : lecture de la requête, construction de la réponse, sessions et exceptions typées par statut HTTP.

La lib ne fournit ni routeur, ni middleware, ni conteneur. Response est un builder mutable : il n'implémente pas Psr\Http\Message\ResponseInterface, seul son corps est un StreamInterface PSR-7 (via nyholm/psr7).

Installation

composer require sopheos/pebble_http

Claude Code

Ce package fournit un skill Claude Code dans skills/pebble-http/. Il documente les patterns d'usage et les pièges de la librairie : redirect() qui réinitialise les en-têtes, parsing JSON qui exige un Content-Type exact, Session::start() à chaque requête, CORS trop permissif, préfixe de cookie ignoré, etc.

Dans un projet qui dépend de sopheos/pebble_http, copie-le une fois dans .claude/skills/ après composer install pour que Claude Code le charge automatiquement. Le nom du dossier doit correspondre au name déclaré dans SKILL.md :

cp -r vendor/sopheos/pebble_http/skills/pebble-http .claude/skills/pebble-http

Pour la maintenance de la lib elle-même, voir CLAUDE.md. Les bugs connus sont listés dans TODO.md.

Request

Pebble\Http\Request Récupération des données d'une requête HTTP.

Request::createFromServer() : static Lit $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES et php://input une seule fois, par valeur.
Request::create() : static Requête vide, à remplir avec setUri(), setServers(), setQueryParams(), setBodyParams(), setAttachements(), setCookies() (utile en test).

URL et données du serveur

uri() : string Chemin demandé, sans query string. Les // sont fusionnés et le / final est retiré, sauf s'il précède une query string (/a/?x=1 donne /a/).
baseUrl() : string Schéma et hôte, par exemple https://example.com. Chaîne vide sans HTTP_HOST.
currentUrl(bool $withQueryString = true) : string URL complète.
servers() : array Paramètres serveur ($_SERVER).
server(string $name) : mixed Un paramètre serveur, ou null.
time() : int Horodatage de la requête en secondes.
mtime() : float Horodatage de la requête avec une précision à la microseconde.

Méthode HTTP

method() : string Méthode HTTP (GET, POST, DELETE…), ou CLI en ligne de commande.
isGet(), isPost(), isPut(), isPatch(), isDelete() : bool Teste la méthode.
isClient() : bool Vrai en ligne de commande.
isAjax() : bool Vrai si X-Requested-With: XMLHttpRequest.
isSecure() : bool Vrai si $_SERVER['HTTPS'] est défini et différent de off. X-Forwarded-Proto n'est pas lu.

Cookies

cookies() : array Tableau des cookies.
cookie(string $name) : mixed Valeur d'un cookie, ou null.

Données de la requête

queryParams() : array Paramètres de la query string.
queryParam(string $name) : mixed Un paramètre de la query string.
bodyParams() : array Données du corps : $_POST, sinon JSON si Content-Type vaut exactement application/json, sinon le corps brut parsé comme une query string.
bodyParam(string $name) : mixed Une donnée du corps.
attachements() : array Fichiers envoyés, indexés par nom de champ. Un champ multiple (docs[]) devient une liste de fichiers, un champ simple garde la forme native de $_FILES.
attachement(string $name) : ?array Les données d'un champ fichier.

Client

userAgent() : ?string User agent.
ip() : string Adresse IP issue de REMOTE_ADDR uniquement, 0.0.0.0 si absente ou invalide.

Response

Pebble\Http\Response Construit une réponse HTTP. Toutes les méthodes set*/add* modifient l'instance et la renvoient.

Response::createFromServer() : static Reprend la version du protocole, secure des cookies selon HTTPS, et les en-têtes CORS de la requête (Origin, Access-Control-Request-*). N'appelle pas cors().
Response::create() : static Réponse vierge.
reset() : static Vide les en-têtes et le corps, garde la configuration.

Configuration

setStreamFactory(StreamFactoryInterface $factory) : static / getStreamFactory() Fabrique PSR-17 des corps, nyholm/psr7 par défaut.
setBuffer(int $buffer) : static Taille des blocs de emitBody(), 0 pour tout envoyer d'un coup.
setCookieDomain(), setCookiePath(), setCookieSecure(), setCookieHttponly(), setCookieSamesite() Réglages par défaut des cookies.
setCookiePrefix(string $prefix) : static Stocké mais jamais appliqué (voir TODO.md).
setCorsOrigin(), setCorsMethods(), setCorsHeaders() Valeurs utilisées par cors().

HTTP status

setProtocolVersion(string $version) : static Version du protocole, 1.1 ou HTTP/1.1.
setStatusCode(int $code, ?string $reason = null) : static Statut HTTP. Sans raison, celle des constantes Response::HTTP_* est utilisée, ou Unknown Status (cas de 419).
getProtocolVersion() : string / getStatusCode() : int

HTTP headers

addHeader(string $name, string $value, bool $replace = false) : static Ajoute un en-tête. Le nom est normalisé (x-foo devient X-Foo).
removeHeader(string $name) : static Supprime un en-tête.
getHeaders() : array, getHeader(string $name) : array, hasHeader(string $name) : bool
setContentType(string $mime, string $charset = "UTF-8") : static Définit le type. Une clé inconnue est utilisée telle quelle.
```
$res->setContentType('jpg');        // raccourci
$res->setContentType('image/jpeg'); // explicite
```
addCookie(string $name, $value, int $expire = 0, array $settings = []) : static Ajoute un cookie. La valeur est passée par urlencode(). samesite n'accepte que lax ou strict.
removeCookie(string $name) : static Expire un cookie.
redirect(string $url = "/", bool $temporary = true) : static Redirection 302 ou 301. Réinitialise en-têtes et corps, mais garde les cookies déjà ajoutés.
cache(int $age = 86400) : static Active le cache HTTP.
noCache() : static Désactive le cache HTTP.
cors(?string $origin = null, ?string $methods = null, ?string $headers = null) : static Ajoute les en-têtes CORS, toujours avec Access-Control-Allow-Credentials: true. Attention : avec createFromServer(), l'origine renvoyée est celle de la requête, quelle qu'elle soit (voir TODO.md).

Http body

setBody($body = "") : static Corps : StreamInterface, ressource, scalaire, Stringable ou null.
setBodyFile(string $filename, string $mode = 'r') : static Corps lu en flux depuis un fichier.
getBody() : StreamInterface
setText(string $data = '') : static Corps text/plain.
setJson(mixed $data = null, int $flags = 0) : static Corps application/json. Lève \JsonException si l'encodage échoue.
setJsonException(ResponseException $ex) : static Statut et corps JSON tirés de l'exception.

Rendering

emitHeaders() Envoie les en-têtes. Ne fait rien, sans erreur, si une sortie a déjà eu lieu.
emitBody(?int $bufferLength = null) Envoie le corps.
emit(?int $bufferLength = null) Envoie en-têtes et corps.

Session

Pebble\Http\Session Couche d'abstraction pour manipuler les sessions.

__construct(?\SessionHandlerInterface $handler = null) Gestionnaire de session optionnel (memcache, base de données…).
start(?string $id = null) : static Démarre la session et fait expirer les données flash et temporaires. À appeler à chaque requête.
id() : ?string Identifiant de session, null avant start().
close() : static Écrit et ferme la session.
destroy() : static Détruit la session.
reset() : static Supprime toutes les variables de session.
all() : array Toutes les données.
has(string $name) : bool Indique si une donnée existe.
get(string $name, $default = null) : mixed Valeur d'une donnée.
set(string $name, mixed $value) : static Enregistre une donnée.
delete(string $name) : static Supprime une donnée.

Flash data

Une donnée flash existe jusqu'à la requête suivante (à moins d'être re-marquée en flash).

setFlash(string $name, $value) : static
markFlash(string $name) : static Sans effet si la clé n'existe pas.
unmarkFlash(string $name) : static

Temp data

Une donnée temporaire existe pendant une durée donnée en secondes. Une durée ≥ 2592000 (30 jours) est traitée comme un timestamp absolu.

setTemp($name, $value, $time = 300)
markTemp(string $name, int $time = 300)
unmarkTemp(string $name)

Exceptions

Utilisées pour gérer globalement les erreurs des réponses HTTP.

ResponseException

Hérite de Exception et implémente JsonSerializable. Statut 418 par défaut.

ResponseException::create(string $error = 'default') : static
ResponseException::createWithStatus(int $status, string $error = 'default') : static
setErrors(array $errors) : static Configure les erreurs.
addError(string $key, mixed $value) : static Ajoute une erreur.
setExtra(array $extra) : static Configure des données additionnelles.
addExtra(string $key, mixed $value) : static Ajoute une donnée additionnelle.
jsonSerialize() ['status', 'error', 'errors', 'extra']. errors et extra valent null quand ils sont vides.

Liste des exceptions

Héritent de ResponseException.

UserException Erreur provenant de l'utilisateur, validation par exemple (statut 400).
AccessException Informations d'authentification non valides (statut 401).
ForbiddenException Accès interdit (statut 403).
EmptyException Ressource introuvable (statut 404).
NotAcceptableException Représentation demandée impossible (statut 406).
ExpiredException Jeton ou session expiré (statut 419, non standard).
LockException Ressource verrouillée (statut 423).
SystemException Erreur d'exécution, une panne par exemple (statut 500).

Tests

composer install
vendor/bin/phpunit

Les bugs connus sont figés par des tests annotés // BUG: qui vérifient le comportement actuel. Les tests de Session démarrent de vraies sessions PHP : phpunit.xml désactive session.use_cookies et session.cache_limiter pour que session_start() fonctionne en CLI.

sopheos / pebble_http

Package info

Security

Statistics