Come installare un'estensione Magento 2 con Composer: guida passo passo
Guida pratica per installare un'estensione Magento 2 con Composer: repository privati, auth.json, setup:upgrade, passaggi in modalità production, aggiornamenti, disinstallazione…

In questo articolo
Per installare un'estensione Magento 2 con Composer aggiungi il repository del fornitore (più le credenziali, se è privato), esegui composer require, abiliti il modulo, lanci bin/magento setup:upgrade, compili e fai il deploy dei contenuti statici se il negozio è in modalità production e infine svuoti la cache. Sono pochi comandi, ma l'ordine e la modalità di deploy contano.
Questa guida segue l'intera sequenza usando come esempio concreto l'estensione gratuita Conviro for Magento, poi spiega come aggiornare e disinstallare e come risolvere gli errori che incontrerai più probabilmente.
In sintesi
- Esegui ogni comando dalla root di Magento come proprietario del file system, dopo un backup, e sempre prima in staging.
- La modalità developer richiede setup:upgrade e lo svuotamento della cache; la modalità production richiede anche la compilazione e il deploy dei contenuti statici.
- Disinstalla in ordine inverso: prima rimuovi l'integrazione, poi disabilita, rimuovi il pacchetto ed esegui l'upgrade.
Prima di iniziare: i prerequisiti
Verifica questi punti prima di toccare la produzione:
- Accesso SSH e Composer sul server. Un'installazione basata su Composer non si può fare dal pannello di amministrazione.
- Un backup recente di codice e database e, idealmente, una copia di staging su cui fare i test.
- L'utente giusto. Esegui i comandi come proprietario del file system, non come root, altrimenti creerai problemi di permessi.
- La tua modalità di deploy. Controllala con
bin/magento deploy:mode:show. - Una finestra di manutenzione per la produzione:
bin/magento maintenance:enableprima,bin/magento maintenance:disabledopo.
Per l'estensione di Conviro in particolare servono anche Magento Open Source 2.4.4 o successivo con PHP 7.4 o 8.1–8.4, un URL del negozio in HTTPS, il cron di Magento in esecuzione e traffico HTTPS in uscita verso api.conviro.io. L'installazione dell'estensione (versione 1.4.1 al momento della stesura) è stata testata su:
| Magento | PHP | Tema |
|---|---|---|
| 2.4.4-p13 | 8.1 | Luma |
| 2.4.7-p4 | 8.3 | Luma |
| 2.4.9 | 8.4 | Luma e Hyvä 1.5.2 |
Adobe Commerce si basa sullo stesso framework ma non è ancora stato testato, Hyvä Checkout non è testato e i negozi su 2.4.0–2.4.3 restano sulla versione 1.3.5 dell'estensione.
Come installare un'estensione Magento 2 con Composer, passo dopo passo
Passo 1: aggiungi il repository Composer e le credenziali
Le estensioni private vengono distribuite dal repository Composer del fornitore. Dalla root di Magento:
composer config repositories.conviro composer https://repo.conviro.io
composer config http-basic.repo.conviro.io api <CONVIRO_API_KEY>
Il primo comando aggiunge il repository a composer.json. Il secondo salva le credenziali in auth.json, nella stessa cartella. Per Conviro, lo username è api e la password è una chiave API che trovi in Developers → API Keys nella dashboard di Conviro. Trovi altre informazioni sull'API di Conviro nella pagina per sviluppatori.
Tieni auth.json fuori dal controllo di versione. Di solito nello stesso file ci sono anche le chiavi di repo.magento.com.
Passo 2: esegui composer require e setup:upgrade
composer require conviro/module-aichat
bin/magento module:enable Conviro_AiChat
bin/magento setup:upgrade
Questi tre comandi sono il cuore di qualsiasi installazione di un modulo Magento 2:
composer requirescarica il pacchetto invendor/e lo registra incomposer.jsonecomposer.lock. Fai il commit di entrambi i file, così ogni ambiente installa la stessa versione.module:enableregistra il modulo inapp/etc/config.php.setup:upgradeapplica al database le patch di schema e di dati del modulo e aggiorna il registro dei moduli.
Passo 3: compila, fai il deploy e svuota la cache
In modalità production il codice generato e i file statici non vengono creati al volo, quindi esegui:
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
In modalità developer salta entrambi i comandi. In tutte e due le modalità, concludi con:
bin/magento cache:flush
Poi verifica che il modulo sia attivo ed esci dalla modalità manutenzione:
bin/magento module:status Conviro_AiChat
bin/magento maintenance:disable
Passo 4: collega l'estensione nell'admin
La maggior parte delle estensioni va configurata dopo l'installazione. Per Conviro, apri Stores › Settings › Conviro Setup. Una procedura guidata in 7 passaggi esegue un controllo dell'ambiente, poi fai clic su Connect to Conviro, approvi il negozio nella dashboard di Conviro e torni su Magento. In Magento non viene copiata nessuna chiave API né alcun token.
La procedura guidata crea un'integrazione Magento con privilegi minimi (OAuth 1.0a), ti fa scegliere le store view, cosa sincronizzare e quali azioni IA consentire, e verifica tutto con un evento di test. In seguito, la scheda Integration Health in Stores › Configuration › Conviro › AI Chat controlla connessione, autenticazione, webhook, catalogo, ordini, cron, versione e ambiente, con istruzioni per risolvere i problemi. La pagina di installazione e la documentazione di installazione coprono ogni passaggio. Per il collegamento serve un piano Conviro con accesso API, Pro o superiore (vedi i prezzi).
Aggiornare e disinstallare un modulo Magento 2
Aggiornamento
composer update conviro/module-aichat
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush
Come prima, compila e fai il deploy solo in modalità production. Quando esce una nuova versione, l'admin di Magento mostra un avviso con il comando esatto, e configurazione, chiave API e integrazione vengono mantenute.
Disinstallazione
L'ordine conta: la disconnessione si fa nella procedura guidata di configurazione, che sparisce quando rimuovi il modulo.
- Disconnetti il negozio nella procedura guidata di Conviro.
- Disabilita il modulo:
bin/magento module:disable Conviro_AiChat - Rimuovi il pacchetto:
composer remove conviro/module-aichat - Esegui
bin/magento setup:upgrade.
In modalità production, ricompila, rifai il deploy dei contenuti statici e svuota la cache come di consueto. Conviro cancella i dati del negozio 30 giorni dopo la disconnessione, o subito se lo scegli. La documentazione sulla disinstallazione elenca tutti i passaggi.
Errori comuni e come risolverli
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| "Allowed memory size exhausted" durante Composer | Limite di memoria di PHP | Esegui COMPOSER_MEMORY_LIMIT=-1 composer require ... |
| La compilazione esaurisce la memoria | Limite di memoria della CLI | Esegui php -d memory_limit=2G bin/magento setup:di:compile |
| Errore 401 o richiesta di credenziali dal repository | Chiave o username errati | Ripeti il comando http-basic; lo username è api |
"Permission denied" in generated/, var/ o pub/static/ |
Comandi eseguiti come root o con l'utente sbagliato | Correggi i proprietari dei file, poi riesegui come proprietario del file system |
| "Please upgrade your database" | setup:upgrade non eseguito | Esegui bin/magento setup:upgrade |
| I dati smettono di sincronizzarsi, la scheda di stato segnala il cron | Il cron non è in esecuzione | Esegui bin/magento cron:install e controlla crontab -l |
Il cron conta più di quanto sembri. Conviro scrive gli eventi di checkout, registrazione e salvataggio dei prodotti in una coda locale che il cron di Magento consegna in background. L'estensione è anche progettata in modo che le pagine dello storefront non chiamino Conviro da PHP e che gli ordini vengano elaborati anche se Conviro non è raggiungibile. Testa prima l'intero flusso in staging; dopo l'installazione ti aiuta la nostra checklist per testare un chatbot IA.
Domande frequenti
Devo eseguire setup:di:compile in modalità developer?
No. La modalità developer genera il codice al volo, quindi dopo aver installato un modulo bastano setup:upgrade e cache:flush. In modalità production esegui anche setup:di:compile e setup:static-content:deploy, altrimenti storefront e admin possono rompersi perché mancano il codice generato e i file statici.
Dove salva Composer le credenziali di un repository privato?
composer config http-basic.<host> <user> <password> le scrive in auth.json nella root del progetto, accanto a composer.json. Aggiungi --global per salvarle invece nella home Composer del tuo utente. In entrambi i casi, tieni auth.json fuori dal controllo di versione, così le chiavi non finiscono in giro.
Come verifico se un modulo Magento 2 è abilitato?
Esegui bin/magento module:status per elencare i moduli abilitati e disabilitati, oppure aggiungi il nome del modulo, per esempio bin/magento module:status Conviro_AiChat. Se risulta disabilitato, esegui module:enable, poi setup:upgrade e svuota la cache.
Posso installare un'estensione Magento senza accesso SSH?
Non con Composer. L'estensione di Conviro richiede accesso SSH o CLI e Composer sul server. Se il tuo hosting non li fornisce, chiedi al provider o alla tua agenzia di eseguire l'installazione. Con il piano Enterprise, il team di Conviro installa l'estensione senza costi aggiuntivi.
Prossimi passi
Esegui l'installazione in staging, completa la procedura guidata di configurazione e controlla la scheda Integration Health prima di ripetere tutto in produzione. Per una panoramica completa di cosa fa l'estensione una volta collegata, leggi la nostra panoramica dell'estensione chat IA per Magento 2. Pronto a collegare il tuo negozio? Crea il tuo account Conviro.
Pubblicato da
Conviro
Condivide approfondimenti su supporto clienti basato su IA, automazione chatbot e strategie di crescita SaaS.
Sviluppa su Conviro
Collega i workflow conversazionali al tuo stack
Consulta le risorse per sviluppatori e i pattern di integrazione prima di progettare l’implementazione.
Articoli correlati
Altri post
Engineering
IMAP o POP3 (e SMTP)? Come collegare una casella di assistenza a un assistente IA
7 min di lettura
Leggi l'articolo
Engineering
Cos'è un webhook? Guida per chi non programma: collegare il chatbot ai tuoi strumenti
7 min di lettura
Leggi l'articolo