Come utilizzare il file .user.ini in ServBay: guida alla configurazione PHP localizzata

ServBay è un potente ambiente di sviluppo web integrato, progettato specificamente per gli sviluppatori e capace di supportare diversi linguaggi e stack tecnologici, tra cui una gestione versatile delle versioni PHP e opzioni di configurazione rapide. In fase di sviluppo, può capitare che progetti differenti richiedano impostazioni PHP diverse, come limiti sulle dimensioni di upload, limitazioni di memoria o livelli di report degli errori. Modificare direttamente il file php.ini globale influirebbe su tutti i progetti, risultando scomodo nella gestione multi-progetto.

Fortunatamente, PHP offre il meccanismo dei file .user.ini, che permette agli sviluppatori di definire set di configurazioni PHP personalizzati in una specifica cartella e nelle relative sottocartelle, senza toccare il php.ini globale. ServBay supporta completamente i file .user.ini, consentendo un'ottimizzazione semplice ed efficiente della configurazione PHP a livello di singolo progetto o directory.

Questa guida illustra il funzionamento dei file .user.ini, come implementarli in ServBay e fornisce esempi pratici di configurazione PHP personalizzata per un progetto.

Introduzione al file .user.ini

Il file .user.ini è una funzionalità introdotta in PHP dalla versione 5.3.0, pensata per offrire una modalità di configurazione più flessibile e sicura rispetto agli approcci tradizionali (php_value e php_flag in .htaccess di Apache). Permette agli sviluppatori di inserire un file .user.ini in una directory accessibile dal web, rendendo le direttive di configurazione contenute valide solo per quella cartella e tutte le sue sottocartelle.

Caratteristiche principali

1. Ambito locale: Le impostazioni definite in un file .user.ini si applicano solo a quella directory e alle sottodirectory, senza incidere sul file php.ini globale di ServBay né su altri progetti.
2. Alta flessibilità: Gli sviluppatori possono creare set di configurazione PHP specifici per ogni progetto, secondo necessità.
3. Gestione semplificata: Non occorre modificare file di configurazione globali del server o di PHP, riducendo il rischio di conflitti e garantendo maggiore indipendenza e portabilità tra progetti.
4. Nessun riavvio necessario: A differenza delle modifiche al php.ini, che spesso richiedono il riavvio di PHP-FPM o del web server, le modifiche al file .user.ini sono applicate in automatico dopo un intervallo determinato da user_ini.cache_ttl (per default 300 secondi, ovvero 5 minuti).

Direttive configurabili

Non tutte le direttive di configurazione PHP possono essere impostate tramite .user.ini. La possibilità dipende dalla cosiddetta “modalità di cambiamento” (Changeable Modes). Solo le direttive con modalità PHP_INI_USER, PHP_INI_PERDIR o PHP_INI_ALL sono gestibili via .user.ini.

Alcuni esempi comuni di direttive configurabili:

• upload_max_filesize
• post_max_size
• memory_limit
• display_errors
• log_errors
• max_execution_time
• session.save_path
• date.timezone

Le direttive in modalità PHP_INI_SYSTEM (es. extension_dir, zend_extension, disable_functions ecc.) non possono essere configurate tramite .user.ini ma solo tramite il file principale php.ini o tramite la configurazione del server web.

Per consultare la modalità di ogni direttiva, si consiglia la lettura della pagina del manuale PHP sulle direttive di configurazione di php.ini.

Utilizzo del file .user.ini in ServBay

L’utilizzo del file .user.ini in ServBay è decisamente intuitivo. Ecco i passaggi concreti, usando come esempio la configurazione di upload_max_filesize e memory_limit.

Immaginiamo che la root del vostro sito sia in /Applications/ServBay/www/, e che dobbiate personalizzare la configurazione PHP per un progetto denominato myproject, il cui root web si trova in /Applications/ServBay/www/myproject/public.

Passo 1: Identificare la directory di destinazione

Individuate la directory cui volete applicare le personalizzazioni. Solitamente si tratta della root pubblica su cui il web server pubblica la vostra applicazione (es. la cartella public di un progetto Laravel o Symfony), oppure una sottocartella che richiede una configurazione specifica.

Esempio: /Applications/ServBay/www/myproject/public

Passo 2: Creare o modificare il file .user.ini

Nella directory identificata, create un nuovo file chiamato .user.ini (se esiste già, modificatelo). Ricordate che i file preceduti da un punto (dotfile), come .user.ini, sono nascosti sui principali file system: potrebbe essere necessario abilitare la visualizzazione dei file nascosti nel vostro file manager.

Per creare il file da terminale:

cd /Applications/ServBay/www/myproject/public
touch .user.ini

Quindi aprite .user.ini in un editor di testo e aggiungete le direttive PHP necessarie, una per riga, ad esempio:

; Imposta il limite massimo di upload dei file a 20MB
upload_max_filesize = 20M

; Imposta il limite di memoria di PHP a 256MB
memory_limit = 256M

; Abilita la visualizzazione degli errori (da usare solo in ambienti di sviluppo)
display_errors = On

Salvate e chiudete il file.

Passo 3: Attendere che le modifiche siano attive o forzare un refresh

Le modifiche al file .user.ini non sono applicate in tempo reale, dato che PHP ne esegue il caching per motivi di efficienza. L’intervallo di aggiornamento è controllato dalla direttiva user_ini.cache_ttl, che di default è impostata su 300 secondi (5 minuti).

Se desiderate che le modifiche abbiano effetto immediatamente, potete seguire una delle seguenti opzioni (il risultato dipende dalla versione e configurazione di ServBay):

1. Riavvio di PHP-FPM: nell’interfaccia di ServBay, individuate la versione PHP in uso dal sito e riavviate il relativo servizio PHP-FPM.
2. Riavvio di ServBay: metodo drastico, ma è l’unico modo per resettare completamente tutti i servizi locali.
3. Attendere la scadenza cache: opzione preferibile, soprattutto in situazioni non urgenti.

Passo 4: Verificare l’attivazione del file .user.ini

Per accertarvi che le impostazioni di .user.ini siano state correttamente applicate, potete creare un semplice file PHP che mostri le informazioni di configurazione di PHP.

Nella stessa directory del file .user.ini (ad esempio /Applications/ServBay/www/myproject/public), create un file chiamato info.php con il seguente contenuto:

<?php
phpinfo();
?>

Salvate il file.

Poi, accedete tramite browser all’URL corrispondente al file info.php sul vostro sito ServBay. Ad esempio, se il vostro progetto su ServBay risponde a myproject.servbay.demo e info.php risiede nella cartella public, l’indirizzo sarà https://myproject.servbay.demo/info.php.

Nella pagina generata da phpinfo(), cercate le direttive inserite nel file .user.ini (es. upload_max_filesize, memory_limit, display_errors). Troverete due colonne:

• Master Value: il valore impostato nel file php.ini globale.
• Local Value: il valore attualmente in uso per lo script, che può derivare da .user.ini o dalla configurazione del server web.

Se per Local Value compaiono i valori definiti in .user.ini (es. 20M, 256M, On), significa che la configurazione locale è stata applicata con successo.

Nota importante: Dopo la verifica, è fondamentale rimuovere il file info.php o limitarne l’accesso, per motivi di sicurezza: il file espone dettagli sulla configurazione del vostro server.

Considerazioni aggiuntive e avvertenze

• Nome e posizione del file: il file deve essere denominato esattamente .user.ini e posizionato nella directory in cui si desidera applicare la configurazione. Avrà effetto su tale directory e su tutte le relative sottocartelle.
• Modalità delle direttive: ribadiamo che solo certe direttive possono essere impostate tramite .user.ini. Se tentate di configurare una direttiva in modalità PHP_INI_SYSTEM tramite .user.ini, semplicemente non funzionerà, senza mostrare errori. Controllate sempre la documentazione PHP.
• Caching: fate attenzione all’impostazione di user_ini.cache_ttl. Se dovete modificare frequentemente .user.ini e desiderate un effetto immediato, potete temporaneamente settare user_ini.cache_ttl su un valore basso (es. user_ini.cache_ttl = 5) nel php.ini globale, ma è sconsigliato in produzione perché potrebbe impattare le prestazioni. Ricordate che le modifiche al file php.ini richiedono il riavvio di PHP-FPM.
• Priorità delle configurazioni: La gerarchia delle impostazioni PHP è la seguente: valori di default < php.ini (o file .ini aggiuntivi caricati) < configurazione del web server (php_value/php_flag, se usati tramite modulo Apache/nginx) < .user.ini < funzioni chiamate via ini_set() negli script. .user.ini sovrascrive le direttive globali ma può essere a sua volta sovrascritto dagli script tramite ini_set().
• Sicurezza: evitate di inserire informazioni sensibili nel file .user.ini. Anche se valido solo per la directory, il file può comunque essere presente in percorsi accessibili dal web (benché normalmente la configurazione impedisca l’accesso diretto).

Domande frequenti (FAQ)

D: Ho creato il file .user.ini e aggiunto le impostazioni, ma sembrano non funzionare. Come mai?

R: Le possibili cause sono:

1. Nome o posizione del file errata: assicuratevi che il file si chiami esattamente .user.ini e sia nella directory corretta.
2. Direttiva non supportata: potreste aver tentato di configurare una direttiva non compatibile (modalità diversa da PHP_INI_USER o PHP_INI_PERDIR). Consultate la documentazione PHP.
3. Cache non ancora scaduta: attendete il tempo specificato da user_ini.cache_ttl (5 minuti di default) o riavviate PHP-FPM.
4. Errore di sintassi: controllate che il file .user.ini non contenga errori di sintassi.
5. Sovrascrittura da impostazioni prioritarie: verificate che uno script non utilizzi ini_set() per modificare nuovamente le impostazioni.

D: Qual è la differenza tra il file .user.ini e il file php.ini globale?

R: Il file php.ini globale interessa l’intero ambiente PHP (o tutte le applicazioni di una specifica versione PHP), applicando le stesse impostazioni a tutti gli script (salvo sovrascritture in configurazioni di ambito minore). Il file .user.ini agisce soltanto sulla directory in cui si trova e sulle relative sottocartelle, e consente la modifica solo di alcune direttive. Il vantaggio di .user.ini è il suo ambito limitato e la possibilità di personalizzazione per ciascun progetto senza intaccare la configurazione generale.

Conclusioni

Utilizzare i file .user.ini in ServBay è la soluzione raccomandata per gestire configurazioni PHP parte-specifiche del progetto. Offrono estrema flessibilità, permettendo agli sviluppatori di personalizzare l’ambiente PHP per singoli progetti senza interferire con altri progetti o con la configurazione globale di ServBay. Seguendo le istruzioni e gli esempi di questa guida, sarete in grado di implementare facilmente .user.ini nei vostri progetti ServBay, migliorando così efficienza nello sviluppo e semplicità nella gestione dell’ambiente. La filosofia di ServBay punta a offrire strumenti locali potenti e flessibili per gli sviluppatori, e il supporto avanzato dei file .user.ini ne è una chiara dimostrazione.