Funzione PHP setrawcookie(): Tutto Quello che Devi Sapere

Come sviluppatore PHP, potresti dover impostare cookie grezzi nella tua applicazione web per memorizzare informazioni lato client. La funzione setrawcookie() è una funzione PHP integrata che consente di impostare un cookie grezzo. A differenza della funzione standard setcookie(), setrawcookie() non codifica il valore del cookie tramite URL, il che la rende utile quando è necessario memorizzare dati già codificati o stringhe binarie. In questo articolo esamineremo in dettaglio la funzione setrawcookie() — la sua sintassi, i parametri, la forma moderna con array di opzioni, le insidie comuni e le differenze rispetto a setcookie().

Questa pagina presuppone che tu abbia già compreso le basi dei cookie PHP. Se vuoi semplicemente memorizzare testo ordinario, setcookie() è di solito la scelta migliore — usa setrawcookie() solo quando devi inviare il valore esattamente com'è.

Cos'è la Funzione setrawcookie()?

La funzione setrawcookie() è una funzione integrata di PHP (disponibile da PHP 5.2.0) che consente di impostare un cookie grezzo lato client. Funziona aggiungendo un'intestazione HTTP di risposta Set-Cookie, quindi — come ogni funzione che emette intestazioni — deve essere chiamata prima che venga inviato qualsiasi output al browser (nessun HTML echeggiato, nessuna riga vuota prima di <?php, nessun BOM). Se l'output è già iniziato, l'intestazione viene ignorata silenziosamente. Consulta headers_sent() per sapere come rilevare questa situazione.

La funzione restituisce true se l'intestazione è stata accodata con successo e false in caso di errore. Nota che un valore restituito true non garantisce che il browser abbia accettato il cookie o che lo invierà di nuovo — significa solo che l'intestazione è stata emessa.

Come Usare la Funzione setrawcookie()

Usare la funzione setrawcookie() è semplice. Ecco la sintassi:

Sintassi PHP

setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

La funzione accetta sette parametri:

• $name: Il nome del cookie.
• $value: Il valore grezzo del cookie (non codificato tramite URL).
• $expire: Il tempo di scadenza come timestamp Unix.
• $path: Il percorso del server in cui il cookie sarà disponibile.
• $domain: Il dominio in cui il cookie sarà disponibile.
• $secure: Se il cookie deve essere trasmesso solo tramite HTTPS.
• $httponly: Se il cookie deve essere inaccessibile al JavaScript lato client.

Ecco un esempio di come usare la funzione setrawcookie() per impostare un cookie grezzo:

Esempio

<?php

$name = "username";
$value = "john";
$expire = time() + (86400 * 30); // 30 days
$path = "/";
$domain = ".example.com";
$secure = true;
$httponly = true;
setrawcookie($name, $value, $expire, $path, $domain, $secure, $httponly);

In questo esempio, utilizziamo la funzione setrawcookie() per impostare un cookie grezzo chiamato username con il valore john. Specifichiamo il tempo di scadenza come 30 giorni dal momento attuale (usando time() come base), il percorso del server come / e il dominio come .example.com. I flag secure e httponly sono impostati su true per garantire che il cookie venga trasmesso solo tramite HTTPS e sia inaccessibile al JavaScript lato client.

La firma con array di opzioni (PHP 7.3+)

Da PHP 7.3 è possibile passare un singolo array $options invece di argomenti posizionali. Questa è la forma raccomandata perché è l'unico modo per impostare l'attributo SameSite, che controlla se il cookie viene inviato nelle richieste cross-site:

<?php

setrawcookie("username", "john", [
    "expires"  => time() + (86400 * 30), // 30 days
    "path"     => "/",
    "domain"   => ".example.com",
    "secure"   => true,
    "httponly" => true,
    "samesite" => "Strict", // "Strict", "Lax", or "None"
]);

Quando si utilizza la forma con array, la chiave $expire si chiama expires (con la s), e samesite non ha un equivalente nella firma posizionale.

Leggere il cookie in seguito

Un cookie impostato in una richiesta non è disponibile in $_COOKIE finché il browser non lo rimanda in una richiesta successiva. In quella richiesta successiva lo si legge come qualsiasi altro cookie:

<?php

if (isset($_COOKIE["username"])) {
    echo "Welcome back, " . $_COOKIE["username"];
} else {
    echo "Cookie not set yet.";
}

Poiché setrawcookie() non codifica il valore, i byte memorizzati vengono restituiti esattamente com'erano — non c'è alcun passaggio automatico di urldecode() al ritorno.

Eliminare un cookie grezzo

Per rimuovere un cookie, impostalo di nuovo con un tempo di scadenza nel passato. name, path e domain devono corrispondere al cookie originale:

<?php

setrawcookie("username", "", time() - 3600, "/", ".example.com");

setrawcookie() vs setcookie()

La principale differenza tra setcookie() e setrawcookie() riguarda il modo in cui gestiscono il valore del cookie. setcookie() codifica automaticamente il valore tramite URL usando rawurlencode(), il che è sicuro per il testo standard ma può causare problemi se è necessario memorizzare dati già codificati o stringhe binarie. setrawcookie() salta questo passaggio di codifica, dandoti pieno controllo sul valore grezzo. Per la maggior parte dei casi d'uso standard, setcookie() è preferibile, ma setrawcookie() è essenziale quando si lavora con dati già codificati.

Una conseguenza pratica: con setrawcookie() sei responsabile di mantenere il valore compatibile con i cookie. Un valore di cookie grezzo non deve contenere determinati caratteri — caratteri di controllo, spazi bianchi, virgole, punti e virgola o segni di uguale — perché hanno un significato speciale nell'intestazione Set-Cookie. Se il tuo valore potrebbe contenere questi caratteri, codificalo tu stesso (ad esempio con rawurlencode()) prima di passarlo:

<?php

$raw = rawurlencode("john doe; admin=1"); // pre-encode unsafe bytes
setrawcookie("username", $raw, time() + 3600, "/");

Conclusione

La funzione setrawcookie() è uno strumento utile per impostare cookie grezzi nella tua applicazione web PHP. Comprendendo la sua sintassi, i parametri, la forma con array di opzioni e le differenze rispetto a setcookie(), puoi memorizzare in modo sicuro dati già codificati lato client. Ricorda di chiamarla prima di qualsiasi output, preferisci l'array di opzioni per poter impostare SameSite, e usala solo quando hai davvero bisogno di bypassare la codifica URL.

Argomenti correlati

• Cookie PHP — il quadro generale di come funzionano i cookie in PHP.
• setcookie() — il setter standard di cookie con codifica URL.
• Sessioni PHP — stato lato server, un'alternativa ai cookie.
• header() — invia intestazioni HTTP arbitrarie manualmente.
• headers_sent() — verifica se le intestazioni sono già state inviate.

Pratica