Compilare e Installare Moduli PHP Personalizzati in ServBay (macOS)

ServBay è un potente ambiente di sviluppo Web locale pensato specificamente per macOS, integrando una vasta gamma di pacchetti software utili agli sviluppatori moderni. Include di default PHP, Node.js, Python, Go, Java, database (come MySQL, PostgreSQL, MongoDB), sistemi di cache (Redis) e server web (Caddy, Nginx, Apache) offrendo così uno stack tecnologico completo. ServBay offre il supporto multiversione per ogni pacchetto, permettendoti di cambiare ambiente in modo flessibile in base alle esigenze di ogni progetto.

Sebbene ServBay includa già molti moduli PHP comunemente usati, in specifici scenari di sviluppo potresti aver bisogno di compilare e installare ulteriori moduli PHP per estendere le funzionalità o integrare servizi di terze parti.

Questa guida dettagliata ti mostrerà passo dopo passo come compilare e installare moduli personalizzati per la versione PHP desiderata nel contesto ServBay. Utilizzeremo come esempio la compilazione del popolare modulo di elaborazione immagini imagick e del driver database Microsoft SQL Server sqlsrv, illustrando l’intero processo per aiutarti ad ampliare funzionalità nella tua installazione di PHP su ServBay.

Prerequisiti

Avviso Importante

Prima di procedere con la compilazione di qualsiasi modulo PHP, è fondamentale seguire le istruzioni ufficiali di ServBay per l’inizializzazione dell’ambiente di compilazione e la corretta configurazione delle variabili d’ambiente di sistema. Questa fase è essenziale affinché la compilazione dei pacchetti ServBay (inclusi i moduli PHP) avvenga senza errori. Se salti o esegui erroneamente questa procedura, è molto probabile che si verifichino errori (es. comando non trovato, librerie mancanti, file header non trovati).

Lo script di inizializzazione dell’ambiente ServBay imposta variabili fondamentali, come PATH (puntamento agli strumenti di build di ServBay), SERVBAY_PACKAGE_FULL_PATH (radice dei pacchetti ServBay) e CPU_NUMBER (per la compilazione parallela). Queste variabili sono essenziali per le successive operazioni di build.

Per conoscere tutti gli step dettagliati di inizializzazione dell’ambiente di compilazione ServBay, consulta la guida: Ricompilare con ServBay. Accertati di aver compreso pienamente e seguito scrupolosamente tutte le configurazioni necessarie indicate nel documento.

Prima di procedere con la compilazione dei moduli, assicurati di aver completato con successo l’inizializzazione dell’ambiente di compilazione ServBay e che le variabili d’ambiente siano state configurate correttamente nella tua sessione terminale corrente.

L'importanza della Scelta della Versione PHP

Una delle principali caratteristiche di ServBay è il supporto multi-versione per PHP su un unico sistema. Questa flessibilità consente agli sviluppatori di cambiare rapidamente l’ambiente PHP per adattarsi a differenti progetti. Tuttavia, quando compili un modulo PHP, è obbligatorio associarlo esplicitamente alla versione PHP di destinazione. Gli strumenti chiave per la preparazione dell’ambiente di compilazione e il recupero delle informazioni di configurazione (phpize e php-config) sono specifici per ogni versione di PHP.

• phpize: script per preparare l’ambiente di compilazione delle estensioni PHP. Legge il file config.m4 e genera il tipico script configure, prima fase standard della compilazione di software C/C++.
• php-config: script che fornisce i dettagli di configurazione dell’installazione PHP di destinazione (flag del compilatore, directory include, directory delle librerie, cartella delle estensioni, ecc). Lo script configure interroga php-config per ottenere questi dati e garantire la corretta build e il collegamento del modulo alla PHP desiderata.

Quindi, ogni volta che usi phpize, php-config o altri comandi correlati alla compilazione PHP, devi sempre specificare il percorso completo della versione PHP per cui desideri compilare il modulo. Ad esempio, per PHP 8.3 installato in ServBay, dovrai usare /Applications/ServBay/package/php/8.3/current/bin/phpize e /Applications/ServBay/package/php/8.3/current/bin/php-config. Scegliere il percorso giusto garantisce che il modulo sia pienamente compatibile con l’ambiente PHP di destinazione ed evita errori di compilazione e problemi di caricamento runtime (es. simboli mancanti).

Gli esempi in questa guida sono relativi alla versione PHP 8.3 di ServBay. Quando operi in concreto, sostituisci i percorsi con quelli relativi alla tua effettiva versione PHP presente in ServBay.

Compilare il Modulo PHP imagick

Il modulo imagick è una delle estensioni più diffuse per PHP, fornendo potenti funzionalità di manipolazione immagini tramite la libreria ImageMagick. Con imagick potrai in PHP ridimensionare, ritagliare, convertire formati, applicare watermark, comporre immagini ed eseguire varie operazioni avanzate. Ecco come compilare e installare il modulo imagick per una versione PHP specifica in ServBay:

Step 1: Installare la Dipendenza ImageMagick

Il modulo PHP imagick necessita della libreria ImageMagick installata nel sistema. Su macOS si consiglia di utilizzare il gestore pacchetti Homebrew. Se non hai ancora installato Homebrew, consulta il sito ufficiale Homebrew.

Apri il terminale ed esegui il seguente comando per installare ImageMagick e le librerie di sviluppo:

brew install imagemagick

Step 2: Scaricare il Sorgente del Modulo imagick

Ora occorre scaricare il pacchetto sorgente del modulo imagick dal sito ufficiale PECL. Vai alla pagina PECL di imagick e scegli la versione desiderata (preferibilmente quella più recente e stabile). Nell’esempio usiamo la versione 3.7.0:

wget https://pecl.php.net/get/imagick-3.7.0.tgz

Step 3: Estrarre il Pacchetto Sorgente e Accedere alla Cartella

Dopo il download, estrai il pacchetto e accedi alla cartella dei sorgenti:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Step 4: Preparare l'Ambiente di Compilazione (con phpize)

Entrato nella cartella dei sorgenti, lancia phpize relativo alla versione PHP di destinazione, usando il percorso completo come spiegato in precedenza. Con variabile SERVBAY_PACKAGE_FULL_PATH già impostata:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Se il comando va a buon fine, phpize analizzerà il file config.m4 e genererà lo script configure e tutti i file di build necessari. Sul terminale vedrai un output che conferma che l’ambiente di build è pronto.

Step 5: Configurare le Opzioni di Compilazione

Esegui ora lo script configure per le impostazioni di compilazione, specificando il percorso di php-config tramite il parametro --with-php-config:

./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

Lo script configure farà tutte le verifiche necessarie (compresi i path di ImageMagick) e genererà il file Makefile per la build. In caso di errore, probabilmente manca una dipendenza o c’è un path errato.

Step 6: Compilare e Installare il Modulo

Se configure ha avuto successo e ha generato il Makefile, puoi procedere a compilare con make, seguito da make install per copiare il file dell’estensione nella directory delle estensioni di PHP. La variabile ${CPU_NUMBER} (impostata nell’inizializzazione di ServBay) indica il numero di processi paralleli per accelerare la compilazione.

make -j ${CPU_NUMBER}
make install

Il comando make install copierà automaticamente il file imagick.so nella directory delle estensioni della specifica versione PHP su ServBay (ad es. /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/, il percorso esatto può variare a seconda della versione e delle opzioni di build).

Step 7: Abilitare il Modulo

Dopo aver installato il file, devi abilitare l’estensione nel file di configurazione della versione PHP desiderata. ServBay offre un modo grafico per farlo.

• Apri l’app ServBay
• Dal menu a sinistra vai su Linguaggi - PHP - PHP 8.3
• Sul lato destro, seleziona la scheda PHP, scorri fino in fondo e nella sezione "Parametri extra", inserisci extension=imagick.so
• Clicca su Salva; il processo PHP verrà riavviato e caricherà il nuovo modulo

Step 8: Verificare il Caricamento del Modulo

Dopo aver abilitato il modulo, riavvia obbligatoriamente il servizio PHP utilizzato da ServBay affinché la nuova configurazione sia effettiva. Puoi farlo tramite l'interfaccia grafica di ServBay, selezionando il pacchetto PHP corrispondente e cliccando “riavvia”, oppure tramite la CLI ServBay (consulta la documentazione ufficiale per i comandi).

Verifica il caricamento di imagick con il comando:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep imagick

Utilizziamo il path completo per essere certi di interrogare la PHP giusta. L’opzione -m mostra tutti i moduli caricati. Se imagick risulta tra questi, la procedura è riuscita.

Per una verifica più approfondita, crea un file PHP (ad esempio info.php) nella tua root web (di default /Applications/ServBay/www) contenente <?php phpinfo(); ?> e naviga su http://localhost/info.php o sull’host configurato. Nella pagina di output di phpinfo(), cerca la voce "imagick" per confermare attivazione, configurazione e versione.

Compilare il Modulo PHP sqlsrv/pdo_sqlsrv

I moduli sqlsrv e pdo_sqlsrv sono estensioni ufficiali PHP per il collegamento e la gestione di database Microsoft SQL Server, basate sulle librerie ODBC di Microsoft. Se hai bisogno di connettere PHP su ServBay a database SQL Server, segui la procedura qui descritta.

Attenzione: Requisiti Essenziali

Per compilare e installare sqlsrv su macOS, devi prima installare il driver ODBC Microsoft SQL Server (msodbcsql18) e gli strumenti da linea di comando associati (mssql-tools18). Tali pacchetti non sono inclusi in ServBay, vanno installati manualmente.

Si consiglia l’uso di Homebrew. Se non l’hai già fatto, consulta Homebrew sito ufficiale.

Per installare i driver Microsoft ODBC e relativi tool con Homebrew, usa i seguenti comandi (potresti dover accettare la licenza impostando HOMEBREW_ACCEPT_EULA=Y):

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18 mssql-tools18

Assicurati che tali dipendenze siano installate prima di tentare la compilazione. Tipicamente saranno collocate in /opt/homebrew/ (Apple Silicon) o /usr/local/ (Intel). Sarà necessario riferirsi a questi percorsi in fase di build.

Suggerimento

sqlsrv e pdo_sqlsrv sono due moduli distinti e vanno compilati separatamente, ma la procedura è la stessa. L’esempio prosegue con sqlsrv.

Step 1: Installare Driver e Strumenti Microsoft ODBC

(Assicurati di aver già eseguito i comandi Homebrew per l’installazione di msodbcsql18 e mssql-tools18 come sopra.)

Step 2: Scaricare i Sorgenti dei Moduli sqlsrv/pdo_sqlsrv

Scarica i sorgenti dal sito PECL tramite:

wget https://pecl.php.net/get/sqlsrv-5.12.0.tgz  # sqlsrv
wget https://pecl.php.net/get/pdo_sqlsrv-5.12.0.tgz  # pdo_sqlsrv

Step 3: Estrarre il Pacchetto Sorgente e Accedere alla Cartella

Dopo aver scaricato il pacchetto, estrailo e accedi alla cartella dei sorgenti:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# La procedura per pdo_sqlsrv è identica, i prossimi passaggi sono illustrati solo per sqlsrv

Step 4: Preparare l'Ambiente di Compilazione (con phpize)

All’interno della cartella, esegui il phpize relativo alla PHP di destinazione (in questo esempio PHP 8.3):

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/phpize

Step 5: Configurare le Opzioni di Compilazione (inclusi i Path delle Dipendenze)

Poiché sqlsrv dipende fortemente dal driver ODBC Microsoft e da unixODBC installati via Homebrew, dovrai specificare i percorsi corretti tramite le variabili d’ambiente LDFLAGS e CPPFLAGS prima di chiamare ./configure. In aggiunta, specifica il path di php-config:

Adatta i percorsi in base all’architettura (su Intel /usr/local, su Apple Silicon /opt/homebrew). La sintassi per Apple Silicon:

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # Includi eventuali header extra
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS: indica i percorsi delle librerie (linking)
• CPPFLAGS: indica i percorsi degli header (includi unixODBC e altre dipendenze)
• ${CPPFLAGS} e ${LDFLAGS} preservano eventuali flag impostati da ServBay

Step 6: Compilare e Installare il Modulo

Dopo aver generato il Makefile, esegui la build:

make -j ${CPU_NUMBER}
make install

Il comando copierà i file sqlsrv.so e pdo_sqlsrv.so (se compilati entrambi) nella directory delle estensioni della PHP di riferimento.

Step 7: Abilitare il Modulo

Anche qui, una volta installato il file, devi abilitarlo dalla GUI ServBay.

• Apri ServBay
• Dal menu a sinistra Linguaggi - PHP - PHP 8.3
• Sulla destra, sotto il tab PHP, scorri fino a "Parametri extra" e inserisci extension=sqlsrv.so e extension=pdo_sqlsrv.so
• Salva; il servizio PHP verrà riavviato

Step 8: Verificare il Caricamento del Modulo

Dopo aver abilitato i moduli, riavvia obbligatoriamente il processo PHP in ServBay.

Dopo il riavvio, verifica tramite CLI:

${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep sqlsrv
${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php -m | grep pdo_sqlsrv

Se tutto è andato a buon fine, ritroverai sqlsrv e pdo_sqlsrv tra i moduli caricati. In alternativa, puoi verificare tramite la funzione phpinfo() come descritto nei passaggi per imagick.

FAQ (Domande Frequenti)

• D: Compilando compare l’errore "Cannot find autoconf" o simili?
  • R: Questo indica quasi sempre che l’ambiente di compilazione ServBay non è stato correttamente inizializzato. Torna alla sezione “Prerequisiti” e verifica di aver eseguito lo script e tutti i passaggi della guida Ricompilare con ServBay. Accertati che strumenti come autoconf, automake, libtool ecc. siano installati e referenziati nell’ambiente. Riavviare il terminale dopo l’inizializzazione spesso risolve.
• D: Lo script configure fallisce dicendo che non trova una libreria o un file header?
  • R: Significa che manca una dipendenza di sistema (libreria o header), oppure c’è un percorso errato.
    • Per imagick, assicurati che ImageMagick sia installato con Homebrew: brew install imagemagick.
    • Per sqlsrv, obbligatorio installare i driver ODBC Microsoft (msodbcsql18) e mssql-tools18 con Homebrew. Prima di eseguire ./configure, controlla LDFLAGS e CPPFLAGS per i percorsi /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include.
    • Assicurati che eventuali path e bin di Homebrew siano inclusi in PATH e nelle variabili dell’ambiente di compilazione ServBay.
• D: Errore durante make o make install?
  • R: Può avvenire per vari motivi:
    • Dipendenze mancanti: Controlla l’output, sarà indicato cosa manca. Installa ciò che occorre.
    • Configurazione errata: Rivedi i parametri di configure; verifica che --with-php-config punti alla PHP giusta.
    • Problemi di permessi: Il comando make install scrive nella directory delle estensioni ServBay. Se ci sono errori di permesso, puoi provare con sudo make install (usare con cautela e consapevolmente).
    • Sorgente danneggiato: Verifica che i file scaricati non siano corrotti.
• D: Il file .so del modulo esiste, è referenziato in .ini, ma non compare in php -m o in phpinfo()?
  • R:
    • Motivo principale: Il servizio PHP in ServBay non è stato riavviato. Dopo ogni modifica ai file .ini, assicurati di riavviare il pacchetto PHP dalla GUI o dalla CLI ServBay. Un semplice refresh o il riavvio del server web (Caddy/Nginx) non basta!
    • Verifica la sintassi dei file .ini e controlla che la linea sia extension=modulename.so.
    • Controlla che extension_dir in php.ini punti nella giusta directory. Puoi scoprirla con il comando php-config --extension-dir.
    • Il file modulo potrebbe essere corrotto o incompatibile: ricompilalo con attenzione, scarica la versione compatibile, e consulta i log di PHP (in logs nella directory di installazione ServBay) per eventuali messaggi di errore.

Conclusione

Seguendo attentamente i passaggi di questa guida, sarai in grado di compilare e installare con successo moduli PHP personalizzati (come imagick e sqlsrv) nell’ambiente locale ServBay su macOS. Gli aspetti cruciali sono:

1. Inizializzare correttamente l’ambiente di compilazione ServBay: è la base per tutte le operazioni successive.
2. Specificare la versione PHP corretta: usa sempre i percorsi completi a phpize e php-config relativi alla versione PHP per cui vuoi la build.
3. Gestire le dipendenze esterne: installa le librerie e tool di sistema richiesti (ImageMagick, driver ODBC Microsoft ecc.) e passa i path giusti tramite variabili d’ambiente come LDFLAGS e CPPFLAGS durante il ./configure.
4. Abilitare correttamente il modulo: aggiungi o modifica i file .ini nella cartella conf.d della PHP di destinazione, usando la direttiva extension=modulename.so.
5. Riavviare il servizio PHP in ServBay: ogni modifica ai moduli richiede un riavvio completo del pacchetto PHP per essere presa in carico.

ServBay, come ambiente di sviluppo locale completo, offre massima flessibilità per ogni esigenza. Oltre quanto illustrato su PHP, ServBay supporta e integra MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust e altre tecnologie. Offre inoltre utilità avanzate come richiesta certificati SSL reali con ACME, configurazione CORS facilitata, backup automatici (inclusi settaggi, siti, database, certificati), reset della password root dei database e certificati di CA locali per lo sviluppo HTTPS.

Speriamo che questa guida ti abbia aiutato ad abilitare tutte le funzionalità PHP di cui hai bisogno su ServBay. Se incontri altri problemi, consulta la documentazione ufficiale o il supporto della community ServBay.