Installare Laravel con Composer non significa solo lanciare un comando e aprire il browser. La differenza tra un progetto che parte e uno che resta fragile sta nei dettagli: versione di PHP, estensioni, permessi, document root corretta, database pronto e un web server configurato per riscrivere le richieste verso public/index.php. Se questi pezzi non sono allineati, l’errore arriva subito: pagina bianca, 500, asset mancanti o installazione incompleta.
Qui il percorso è quello pulito: si parte dai prerequisiti, si crea il progetto con Composer, si imposta il file .env, si verifica il funzionamento in locale e poi si passa alla pubblicazione su Apache o Nginx. L’obiettivo è avere un’installazione ripetibile, non un setup “funziona sul mio PC”.
Prerequisiti reali prima di lanciare Composer
Laravel richiede una base coerente. Oggi conviene partire con PHP 8.2 o superiore, Composer 2, un database supportato e alcune estensioni PHP che spesso mancano nelle installazioni minime. Se il server è una VM o un hosting Linux classico, controlla prima la versione del runtime e dei moduli caricati.
Verifica questi punti prima di creare il progetto:
- PHP compatibile con la versione di Laravel che vuoi installare.
- Composer installato e raggiungibile da shell.
- Estensioni come
mbstring,openssl,pdo,tokenizer,xml,ctype,json,fileinfo. - Un database pronto, se l’applicazione lo userà subito.
- Permessi di scrittura sulla directory del progetto per l’utente corretto.
Un controllo rapido evita di scoprire il problema a metà installazione:
php -v
composer -V
php -m | egrep 'mbstring|openssl|pdo|tokenizer|xml|ctype|json|fileinfo'
Se una estensione manca, non forzare l’installazione e basta: chiudi il gap a livello di pacchetto di sistema o di configurazione PHP. Su Debian/Ubuntu, per esempio, spesso basta installare il modulo corretto e riavviare il servizio PHP-FPM o Apache. Su ambienti con pannello, conviene farlo dal gestore PHP del pannello per evitare mismatch tra CLI e web server.
Creare il progetto Laravel con Composer
Il comando più diretto è composer create-project. Scarica lo skeleton dell’applicazione, risolve le dipendenze e prepara la struttura iniziale. È il metodo giusto quando vuoi un progetto nuovo, non un aggiornamento di uno esistente.
composer create-project laravel/laravel nome-progetto
Se vuoi una versione precisa, specifica il vincolo. Questo è utile quando devi allinearti a un ambiente esistente o a una policy aziendale sulle versioni supportate.
composer create-project laravel/laravel:^11.0 nome-progetto
Durante il download Composer può impiegare qualche minuto, soprattutto se il server ha poca banda o se il cache locale è vuoto. L’errore più comune in questa fase è la mancanza di permessi nella directory di destinazione. In quel caso non correggere con 777: assegna l’ownership all’utente giusto o lavora in una directory dove il tuo utente ha pieno controllo.
Se stai lavorando in una cartella già esistente, puoi anche usare composer install su un repository clonato, ma per una nuova installazione il flusso standard resta create-project. La differenza è sostanziale: nel primo caso Composer usa il file composer.lock, nel secondo costruisce il progetto partendo dal template ufficiale.
Struttura iniziale: cosa guardare subito
Una volta creato il progetto, entra nella directory e verifica i file principali. I punti che contano davvero all’inizio sono .env.example, artisan, la directory public/, la cartella storage/ e bootstrap/cache/. Sono i componenti che incidono subito su avvio, configurazione e scrittura dei file temporanei.
cd nome-progetto
ls -la
La presenza di public/index.php è cruciale: il web server deve puntare lì come document root. Se serve servire il progetto dal root del dominio senza configurare bene il vhost, è facile esporre file interni o rompere il routing. In Laravel la directory pubblica non è una scelta opzionale, è il confine corretto tra web ed applicazione.
Configurare il file .env senza improvvisare
Il file .env contiene i parametri operativi dell’applicazione: nome, ambiente, chiave, connessione al database, cache, mail e altri valori. Dopo la creazione del progetto, il file va generato o copiato da .env.example. Laravel lo usa per separare configurazione e codice, quindi non conviene trattarlo come un dettaglio.
cp .env.example .env
php artisan key:generate
Il comando key:generate crea APP_KEY, necessaria per crittografia e sessioni. Se la chiave manca, l’applicazione mostra errori o si comporta in modo anomalo. Non inserire chiavi a mano in chiaro dentro documentazione, ticket o repo pubblici: se una chiave è stata esposta, va ruotata.
Un esempio minimo di configurazione iniziale può essere questo:
APP_NAME="Laravel"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel_user
DB_PASSWORD=********
La password qui è mascherata apposta: in produzione il segreto non va mai riportato in chiaro in guide, screenshot o snippet condivisi. Se devi distribuire la configurazione, usa redazione o un sistema di secret management. Se il valore è già finito in giro, la strada corretta è la rotazione.
Installare le dipendenze del progetto
Se hai creato il progetto con create-project, Composer ha già installato i pacchetti necessari. In caso di repository clonato o di ambiente ripristinato, il passaggio successivo è:
composer install
Questo comando legge composer.lock e installa le versioni bloccate. È il comportamento desiderabile in produzione o su staging, perché evita sorprese dovute a aggiornamenti automatici delle dipendenze. Se invece usi composer update, stai cambiando il grafo delle librerie: è un change controllato, non un passaggio neutro.
Verifica che Composer non segnali conflitti di versione. Un errore sulle estensioni PHP o sulla versione del runtime non si risolve forzando il pacchetto: bisogna allineare ambiente e requisiti dell’applicazione. Il controllo pratico è semplice: leggere il messaggio, confrontarlo con php -v e con l’output di php -m.
Permessi corretti per storage e cache
Laravel deve poter scrivere in storage/ e bootstrap/cache/. Se questi percorsi non sono scrivibili dall’utente del web server o dal processo PHP-FPM, l’applicazione si rompe in modo poco elegante: log mancanti, cache non generata, errori 500 o sessioni non persistenti.
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R ug+rwX storage bootstrap/cache
Il gruppo e l’utente possono cambiare in base alla distro e al web server. Su alcuni sistemi l’utente è apache, su altri nginx o un utente dedicato del pannello. Il criterio non cambia: il processo che esegue PHP deve poter scrivere solo dove serve, non sull’intero progetto.
Se vuoi evitare conflitti tra utenti diversi, una pratica pulita è usare un gruppo condiviso per il progetto, assegnare i permessi di gruppo e tenere il resto del filesystem più restrittivo. È più ordinato del classico “apri tutto” e riduce il rischio di modifiche accidentali fuori dai percorsi necessari.
Avvio in locale con Artisan
Per un test rapido, Laravel include un server di sviluppo integrato. Non è il modo corretto per pubblicare in produzione, ma è perfetto per validare che progetto, configurazione e dipendenze siano coerenti.
php artisan serve
Di default ascolta su http://127.0.0.1:8000. Se la pagina non si apre, controlla prima la console: il problema spesso è un errore PHP, una chiave mancante o una dipendenza non installata. Se il comando parte ma il browser mostra errore, verifica anche il file storage/logs/laravel.log.
Per un controllo più rigoroso, puoi eseguire una route di prova o aprire la homepage e osservare il comportamento. Se compare una pagina bianca, non saltare subito alle ipotesi esotiche: in molti casi è un APP_KEY non generato, una configurazione errata del database o un errore fatale in un service provider.
Preparare il database e la migrazione iniziale
Se l’applicazione userà un database, crea prima utente e schema. Il principio è semplice: l’installazione non deve dipendere da credenziali amministrative permanenti. Usa un utente con privilegi limitati allo schema dell’applicazione.
mysql -u root -p
CREATE DATABASE laravel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'password_forte';
GRANT ALL PRIVILEGES ON laravel.* TO 'laravel_user'@'localhost';
FLUSH PRIVILEGES;
Il comando sopra è un esempio operativo, ma la password va gestita fuori dai documenti. In ambienti reali usa un secret store, un vault o almeno un file di configurazione protetto dal filesystem. Dopo aver configurato .env, esegui le migrazioni:
php artisan migrate
Se le migrazioni falliscono, il log ti dice subito se il problema è la connessione, il driver o lo schema. Qui la diagnosi è molto più veloce se confronti DB_HOST, credenziali e disponibilità del servizio database prima di toccare il codice.
Pubblicare Laravel su Apache o Nginx
In produzione il document root deve puntare a public/. È il punto che più spesso viene sbagliato quando si copia un sito PHP tradizionale. Laravel non va pubblicato dalla root del progetto, perché esporresti file interni e soprattutto romperesti il routing.
Apache
Con Apache, il virtual host deve avere DocumentRoot verso la cartella public e AllowOverride All se usi il file .htaccess per le rewrite.
<VirtualHost *:80>
ServerName example.com
DocumentRoot /var/www/laravel/public
<Directory /var/www/laravel/public>
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
Se Apache risponde ma il routing non funziona, controlla che mod_rewrite sia attivo e che il virtual host sia quello effettivamente caricato. Il sintomo classico è una 404 del server invece della route Laravel.
Nginx
Con Nginx la logica è simile, ma le rewrite vanno dichiarate esplicitamente. Il blocco base è questo:
server {
listen 80;
server_name example.com;
root /var/www/laravel/public;
index index.php index.html;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}
}
Qui il punto critico è il socket PHP-FPM. Se il percorso non coincide con la tua installazione, il server restituisce 502 o 500. Verifica il file di pool o lo stato del servizio prima di cercare problemi nell’applicazione.
Controlli finali dopo l’installazione
Dopo aver configurato progetto, database e web server, fai una verifica ordinata. Non limitarti a “la home si apre”: controlla che il backend scriva log, che le migrazioni siano complete e che il routing funzioni anche su URL diverse dalla root.
- Apri la home e verifica che il codice HTTP sia
200. - Controlla
storage/logs/laravel.logper eventuali errori residui. - Esegui
php artisan route:listper vedere se il framework carica correttamente le route. - Se usi cache e config cache, prova
php artisan config:cacheephp artisan route:cachesolo dopo che la base funziona.
php artisan route:list
php artisan config:clear
php artisan cache:clear
Le operazioni di cache sono utili, ma vanno fatte quando la configurazione è già stabile. Se le esegui troppo presto, rischi di congelare un errore di configurazione e rendere più opaca la diagnosi. Prima osserva, poi ottimizza.
Errori tipici e come leggerli senza perdere tempo
Un errore 500 non è una diagnosi. È solo il sintomo di qualcosa che si è rotto a livello applicativo o di runtime. I casi più frequenti in una nuova installazione sono chiari: APP_KEY mancante, permessi errati su storage/, database non raggiungibile, versione PHP incompatibile o configurazione del web server che punta alla directory sbagliata.
Per non andare a tentativi, segui questo ordine mentale: prima controlla il log Laravel, poi il log del web server, poi lo stato del database e infine la versione di PHP effettivamente usata dal processo web. La CLI e il runtime web non sempre coincidono, soprattutto su hosting condivisi o ambienti con più versioni di PHP installate.
Se vedi una pagina bianca senza dettagli, non assumere che il problema sia Laravel “in generale”. Spesso è una configurazione di APP_DEBUG=false in un ambiente dove non hai ancora accesso ai log corretti. In fase di installazione, tenere il debug attivo in locale è ragionevole; in produzione, va disattivato e sostituito da logging adeguato.
Quando conviene usare un pannello invece della shell
Se lavori su un hosting con pannello, alcune operazioni sono più sicure dal pannello stesso: scelta della versione PHP, attivazione estensioni, configurazione del dominio e document root. La shell resta indispensabile per Composer, Artisan e i controlli tecnici, ma per i passaggi che riducono gli errori di digitazione il pannello può essere più affidabile.
Il criterio pratico è semplice: usa il pannello per allineare l’ambiente, usa la CLI per verificare e automatizzare. Se il pannello mostra una versione PHP e la shell ne usa un’altra, hai trovato un problema da risolvere prima di andare avanti. Quel disallineamento è una delle cause più comuni di installazioni Laravel che sembrano corrette ma falliscono appena entrano in gioco Composer o le estensioni.
Sequenza minima consigliata per un’installazione pulita
Se vuoi un flusso sintetico ma solido, questa è la sequenza che evita la maggior parte dei problemi iniziali:
- Controlla versione PHP, Composer ed estensioni.
- Crea il progetto con
composer create-project. - Configura
.enve genera la chiave applicativa. - Imposta permessi corretti su
storage/ebootstrap/cache/. - Configura database e migrazioni.
- Pubblica il progetto con document root su
public/. - Verifica log, route e risposta HTTP.
Seguendo questi passaggi, l’installazione di Laravel con Composer resta lineare e soprattutto ripetibile. La parte importante non è solo “far partire” il framework, ma farlo partire in un ambiente coerente, con permessi corretti e configurazioni leggibili anche tra qualche mese, quando dovrai intervenire di nuovo.
Commenti (0)
Nessun commento ancora.
Segnala contenuto
Elimina commento
Eliminare definitivamente questo commento?
L'azione non si può annullare.