Come caricare estensioni PHP di terze parti in ServBay

ServBay è un potente ambiente di sviluppo Web locale che include molte delle estensioni PHP più comuni pronte all’uso. Normalmente, per attivarle, basta accedere a Packages -> Languages -> Versione PHP -> Estensioni all’interno dell’interfaccia di ServBay.

Tuttavia, capita che gli sviluppatori abbiano la necessità di caricare estensioni PHP di terze parti o compilate artigianalmente, che non sono incluse di default in ServBay. In questo articolo ti spieghiamo passo passo come caricare questo tipo di estensioni, prendendo come esempio ionCube Loader. La procedura è valida anche per altre estensioni Zend o file di estensione .so compilati da te.

Nota speciale sulle estensioni Zend: ionCube Loader è un’estensione di tipo Zend, che interagisce ancora più in profondità con il motore Zend di PHP. Per queste estensioni, occorre usare la direttiva zend_extension (e non la comune extension). Presta attenzione e utilizza la direttiva appropriata.

Prerequisiti

• Hai già installato e avviato ServBay su macOS.
• Hai i permessi da amministratore per accedere ai file di sistema e alle impostazioni di ServBay.
• Hai familiarità con l’uso del Terminal di macOS.
• Disponi del file di estensione PHP di terze parti da caricare (tipicamente un file .so), compatibile esattamente con la versione di PHP target in ServBay, l’architettura (Intel o Apple Silicon) e le opzioni di compilazione (come NTS/ZTS).

Attenzione: la compatibilità dell’architettura è fondamentale

ServBay fornisce pacchetti PHP nativi sia per architettura Intel (x86_64) che Apple Silicon (ARM64, come i chip M1/M2/M3/M4). Quando carichi file di estensione .so, assicurati sempre che siano compilati per la stessa architettura del pacchetto PHP di ServBay.

Non mescolare file di architetture diverse: l’incompatibilità impedirà a PHP di avviarsi o causerà crash.

Puoi usare il comando file per identificare l’architettura di un eseguibile o di un file .so:

1. Verifica l’architettura del pacchetto PHP fornito con ServBay (sostituisci 8.3 con la versione PHP che hai in uso):

   file /Applications/ServBay/package/php/8.3/current/bin/php

   Output tipico:

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable arm64 # Indica Apple Silicon ARM64

   oppure

   /Applications/ServBay/package/php/8.3/current/bin/php: Mach-O 64-bit executable x86_64 # Indica Intel x86_64

2. Verifica l’architettura del file di estensione .so che hai scaricato o compilato (sostituisci xdebug.so con il nome del tuo file):

   file xdebug.so

   Output tipico:

   xdebug.so: Mach-O 64-bit bundle arm64 # Indica Apple Silicon ARM64

   oppure

   xdebug.so: Mach-O 64-bit bundle x86_64 # Indica Intel x86_64

   L’architettura riportata nel punto 1 e 2 deve corrispondere perfettamente.

Procedura

Passo 1: Scarica il file dell’estensione di terze parti (esempio ionCube Loader)

1. Vai alla pagina ufficiale di download di ionCube Loader. Seleziona la versione adatta all’architettura del tuo macOS: per Apple Silicon ARM64 (serie M), scarica la versione Darwin ARM64. Ecco un link diretto di esempio (verifica sempre che sia aggiornato sul sito ufficiale): https://downloads.ioncube.com/loader_downloads/ioncube_loaders_dar_arm64.tar.gz
2. Una volta completato il download, avrai un archivio .tar.gz, ad esempio ioncube_loaders_dar_arm64.tar.gz.

Passo 2: Individua la versione PHP target e la directory delle estensioni in ServBay

1. Apri l’app di ServBay.

2. Dal menu di sinistra, seleziona Packages e poi Languages.

3. Sulla destra individua la versione PHP in cui vuoi installare ionCube Loader (nell’esempio, PHP 8.3). Prendi nota del numero di versione.

4. Trova la directory di installazione delle estensioni PHP (extension_dir) relativa a quella versione. Qui andranno posizionati i file .so. Il percorso esatto dipende dalla posizione di installazione ServBay, dalla versione PHP e dalle opzioni di compilazione.

   Il modo più sicuro è usare il Terminal:

   Apri il Terminal e lancia il seguente comando (assicurati di sostituire /Applications/ServBay/package/php/8.3/current/bin/php con il percorso esatto del binario PHP target):

   /Applications/ServBay/package/php/8.3/current/bin/php -i | grep extension_dir

   L’output sarà qualcosa come extension_dir => /path/to/extension/directory. Ad esempio:

   extension_dir => /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831

   Prendi nota esattamente di questo percorso, ti servirà nei passaggi successivi.

Passo 3: Estrai e posiziona il file Loader

1. Apri il Terminal.

2. Spostati nella cartella dove hai scaricato il file .tar.gz (di solito ~/Downloads):

   cd ~/Downloads

3. Estrai l’archivio:

   tar -zxvf ioncube_loaders_dar_arm64.tar.gz

   Verrà creata una cartella ioncube nella stessa directory.

4. Entra nella cartella ioncube:

   cd ioncube

5. All’interno troverai vari file .so per differenti versioni PHP, ad esempio ioncube_loader_dar_8.3.so. Identifica il file che corrisponde esattamente alla versione target scelta al passo 2.

6. Copia questo file .so nella directory delle estensioni individuata al passo 2. Se la destinazione fosse /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/ e vuoi installare per PHP 8.3:

   cp ioncube_loader_dar_8.3.so /Applications/ServBay/package/php/8.3/8.3.16/lib/php/extensions/no-debug-non-zts-20230831/

   • Ricordati di sostituire il percorso di destinazione con quello preciso ottenuto dal comando php -i al passo 2.
   • Assicurati che il file .so sia esattamente quello giusto per la versione di PHP selezionata e per l’architettura corretta (vedi prerequisiti).

Passo 4: Configura PHP in ServBay

1. Torna nell’app ServBay.

2. Nel menu di sinistra seleziona Languages, poi, nell’elenco a destra, scegli la versione PHP da configurare (ad es. PHP 8.3).

3. Nella sezione di destra, vai alla scheda PHP.

4. Scorri verso il basso fino al campo Additional Parameters.

5. Aggiungi questa riga di configurazione, indicando il nome corretto del file Loader:

   zend_extension = ioncube_loader_dar_8.3.so

   • Importante: Sostituisci ioncube_loader_dar_8.3.so col nome effettivo del file copiato nella directory delle estensioni.
   • Usa sempre zend_extension per ionCube Loader (estensione Zend).
   • Hai già posizionato il file nella directory extension_dir, quindi basta specificare il nome, senza percorsi completi.
   • Se ci sono altre direttive già presenti, inserisci questa su una nuova riga.

   (L’immagine è solo un esempio: l’aspetto reale può variare con le versioni)

6. Clicca su Save nell’angolo in basso a destra per salvare la configurazione.

Passo 5: Riavvia il servizio PHP

Dopo aver cliccato Save in ServBay, l’applicazione rileva automaticamente le modifiche e cerca di riavviare senza interruzioni i servizi coinvolti (incluso PHP). Di solito non occorre fare ulteriori riavvii manuali.

Passo 6: Verifica il caricamento dell’estensione

Puoi verificare che ionCube Loader sia stato effettivamente caricato in due modi:

1. Da linea di comando:

   • Apri il Terminal.

   • Esegui (specificando il percorso esatto di PHP):

     /Applications/ServBay/package/php/8.3/current/bin/php -m | grep -i ioncube

     Se è attivo, comparirà una riga tipo ionCube Loader.

   • Puoi anche lanciare il comando php -v per leggere la versione di PHP, che se caricato mostrerà il Loader subito dopo le info Zend:

     /Applications/ServBay/package/php/8.3/current/bin/php -v

     Esempio di output:

     PHP 8.3.16 (cli) (built: Jan 31 2025 15:09:39) (NTS)
     Copyright (c) The PHP Group
     Zend Engine v4.3.16, Copyright (c) Zend Technologies
         with the ionCube PHP Loader v14.4.0, Copyright (c) 2002-2024, by ionCube Ltd.

     Presta attenzione alla riga with the ionCube PHP Loader ....

2. Da phpinfo():

   • Crea un nuovo file PHP nella document root del sito (ad es. /Applications/ServBay/www/servbay.demo/ o altra cartella del sito), chiamato ad esempio info.php.
   • Metti solo questo codice al suo interno:

     <?php
     // Visualizza tutte le informazioni PHP
     phpinfo();
     ?>

   • Apri il file nel browser (http://servbay.demo/info.php, sostituisci col dominio usato in locale).
   • Cerca (con Cmd + F o Ctrl + F) la stringa "ionCube". Se il Loader viene caricato correttamente, troverai una sezione dedicata con la versione, le informazioni di licenza, ecc.

Se si vedono le info di ionCube Loader in uno dei due metodi, significa che il caricamento è avvenuto correttamente.

Problemi comuni e soluzioni

• PHP non si avvia o va in crash: Nella maggior parte dei casi, il problema è dovuto a differenze di architettura tra PHP e il file dell’estensione. Ricontrolla tutti i passaggi relativi alla compatibilità. Anche la versione di PHP o opzioni di compilazione incompatibili possono essere causa.
• Percorso extension_dir errato: Assicurati che il file .so sia stato copiato nell’esatto percorso dato da php -i | grep extension_dir.
• Errore nella direttiva di configurazione: Verifica che la direttiva aggiunta nei Parametri Aggiuntivi sia corretta. Usa zend_extension = filename.so per estensioni Zend, extension = filename.so per quelle standard, e il nome deve combaciare perfettamente (incluso maiuscole/minuscole).
• Permessi dei file: Controlla che l’utente usato da ServBay (di solito il tuo utente macOS) abbia i diritti di lettura sul file .so e sulla cartella di destinazione. Di norma, dopo una copia normale non ci sono problemi, ma se hai manipolato i permessi a mano, verifica.
• ServBay non si riavvia: Normalmente il riavvio è automatico, ma se la nuova configurazione non viene applicata, prova a fermare e riavviare i servizi dal pannello ServBay o chiudere e riaprire ServBay.
• Non vedi ionCube in phpinfo(): Verifica di essere sulla versione PHP corretta gestita da ServBay e che sia stato caricato l’ambiente sul sito giusto.

Conclusione

Seguendo questi passaggi dettagliati, puoi caricare correttamente ionCube Loader o altre estensioni PHP in formato .so per una qualsiasi versione gestita da ServBay. Gli aspetti essenziali sono identificare la versione PHP target, individuare la directory corretta dove depositare l’estensione (extension_dir), copiare lì il file compatibile e specificare il nome esatto nel campo Additional Parameters usando la direttiva giusta (zend_extension o extension). Se incontri problemi, consulta attentamente la sezione di troubleshooting, focalizzandoti soprattutto sulla compatibilità architetturale e sui percorsi dei file.