Funzione PHP setcookie(): tutto quello che devi sapere

Come sviluppatore PHP, potresti dover impostare cookie per memorizzare informazioni lato client. La funzione setcookie() è una funzione PHP integrata che gestisce questa operazione. In questo articolo trattiamo la sintassi moderna, come impostare, leggere ed eliminare i cookie, le insidie più comuni e quando preferire le sessioni.

Cos'è la funzione setcookie()?

La funzione setcookie() è una funzione integrata di PHP che invia un header HTTP Set-Cookie al browser, chiedendogli di memorizzare un piccolo dato. Alla richiesta successiva il browser restituisce quel dato, ed è così che un protocollo senza stato come HTTP può "ricordare" le informazioni tra i caricamenti di pagina — ad esempio un token "ricordami", una preferenza di lingua o un ID di tracciamento.

Poiché un cookie è un header HTTP, setcookie() deve essere eseguita prima di qualsiasi output inviato al browser. Il cookie stesso non è disponibile immediatamente; compare nel superglobale $_COOKIE solo alla richiesta successiva, una volta che il browser lo ha rinviato.

Come usare la funzione setcookie()

Usare la funzione setcookie() è semplice. La sintassi basata su array per le opzioni è stata introdotta in PHP 7.3. In PHP 8.1, la sintassi posizionale legacy con sette parametri è stata deprecata. Ecco la sintassi moderna:

Sintassi PHP della funzione setcookie()

setcookie($name, $value, $options);

Il parametro $options è un array associativo che accetta le seguenti chiavi:

• expires: Il tempo di scadenza del cookie (timestamp Unix).
• path: Il percorso sul server in cui il cookie sarà disponibile.
• domain: Il dominio su cui il cookie sarà disponibile.
• secure: Indica se il cookie deve essere trasmesso solo tramite HTTPS.
• httponly: Indica se il cookie deve essere accessibile solo tramite HTTP.
• samesite: Limita il cookie alle richieste dello stesso sito. Accetta 'Strict', 'Lax' o 'None'. Nota: quando si usa 'None', è necessario impostare anche secure su true, altrimenti i browser moderni rifiuteranno il cookie.

Se si omette expires (o lo si imposta su 0), il cookie diventa un cookie di sessione — esiste solo fino alla chiusura del browser. Impostare expires su un timestamp futuro lo trasforma in un cookie persistente che sopravvive ai riavvii del browser.

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

Come usare la funzione setcookie()?

<?php

$options = [
    'expires'  => time() + (86400 * 30), // 30 days
    'path'     => '/',
    'domain'   => '.example.com',
    'secure'   => true,
    'httponly' => true,
    'samesite' => 'Lax'
];
setcookie('username', 'john', $options);

In questo esempio usiamo la funzione setcookie() per impostare un cookie di nome username con il valore john. Specifichiamo anche il tempo di scadenza a 30 giorni dal momento attuale, il percorso sul server come /, il dominio come .example.com, e impostiamo i flag secure, httponly e samesite per garantire che il cookie venga trasmesso solo tramite HTTPS, non sia accessibile tramite scripting lato client e sia limitato alle richieste dello stesso sito.

Lettura dei cookie

I cookie impostati con setcookie() sono automaticamente disponibili nell'array superglobale $_COOKIE nelle richieste di pagina successive. Puoi verificarne l'esistenza e leggerne i valori in questo modo:

if (isset($_COOKIE['username'])) {
    echo "Welcome, " . htmlspecialchars($_COOKIE['username']);
}

Eliminazione dei cookie

Per eliminare un cookie, devi impostare il suo tempo di scadenza su un timestamp nel passato. Il valore può essere lasciato vuoto.

setcookie('username', '', [
    'expires' => time() - 3600,
    'path'    => '/',
]);

Assicurati che path (e domain, se ne hai impostato uno) corrispondano ai valori usati durante la creazione del cookie. Un cookie impostato con path => '/admin' non verrà eliminato da una chiamata che usa path => '/', perché il browser li tratta come cookie diversi.

Note importanti

• Valore di ritorno: setcookie() restituisce true in caso di successo e false in caso di errore (anche quando gli header sono già stati inviati).
• Header già inviati: I cookie devono essere impostati prima che qualsiasi output venga inviato al browser (inclusi HTML, spazi bianchi prima di <?php o echo). Altrimenti PHP genererà un avviso "Headers already sent". Vedi headers_sent() per rilevare questo caso.
• Codifica automatica: setcookie() codifica automaticamente i valori dei cookie tramite URL encoding, quindi la codifica manuale di solito non è necessaria. Se devi memorizzare un valore verbatim senza codifica, usa invece setrawcookie().
• Limiti di dimensione: I browser limitano ogni cookie a circa 4 KB e limitano il numero di cookie che un singolo dominio può memorizzare, quindi i cookie sono pensati per valori piccoli, non per dati in blocco.

Cookie vs. Sessioni

I cookie risiedono nel browser e vengono inviati con ogni richiesta, quindi qualsiasi dato memorizzato è visibile (e modificabile) dall'utente. Per i dati sensibili, memorizza solo un identificatore nel cookie e mantieni i dati reali lato server con le sessioni PHP. Per una panoramica più ampia della gestione dei cookie in PHP, consulta il capitolo Cookie PHP.

Conclusione

La funzione setcookie() è uno strumento utile per impostare cookie nella tua applicazione web PHP. Comprendendo la sintassi moderna basata su array, impostandola prima di qualsiasi output e abbinando path/domain durante l'eliminazione, puoi gestire in modo affidabile i dati lato client — e sai quando preferire le sessioni.

Pratica