Come abilitare l’estensione MBstring su cPanel e WHM VPS

MBstring su cPanel/WHM: dove si abilita davvero

Quando in ambiente cPanel/WHM una web app segnala che mbstring manca, il punto non è “accendere una funzione” nel pannello come fosse un toggle unico. In pratica devi intervenire sulla combinazione versione PHP + handler + EasyApache 4 + eventuale MultiPHP. Se sbagli layer, installi il modulo nel posto giusto ma sulla versione sbagliata, e l’app continua a fallire con errori tipo Call to undefined function mb_strlen() o ext-mbstring missing.

La regola operativa è semplice: prima identifichi quale PHP sta servendo il sito, poi abiliti l’estensione per quella stessa versione, infine verifichi dal web e dalla CLI. Su cPanel/WHM moderno, quasi sempre si lavora con EasyApache 4 e con le utility yum/dnf o con l’interfaccia WHM. Se il server è vecchio e usa EasyApache 3, la logica cambia, ma oggi è il caso meno comune.

Prima verifica: quale PHP usa davvero il sito

Non dare per scontato che il PHP della shell coincida con quello del sito. In cPanel puoi avere più versioni installate, più handler e più domini con settaggi diversi. Il controllo minimo è questo:

Dal pannello WHM/cPanel: apri WHM > EasyApache 4 e controlla le versioni PHP installate; poi, per il singolo account, verifica in cPanel > MultiPHP Manager quale versione è assegnata al dominio.

Da shell, puoi vedere la versione CLI con:

php -v

Atteso: la versione mostrata qui è utile per la CLI, ma non basta per il sito. Per capire quella del sito, usa un file temporaneo o un controllo già presente nell’ambiente applicativo.

Se puoi creare un file di test nel document root del dominio, ad esempio public_html/info.php, inserisci:

<?php phpinfo();

Poi apri il file via browser e cerca mbstring e Loaded Configuration File. Quello ti dice quale php.ini è in uso e se l’estensione è già caricata.

Se il file phpinfo() non è accettabile in produzione, usa almeno un controllo in CLI con il binario specifico della versione, ad esempio /opt/cpanel/ea-php82/root/usr/bin/php -m. La differenza è importante: potresti avere mbstring abilitato per PHP 8.2 in CLI, ma non per il dominio che gira su PHP 8.1 o 8.3.

Metodo corretto su WHM con EasyApache 4

Su un VPS con WHM, il modo più pulito è installare il pacchetto dell’estensione per la versione PHP effettivamente usata dal sito. La famiglia dei pacchetti segue il pattern ea-phpXX-php-mbstring, dove XX è la versione. Per esempio, per PHP 8.2 il pacchetto è ea-php82-php-mbstring.

Puoi farlo da WHM > EasyApache 4 in modo visuale, oppure da shell se hai accesso root. In ambienti con più VPS, la CLI è spesso più rapida e meno ambigua.

Installazione via shell per una versione specifica:

sudo yum install ea-php82-php-mbstring

Su sistemi basati su Debian/Ubuntu con pacchetti compatibili e stack diverso il comando può cambiare, ma su cPanel/WHM l’uso tipico resta yum o dnf a seconda della release del sistema operativo. Se il pacchetto non esiste, non forzare: prima verifica che la versione PHP sia davvero installata in EasyApache 4.

Per controllare i pacchetti disponibili:

yum list available 'ea-php*-php-mbstring'

Se preferisci il pannello, in WHM vai su Software > EasyApache 4, entra nella personalizzazione dei pacchetti PHP e seleziona l’estensione mbstring per la versione interessata. Dopo l’applicazione, verifica che il pacchetto risulti installato e che il servizio web non abbia errori di caricamento.

Perché l’estensione può risultare installata ma l’app continua a non vederla

Questo è il caso più comune: il modulo c’è, ma l’app non lo vede. Le cause tipiche sono tre.

1. Versione PHP sbagliata. Hai installato ea-php82-php-mbstring, ma il dominio usa PHP 8.1 o 8.3.
2. Handler diverso. Il sito gira con PHP-FPM o lsphp e la configurazione del dominio è puntata altrove rispetto alla CLI.
3. Cache applicativa o opcache. L’estensione è stata aggiunta, ma il processo PHP attivo non è stato ricaricato in modo pulito.

Per falsificare rapidamente la prima ipotesi, controlla la versione dal sito e confrontala con il pacchetto installato. Per la seconda, verifica in MultiPHP Manager o in MultiPHP INI Editor che il dominio sia assegnato alla stessa versione PHP. Per la terza, riavvia il servizio PHP-FPM della versione coinvolta e ripeti il test.

Un controllo utile da shell è questo:

/opt/cpanel/ea-php82/root/usr/bin/php -m | grep -i mbstring

Atteso: una riga con mbstring. Se non compare, il modulo non è caricato per quella versione. Se compare in CLI ma non nel browser, il problema è nel mapping del dominio o nel reload del servizio web/PHP-FPM.

Attivazione da WHM quando il server usa MultiPHP

Se lavori più volentieri da GUI, il percorso corretto è questo:

1. Apri WHM.
2. Vai su EasyApache 4.
3. Controlla o modifica i pacchetti PHP installati.
4. Assicurati che mbstring sia selezionato per la versione PHP usata dal dominio.
5. Salva e applica le modifiche.
6. Vai su MultiPHP Manager e conferma che il dominio punti alla versione corretta.

Se l’account è gestito con MultiPHP INI Editor, ricorda che lì modifichi direttive INI, non installi estensioni. È un errore frequente confondere i due livelli. mbstring non si abilita aggiungendo una riga nel file di configurazione dell’account se il pacchetto non è presente nel sistema.

Questa distinzione conta soprattutto in hosting condiviso o in VPS con più ambienti: puoi avere la direttiva giusta nel posto sbagliato e perdere tempo a inseguire un problema che è in realtà di packaging, non di configurazione.

Verifica tecnica completa dopo l’installazione

Dopo l’installazione, fai almeno tre verifiche indipendenti. Non fermarti al “pacchetto installato”.

1. Verifica pacchetto: il sistema deve vedere il modulo installato.

rpm -q ea-php82-php-mbstring

Atteso: output con nome pacchetto e versione. Se non c’è, l’installazione non è andata a buon fine o stai controllando la versione sbagliata.

1. Verifica modulo: PHP deve elencare mbstring.

/opt/cpanel/ea-php82/root/usr/bin/php -m | grep -i mbstring

Atteso: una riga con mbstring. Se non compare, verifica il binario della versione corretta.

1. Verifica web: il sito deve caricare la funzione richiesta dall’app.

<?php
var_dump(extension_loaded('mbstring'));
var_dump(function_exists('mb_strlen'));

Atteso: bool(true) per entrambe le righe. Se la CLI è OK ma il browser no, il problema è ancora di versione o handler del virtual host.

Quando serve riavviare e cosa riavviare davvero

In molti casi l’estensione è disponibile appena installata, ma i processi PHP già in esecuzione possono restare con il vecchio stato fino a un reload. Su WHM, il servizio da considerare dipende dall’architettura:

• PHP-FPM: riavvia il pool o il servizio della versione PHP coinvolta.
• Apache: ricarica il servizio solo se l’handler o i moduli lo richiedono.
• LiteSpeed: il comportamento segue il pannello e il servizio LSWS, non Apache puro.

Su stack classico con PHP-FPM, il controllo minimo è verificare che il pool associato al dominio sia attivo. Un segnale utile è il log del servizio PHP-FPM, soprattutto se hai errori di startup legati a config corrotta o pacchetto incompleto.

Comando utile per il riavvio, da usare solo se stai davvero lavorando su quella versione:

sudo systemctl restart ea-php82-php-fpm

Atteso: nessun errore di systemd. Se fallisce, leggi subito lo stato del servizio:

sudo systemctl status ea-php82-php-fpm --no-pager

Se il restart non è necessario e il modulo è già visibile, evita interventi inutili: meno cambi fai, più facile è capire dove stava il problema.

Casi particolari: cloudlinux, selector e hosting multiutente

In ambienti con CloudLinux o PHP selector, la logica cambia ancora un po’. L’estensione può essere disponibile a livello di sistema ma non assegnata al singolo utente o al suo alt-php. In quel caso devi verificare sia il pacchetto di sistema sia la selezione lato account.

Se l’hosting usa selector, il controllo deve passare dal pannello utente o dagli strumenti CloudLinux, non solo da WHM. In pratica, il problema non è “manca mbstring sul server”, ma “mbstring non è nel profilo PHP scelto da quell’account”.

Qui il segnale più utile è sempre lo stesso: confronta l’output di phpinfo() dal dominio con quello della shell e con la configurazione del dominio nel pannello. Se i tre livelli non coincidono, hai trovato il punto di disallineamento.

Impatto applicativo: perché mbstring non è un dettaglio marginale

Molte applicazioni PHP moderne la considerano una dipendenza base. Framework, CMS e librerie la usano per manipolare stringhe UTF-8, validare input multibyte, gestire normalizzazione e lavorare con contenuti non ASCII senza corromperli. Senza mbstring, il sintomo non è sempre un errore esplicito: a volte vedi testi troncati, funzioni che restituiscono lunghezze sbagliate, problemi con emoji o caratteri accentati, parsing errato di template e import/export incoerenti.

Per questo, quando un sito “sembra funzionare ma in realtà no”, mbstring è una delle prime estensioni da controllare insieme a intl, xml e curl. In ambiente hosting, la differenza tra una pagina che si apre e una piattaforma che lavora correttamente spesso sta in pochi moduli PHP ben installati.

Procedura operativa consigliata in produzione

Se devi intervenire su un VPS cPanel/WHM in produzione, tieni una sequenza corta e reversibile.

1. Identifica la versione PHP del dominio in MultiPHP Manager.
2. Conferma se mbstring è già presente con phpinfo() o con il binario PHP corretto.
3. Installa il pacchetto ea-phpXX-php-mbstring per la versione giusta.
4. Ricarica il servizio PHP-FPM solo se necessario.
5. Ripeti il test applicativo che prima falliva.

Se qualcosa non torna, il rollback è semplice: rimuovi il pacchetto della versione errata o torna alla configurazione precedente del dominio. Prima di toccare più versioni insieme, fai sempre un controllo puntuale del mapping dominio-versione, altrimenti ti ritrovi con un modulo abilitato ma invisibile all’app giusta.

Un buon criterio pratico è questo: se il sito è fermo per un errore di estensione, non inseguire ottimizzazioni o tuning. Correggi il layer minimo, verifica con un controllo oggettivo, e solo dopo valuta se servono pulizia di cache, reload del servizio o adeguamenti del profilo PHP.

Checklist veloce finale

Prima di chiudere l’intervento, verifica questi punti:

• Il dominio usa la versione PHP attesa in MultiPHP Manager.
• rpm -q ea-phpXX-php-mbstring restituisce il pacchetto installato.
• /opt/cpanel/ea-phpXX/root/usr/bin/php -m mostra mbstring.
• extension_loaded('mbstring') e function_exists('mb_strlen') tornano true.
• Non ci sono errori nuovi in /usr/local/apache/logs/error_log o nei log PHP-FPM dopo il reload.

Assunzione: il server usa cPanel/WHM con EasyApache 4 e una versione PHP gestita per dominio tramite MultiPHP; se l’ambiente è diverso, il nome del pacchetto o il percorso del binario possono cambiare, ma la logica di verifica resta la stessa.