Compilare e installare moduli PHP personalizzati in ServBay

ServBay è un potente ambiente di sviluppo web locale per macOS e Windows, integrato con una vasta gamma di pacchetti software per soddisfare le esigenze degli sviluppatori moderni. Include PHP, Node.js, Python, Go, Java, vari database (MySQL, PostgreSQL, MongoDB), sistemi di caching (Redis) e web server (Caddy, Nginx, Apache), tutto in una soluzione che supporta più versioni per ciascun pacchetto, permettendo di adattare l'ambiente alle necessità specifiche di ogni progetto.

Anche se ServBay viene fornito con molti moduli PHP comunemente utilizzati, in certi scenari di sviluppo potresti aver bisogno di compilare e installare moduli PHP aggiuntivi per espandere le funzionalità di PHP o integrare servizi di terze parti.

Questa guida fornisce istruzioni dettagliate su come compilare e installare moduli personalizzati per la versione di PHP che utilizzi in ServBay. Useremo come esempio i moduli più richiesti, imagick per la manipolazione delle immagini e sqlsrv come driver per Microsoft SQL Server, così potrai aggiungere funzionalità avanzate al tuo ambiente PHP in ServBay senza difficoltà.

Prerequisiti

Nota Importante

Prima di compilare qualsiasi modulo PHP, il passaggio più fondamentale è inizializzare correttamente l'ambiente di compilazione, seguendo le istruzioni ufficiali ServBay e impostando correttamente le variabili d'ambiente di sistema. Questo è essenziale per compilare con successo qualsiasi pacchetto in ServBay (inclusi i moduli PHP). Se non esegui questo passaggio o lo esegui erroneamente, è molto probabile che la compilazione fallisca, incontrando errori come “comando non trovato”, “libreria mancante” o “header file non trovato”.

Lo script di inizializzazione dell’ambiente di compilazione di ServBay imposterà automaticamente le variabili richieste, ad esempio: PATH (indirizza agli strumenti di build interni di ServBay), SERVBAY_PACKAGE_FULL_PATH (punta alla directory radice dei pacchetti ServBay) e CPU_NUMBER (per la compilazione multi-core). Queste variabili sono essenziali per i comandi di compilazione successivi.

Per la procedura dettagliata su come inizializzare l'ambiente di compilazione ServBay, fai riferimento alla documentazione: Compilazione avanzata con ServBay. Assicurati di aver compreso e seguito scrupolosamente tutte le istruzioni.

Prima di procedere con la compilazione dei moduli, accertati di aver completato con successo l’inizializzazione dell’ambiente di compilazione ServBay e di aver impostato correttamente le variabili d’ambiente nella sessione del terminale.

Importanza della specifica della versione PHP

Una delle funzionalità chiave di ServBay è consentire l’installazione e l’esecuzione di più versioni PHP sulla stessa macchina. Questa flessibilità permette agli sviluppatori di lavorare facilmente su progetti diversi, ciascuno con una propria versione PHP. Tuttavia, quando compili moduli PHP, è indispensabile operare sulla versione PHP specifica. Gli strumenti fondamentali come phpize e php-config sono associati in modo stretto alla versione di PHP su cui vuoi lavorare.

• phpize: script per preparare l’ambiente di compilazione delle estensioni PHP, elabora il file config.m4 e genera lo script standard configure, passaggio tipico per la compilazione di software C/C++.
• php-config: fornisce informazioni di configurazione dettagliate sull’installazione PHP specifica (flag del compilatore, directory degli include, directory delle librerie, directory di installazione delle estensioni ecc.) Il comando configure ricava questi dati da php-config per garantire la compatibilità tra modulo e PHP di destinazione.

Pertanto, quando usi phpize, php-config o altri comandi legati al build di PHP, devi sempre specificare il percorso completo degli strumenti associati alla versione PHP per cui vuoi compilare il modulo.

Esempio Percorsi

Se vuoi compilare un modulo per PHP 8.3 installato in ServBay:

macOS:

• phpize: /Applications/ServBay/package/php/8.3/current/bin/phpize
• php-config: /Applications/ServBay/package/php/8.3/current/bin/php-config

Windows:

• phpize: C:\ServBay\package\php\8.3\current\bin\phpize
• php-config: C:\ServBay\package\php\8.3\current\bin\php-config

Scegliere il percorso corretto assicura che il modulo sia compatibile con la versione PHP di destinazione, evitando errori di compilazione o problemi di esecuzione come “simbolo non trovato”.

Tutti gli esempi in questo documento si riferiscono alla versione PHP 8.3 su ServBay. Sostituisci i percorsi con quelli della versione PHP effettivamente installata che vuoi usare.

Compilare il modulo PHP imagick

Il modulo imagick è una delle estensioni PHP più popolari, basata sulla potente libreria ImageMagick e offre una vasta gamma di funzioni per la manipolazione delle immagini. Con imagick, puoi ridimensionare, ritagliare, convertire formato, aggiungere watermark, comporre immagini e tanto altro da PHP. Ecco i passaggi dettagliati per compilare e installare imagick su una versione specifica di PHP in ServBay:

Fase 1: Installazione delle librerie ImageMagick

Il modulo PHP imagick richiede che la libreria ImageMagick sia installata sul sistema.

macOS

Consigliamo di usare Homebrew come gestore di pacchetti. Se non hai ancora installato Homebrew, visita il sito ufficiale Homebrew per le istruzioni.

Apri il terminale e installa ImageMagick e le relative librerie di sviluppo con:

brew install imagemagick

Windows

Gli utenti Windows devono scaricare e installare ImageMagick manualmente dal sito ufficiale ImageMagick, scegliendo la versione appropriata.

Assicurati di installare la versione che include le librerie di sviluppo, e aggiungi il percorso di installazione alle variabili d’ambiente di sistema.

Fase 2: Scaricare il sorgente del modulo imagick

Ora devi scaricare il pacchetto sorgente del modulo imagick dal sito ufficiale PECL. Vai alla pagina PECL di imagick, trova la versione che ti interessa (di norma la più recente stabile), e copia il link di download. Ad esempio, usando la versione 3.7.0:

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

Fase 3: Estrarre il pacchetto sorgente ed entrare nella directory

Dopo il download, estrai il pacchetto con tar e vai nella directory creata:

tar zxvf imagick-3.7.0.tgz
cd imagick-3.7.0

Fase 4: Preparare l’ambiente di build (con phpize)

All’interno della directory del modulo, usa lo strumento phpize della versione PHP di destinazione (come indicato sopra). Supponiamo di compilare per PHP 8.3 e che tu abbia già impostato la variabile d’ambiente SERVBAY_PACKAGE_FULL_PATH:

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

La riuscita esecuzione di phpize verifica il file config.m4 nel pacchetto sorgente, genera lo script configure e altri file necessari alla build. Il terminale mostrerà delle informazioni che confermano la preparazione dell’ambiente di compilazione.

Fase 5: Configurare le opzioni di compilazione

Ora esegui lo script configure (generato nel passaggio precedente) per impostare le opzioni di build. È fondamentale passare il parametro --with-php-config con il percorso del comando php-config della versione PHP di destinazione; così, lo script può accedere alle giuste configurazioni.

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

configure eseguirà vari controlli, tra cui la ricerca delle librerie/headers di ImageMagick, e genererà il file Makefile. Se compare un errore, spesso significa che una dipendenza manca o il percorso non è corretto.

Fase 6: Compilazione e installazione del modulo

Se la configurazione ha successo e viene generato il Makefile, puoi procedere con la compilazione tramite make e installazione con make install. La variabile ${CPU_NUMBER} (impostata tramite l’inizializzazione dell’ambiente ServBay) serve per la compilazione parallela, accelerando i tempi.

make -j ${CPU_NUMBER}
make install

make install copierà automaticamente il file dell'estensione nel percorso di destinazione standard della versione specifica di PHP in ServBay:

• macOS: /Applications/ServBay/package/php/8.3/current/lib/php/extensions/no-debug-non-zts-YYYYMMDD/
• Windows: C:\ServBay\package\php\8.3\current\lib\php\extensions\no-debug-non-zts-YYYYMMDD\

Il percorso esatto dipende dalla versione PHP e dalle opzioni di build.

Fase 7: Abilitare il modulo

Dopo l’installazione del file del modulo, devi abilitarlo nel file di configurazione PHP della versione di destinazione. ServBay offre un’interfaccia grafica per questo passaggio.

• Apri l’applicazione ServBay
• Nel menu a sinistra vai su Linguaggi - PHP - PHP 8.3
• Nella pagina a destra scegli la scheda PHP; in fondo, nel campo “Parametri extra”, inserisci extension=imagick.so
• Premi Salva; il processo PHP verrà riavviato automaticamente per applicare la nuova configurazione del modulo

Fase 8: Verifica il caricamento del modulo

Dopo aver abilitato il modulo, riavvia il pacchetto PHP di ServBay per applicare la nuova configurazione. Puoi farlo dall’interfaccia di gestione ServBay, cercando il pacchetto PHP corrispondente e cliccando sul pulsante di riavvio, oppure tramite tool a riga di comando forniti da ServBay (consulta la documentazione per i dettagli).

Dopo il riavvio, puoi verificare se il modulo imagick è stato caricato correttamente tramite terminale:

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

Così sei sicuro di usare l’eseguibile della versione PHP di ServBay desiderata. Il parametro -m elenca tutti i moduli PHP caricati. Se imagick è stato caricato, vedrai “imagick” nel risultato.

Un controllo più dettagliato consiste nel creare un file PHP (ad esempio info.php) nella directory di root del web (valori di default):

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

Inserisci il codice <?php phpinfo(); ?> e accedi tramite browser a http://localhost/info.php (o tramite il dominio configurato in ServBay). Cerca “imagick” nella pagina risultante per confermare l’attivazione e visualizzare info sulla configurazione/versione.

Compilare i moduli PHP sqlsrv/pdo_sqlsrv

I moduli sqlsrv e pdo_sqlsrv sono estensioni ufficiali PHP per la connessione e l’interazione con database Microsoft SQL Server, basate sull’ODBC driver fornito da Microsoft. Se hai bisogno di connettere il tuo ambiente PHP ServBay a una base dati SQL Server, è necessario compilare e installare questi moduli. Ecco come fare:

Prerequisito fondamentale

Prima di compilare/installare sqlsrv, devi prima installare il driver ODBC di Microsoft per SQL Server e gli strumenti correlati. Questi pacchetti non sono inclusi di default in ServBay e vanno installati manualmente.

macOS

Consigliato l’utilizzo di Homebrew. Se non installato, visita Homebrew sito ufficiale per la procedura.

Installa i driver/tools Microsoft ODBC con questi comandi Homebrew. Potresti dover accettare la licenza (imposta 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

Questi pacchetti verranno installati di solito in /opt/homebrew/ (Mac Apple Silicon) o /usr/local/ (Mac Intel). Fai riferimento a questi percorsi in fase di compilazione.

Windows

Per Windows, scarica e installa il Microsoft ODBC Driver per SQL Server dal sito Microsoft:

• Vai a Microsoft ODBC Driver for SQL Server
• Scarica la versione appropriata per il tuo sistema e installala
• Assicurati che il driver sia installato e riconosciuto dal sistema

Verifica che tutte le dipendenze richieste siano installate e funzionanti prima di compilare sqlsrv.

Suggerimento

sqlsrv e pdo_sqlsrv sono moduli diversi, devono essere compilati separatamente, anche se il processo è analogo. Di seguito vediamo l’esempio per sqlsrv.

Fase 1: Installare driver/tools Microsoft ODBC

(Fase obbligatoria, come da istruzioni sopra: assicurati che msodbcsql18 e mssql-tools18 siano installati con Homebrew.)

Fase 2: Scaricare il sorgente dei moduli sqlsrv

Scarica i pacchetti sorgente di sqlsrv e pdo_sqlsrv da PECL. Trova la versione richiesta alle seguenti pagine: PECL sqlsrv. Ad esempio, la versione 5.12.0:

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

Fase 3: Estrarre il pacchetto sorgente ed entrare nella directory

Dopo il download, estrai e accedi alla directory del modulo:

tar zxvf sqlsrv-5.12.0.tgz
cd sqlsrv-5.12.0

# pdo_sqlsrv segue lo stesso procedimento; qui vediamo solo sqlsrv come esempio.

Fase 4: Preparare l’ambiente di build (con phpize)

All’interno della directory, usa lo strumento phpize per la versione richiesta di PHP (ad esempio PHP 8.3):

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

Fase 5: Configurare le opzioni di build (comprese le dipendenze)

Per la configurazione serve specificare i percorsi dei driver ODBC installati tramite Homebrew. Imposta le variabili LDFLAGS e CPPFLAGS prima di lanciare ./configure, così lo script troverà le librerie necessarie. Passa sempre il parametro --with-php-config con il percorso giusto.

Adatta i percorsi secondo l’installazione di Homebrew sul tuo sistema (/opt/homebrew su Mac Silicon, /usr/local su Mac Intel). Nell’esempio si presume /opt/homebrew:

export LDFLAGS="-L/opt/homebrew/lib ${LDFLAGS}"
export CPPFLAGS="-I/opt/homebrew/opt/unixodbc/include -I/opt/homebrew/include ${CPPFLAGS}" # Include /opt/homebrew/include per tutti gli header necessari
./configure --with-php-config=${SERVBAY_PACKAGE_FULL_PATH}/php/8.3/current/bin/php-config

• LDFLAGS indica al linker dove trovare le librerie: -L/opt/homebrew/lib
• CPPFLAGS indica alle toolchain C/C++ dove cercare gli header, includendo le directory Homebrew pertinenti. ${CPPFLAGS} e ${LDFLAGS} mantengono eventuali altri flag già impostati dall’ambiente ServBay.

Fase 6: Compilazione e installazione del modulo

Dopo la riuscita configurazione e la generazione del Makefile, compila e installa il modulo:

make -j ${CPU_NUMBER}
make install

make install copierà i file delle estensioni sqlsrv.so e pdo_sqlsrv.so (se compilati insieme) nel percorso corretto per PHP in ServBay.

Fase 7: Abilitare il modulo

Dopo l’installazione, abilita il modulo nella configurazione di PHP tramite l’interfaccia grafica di ServBay:

• Apri ServBay
• Menu a sinistra -> Linguaggi - PHP - PHP 8.3
• Scheda a destra PHP; in fondo, nella sezione “Parametri extra”, inserisci extension=sqlsrv.so e extension=pdo_sqlsrv.so
• Salva; ServBay riavvierà il processo PHP

Fase 8: Verifica il caricamento del modulo

Dopo aver abilitato i moduli, riavvia sempre il pacchetto PHP per applicare le modifiche.

Verifica tramite terminale se i moduli sono caricati:

${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 vedi sqlsrv e pdo_sqlsrv nell’output, vuol dire che sono correttamente caricati. Puoi anche controllare tramite la funzione phpinfo().

Domande Frequenti (FAQ)

• D: Errore “Cannot find autoconf” o simili durante la compilazione?
  • R: Quasi sicuramente significa che l’ambiente di compilazione ServBay non è stato inizializzato correttamente. Torna alla sezione “Prerequisiti” all’inizio e segui attentamente la guida Compilazione avanzata con ServBay, assicurandoti di aver installato e referenziato tramite variabili d’ambiente tutti gli strumenti richiesti (autoconf, automake, libtool ecc.). In genere basta avviare lo script di inizializzazione e riavviare il terminale.
• D: Il comando configure fallisce dicendo che manca una libreria o un header?
  • R: Il modulo richiede una libreria di sistema o degli header che non sono installati, oppure il percorso specificato è errato.
    • Per imagick: verifica che le librerie di sviluppo ImageMagick siano installate (brew install imagemagick).
    • Per sqlsrv: controlla sempre che Microsoft ODBC Driver (msodbcsql18) e mssql-tools18 siano installati via Homebrew. Inoltre, prima di lanciare ./configure, verifica che le variabili LDFLAGS e CPPFLAGS includano i percorsi alle dipendenze necessarie (come /opt/homebrew/lib, /opt/homebrew/opt/unixodbc/include).
    • Verifica che l’ambiente di compilazione ServBay includa i percorsi Homebrew necessari, o eventualmente aggiungi manualmente la cartella bin di Homebrew al PATH.
• D: Errore make o make install?
  • R: Cause possibili:
    • Dipendenza mancante: Una libreria o file richiesto non è presente; installa ciò che ti viene indicato dall’output dell’errore.
    • Errore di configurazione: Ricontrolla i parametri dati a configure, in particolare che il percorso per --with-php-config sia esatto.
    • Permessi insufficienti: make install copia file nella directory delle estensioni PHP di ServBay; se ServBay non ha configurato correttamente i permessi, potresti aver bisogno di sudo make install (usalo con cautela).
    • Problema con il sorgente: Il pacchetto scaricato è danneggiato o incompleto.
• D: Il file .so del modulo è nel percorso corretto e abilitato nel file .ini, ma non compare in php -m o phpinfo()?
  • R:
    • Motivo più frequente: Non hai riavviato il pacchetto PHP in ServBay dopo la modifica. Riavvia tramite il pannello di ServBay o tramite tool a riga di comando. Riavviare solo il web server (Caddy/Nginx) o ricaricare la pagina non basta.
    • Errore sintassi dell’ini: Verifica che la sintassi nel file .ini sia corretta (extension=modulename.so).
    • Percorso errato della directory delle estensioni: Controlla che extension_dir in php.ini punti alla directory giusta. Usa php-config --extension-dir per verificare dove installa make install.
    • File modulo danneggiato o incompatibile: Ricompila il modulo, accertati che la versione sia compatibile con il tuo PHP e verifica eventuali errori nei log di PHP (di solito nella cartella logs di ServBay).

Conclusione

Seguendo i passaggi qui descritti puoi compilare e installare senza problemi moduli PHP personalizzati come imagick e sqlsrv nell’ambiente di sviluppo locale ServBay. La chiave è:

1. Inizializzare correttamente l’ambiente di compilazione ServBay: è la base per evitare problemi successivi.
2. Specificare sempre il percorso esatto della versione PHP: con phpize e php-config utilizza sempre i percorsi ServBay della versione PHP di destinazione.
3. Gestire le dipendenze esterne dei moduli: installa le librerie e tool richiesti dal modulo (es. ImageMagick, ODBC Microsoft), e passa le variabili d’ambiente corrette a configure (come LDFLAGS, CPPFLAGS) per trovare le risorse richieste.
4. Abilitare il modulo correttamente: crea o modifica il file .ini in conf.d della versione PHP, aggiungendo la direttiva extension=modulename.so.
5. Riavvia il pacchetto PHP in ServBay: solo così il modulo verrà caricato correttamente.

ServBay è una piattaforma completa che offre massima flessibilità per adattarsi a qualsiasi workflow di sviluppo: oltre ai moduli PHP, è già preconfigurato per MySQL, PostgreSQL, MongoDB, Redis, Caddy, Nginx, Apache, Node.js, Python, Go, Java, .NET, Ruby, Rust e molto altro. Tra le funzionalità offerte: richiesta automatica di certificati SSL tramite ACME, gestione CORS facilitata, backup automatici di dati e configurazioni (incluse impostazioni, siti, database, certificati SSL), reset della password root dei database, CA utente e CA pubblica di ServBay per sviluppo HTTPS, ecc.

Speriamo che questa guida ti aiuti ad arricchire l’ambiente PHP di ServBay secondo le tue necessità e a migliorare la produttività nello sviluppo web. In caso di ulteriori dubbi, consulta la documentazione ufficiale ServBay o le risorse della community.