password_compat è la libreria ufficiale pensata per portare le funzioni

password_hash(), password_verify() e password_needs_rehash() nei progetti che girano su versioni di PHP precedenti alla 5.5 (in particolare 5.3/5.4). In questo articolo vediamo requisiti, installazione, esempi d’uso e best practice per integrare l’hashing BCRYPT in modo sicuro anche su ambienti legacy.

Requisiti e compatibilità

• PHP ≥ 5.3.7 (oppure una build con la patch “$2y” retroportata, come spesso accade nelle distribuzioni RedHat).
• Nota: la build Debian 5.3.3 non è supportata.
• Per verificare la compatibilità, esegui il file version-test.php fornito con la libreria: se stampa “Pass”, puoi usarla in sicurezza.

Installazione

Metodo rapido (senza Composer)

1. Scarica la libreria e includi lib/password.php.
2. Richiama il file dove ti serve usare le funzioni password_*.

Schema di hashing BCRYPT con password_compat

<?php
require_once __DIR__ . '/lib/password.php'; // polyfill password_* per PHP < 5.5

Installazione via Composer

In alternativa, puoi installare il pacchetto da Packagist e lasciar gestire l’autoload a Composer.

Uso: esempi pratici

Creare hash di password

<?php
$hash = password_hash($password, PASSWORD_BCRYPT);

// con cost personalizzato (valori 4–31; punta a 0.1–0.5s di tempo):
$hash = password_hash($password, PASSWORD_BCRYPT, array('cost' => 10));

// oppure l'alias "sempre il più forte disponibile":
$hash = password_hash($password, PASSWORD_DEFAULT);

Importante: verifica sempre il valore di ritorno prima di salvarlo (in caso di errore può essere false o null). Se usi PASSWORD_DEFAULT, prevedi una colonna VARCHAR(255) per evitare troncamenti futuri quando l’algoritmo predefinito dovesse cambiare.

Verificare una password

<?php
if (password_verify($password, $hash)) {
    // password valida
} else {
    // password non valida
}

Rehash quando cambiano i parametri

<?php
if (password_verify($password, $hash)) {
    if (password_needs_rehash($hash, PASSWORD_BCRYPT, array('cost' => 12))) {
        $hash = password_hash($password, PASSWORD_BCRYPT, array('cost' => 12));
        // salva il nuovo hash nel database
    }
}

Best practice di sicurezza

• Usa sempre BCRYPT (o PASSWORD_DEFAULT) con un cost adeguato al tuo server: regola il valore finché l’hash impiega ~0.1–0.5s.
• Colonne DB capienti: imposta VARCHAR(255) per i campi hash, così non avrai problemi se l’algoritmo di default cambierà in futuro.
• Gestione errori: se una funzione password_* restituisce false, non salvare nulla e registra l’evento (log), notificando l’utente con un messaggio generico.
• Upgrade pianificato: password_compat è un ponte per ambienti legacy; programma l’aggiornamento a una versione moderna di PHP per beneficiare del supporto nativo e di algoritmi più evoluti.
• Protezione dei file: se integri la libreria in CMS come WordPress, previeni l’accesso diretto ai file PHP aggiungendo if ( ! defined('ABSPATH') ) exit; dove opportuno.

FAQ rapide

Quale valore usare per cost?

Non esiste un numero “magico”: aumenta il cost finché l’operazione di hashing impiega circa 100–500 ms sul tuo server di produzione. Così ottieni un buon equilibrio tra sicurezza e performance.

Cosa succede se resto su una versione non supportata?

La libreria può rifiutarsi di creare/verificare hash e restituire false. È un comportamento intenzionale per non esporre il progetto a implementazioni BCRYPT vulnerabili. Aggiorna PHP appena possibile.

Posso mescolare hash vecchi e nuovi?

Sì. Mantieni i vecchi hash finché gli utenti non effettuano il login; in quel momento, dopo password_verify(), esegui un rehash con i nuovi parametri e salva l’hash aggiornato.

Conclusioni

password_compat è una soluzione affidabile per portare le API moderne di gestione password nei progetti PHP 5.3/5.4. Ti consente di usare password_hash(), password_verify() e
password_needs_rehash() in modo coerente, mantenendo uno standard di sicurezza elevato in attesa dell’upgrade dell’ambiente. Integra la libreria, verifica i requisiti, imposta un cost adeguato e pianifica l’aggiornamento a una versione di PHP recente.

Aggiorna sempre le dipendenze e monitora le note di sicurezza: la protezione delle password è un processo, non un’azione singola.