Installer Laravel sur un hébergement avec cPanel (Laravel 13 et 12)

Vous pouvez installer Laravel sur un hébergement avec cPanel en utilisant Composer et l'accès SSH. Dans ce guide, nous allons créer un nouveau projet, préparer sa base de données, configurer le domaine pour qu'il ne publie que le dossier public et préparer les éléments dont une application en production a généralement besoin : scheduler, files d'attente, sessions, cache et, si nécessaire, Horizon et WebSockets.

Si vous avez déjà une application dans un dépôt, vous n'avez pas besoin d'en créer une autre : connectez le dépôt à Deploy+ et suivez ce guide à partir de la section sur la base de données.

1. Choisissez la version de PHP et vérifiez celle du terminal

Laravel 13 nécessite PHP 8.3 ou supérieur, et Laravel 12, PHP 8.2 ou supérieur, toujours dans la limite de ce qu'acceptent vos dépendances. La version du site se choisit dans le sélecteur PHP ; pour un site publié avec Deploy+, elle se fixe dans le .htaccess de votre dépôt, comme nous l'expliquons dans version de PHP avec Deploy+.

Ouvrez SSH ou le terminal de cPanel et vérifiez quelle version exécutent les commandes :

php -v
composer --version

Le php du terminal n'est pas toujours la version de votre site : nous avons vu des comptes où PHP 8.1 répondait alors que le sélecteur était sur 8.4. S'ils ne correspondent pas, appelez le binaire de votre version par son chemin complet, par exemple /opt/alt/php84/usr/bin/php artisan migrate, et exécutez Composer avec lui :

/opt/alt/php84/usr/bin/php "$(command -v composer)" install

Dans la suite du guide, nous écrivons php pour abréger : remplacez-le par le chemin complet si votre terminal donne une autre version. Dans le cron et dans les processus persistants, utilisez toujours le chemin complet.

Les prérequis de Laravel incluent Ctype, cURL, DOM, Fileinfo, Filter, Hash, Mbstring, OpenSSL, PCRE, PDO, Session, Tokenizer et XML ; la base de données choisie nécessite en plus son pilote PHP. Les extensions s'activent par version : si Composer indique ext-fileinfo is missing, activez-la dans la version qui exécute la commande. N'ignorez pas les vérifications avec --ignore-platform-reqs : installer des dépendances incompatibles ne fera pas fonctionner l'application.

Les valeurs de chaque version, comme memory_limit, max_execution_time, upload_max_filesize ou max_input_vars, s'ajustent aussi selon les besoins de votre application : depuis l'onglet Limites de la fiche du site dans l'espace client ou depuis Options dans le sélecteur de cPanel, comme l'explique PHP, choisir la version, les modules et la configuration. max_execution_time ne limite que les requêtes web : Artisan, le scheduler et les workers n'ont pas cette durée maximale.

2. Créez le projet hors du répertoire public

Depuis la racine de votre compte, créez un nouveau dossier qui n'existe pas encore :

cd ~
composer create-project laravel/laravel mi-proyecto "^13.0"
cd mi-proyecto
php artisan --version
composer check-platform-reqs

La vérification d'Artisan doit identifier Laravel 13 ; celle de Composer, confirmer les prérequis de l'environnement. N'exécutez pas create-project sur un site existant.

Si l'application ou une intégration nécessite Laravel 12, utilisez un autre nouveau dossier avec composer create-project laravel/laravel mi-proyecto-12 "^12.0". Son calendrier officiel maintient les correctifs de sécurité jusqu'au 24 février 2027 ; consultez la politique de support de Laravel au moment de choisir la version. Pour un projet existant, utilisez son composer.lock avec composer install ; ne le remplacez pas par une nouvelle installation et ne changez pas de version majeure sans examiner la mise à jour.

Si vous préférez un starter kit (React, Vue, Svelte ou Livewire), installez l'installeur officiel avec composer global require laravel/installer, ajoutez au PATH le chemin que renvoie composer global config bin-dir --absolute et utilisez laravel new otro-proyecto dans un nouveau dossier. Consultez laravel new --help avant d'automatiser des options.

3. Configurez la base de données

Une nouvelle installation peut démarrer avec SQLite si PHP dispose de son pilote. Pour utiliser MySQL, créez la base et son utilisateur depuis l'assistant de bases de données de cPanel. Si vous déployez avec Deploy+, il peut créer la base et écrire la connexion dans le .env lors de la connexion du dépôt.

Modifiez .env dans le projet avec les données réelles de cette base :

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=miusuario_proyecto
DB_USERNAME=miusuario_app
DB_PASSWORD="sustituye_por_la_clave_de_la_base"

Utilisez les noms complets qu'affiche cPanel, préfixe compris. Ne publiez pas .env et ne l'envoyez pas dans le dépôt. Dans le nouveau projet, exécutez :

php artisan config:clear
php artisan migrate

Si vous déployez une application avec des données existantes, examinez les migrations et conservez une sauvegarde avant de les appliquer. N'utilisez pas migrate:fresh : cette commande supprime les tables.

4. Publiez uniquement le dossier public

Le domaine doit servir /home/tu_usuario/mi-proyecto/public, et non /home/tu_usuario/mi-proyecto. Ainsi, les fichiers de configuration et le code privé restent hors de la racine web.

Pour un domaine supplémentaire ou un sous-domaine, vérifiez son répertoire depuis cPanel > Domaines > Gérer et, si la configuration le permet, sélectionnez le dossier public du projet. Ne déplacez pas index.php à la racine pour éviter cette étape.

Pour le domaine principal, cPanel utilise normalement public_html. Si vous devez remplacer ce répertoire par un lien vers le public de Laravel, planifiez d'abord ce qu'il contient, sa sauvegarde et le retour arrière ; ne renommez pas et ne supprimez pas public_html sans vérifier s'il héberge déjà un site ou d'autres domaines. Avec Deploy+, le profil Laravel publie le dossier public du dépôt dans le dossier de votre choix, qui doit être vide lors du premier déploiement.

5. Préparez et vérifiez l'application

Dans .env, configurez l'URL réelle et désactivez le débogage public :

APP_ENV=production
APP_DEBUG=false
APP_URL=https://votredomaine.com

L'installation doit avoir une clé APP_KEY. Dans un nouveau projet sans clé, générez-en une avec php artisan key:generate. Ne la régénérez pas dans une application existante : vous pourriez rendre inaccessibles des données chiffrées.

Si votre projet utilise Vite, compilez ses ressources avec une version de Node.js compatible avec son package.json : npm install et npm run build pour une nouvelle installation ; npm ci et npm run build pour les déploiements avec package-lock.json. Node.js se trouve dans le Gestionnaire de paquets et sert à compiler ; consultez Node.js pour compiler les assets.

Vérifiez que storage et bootstrap/cache sont accessibles en écriture par l'application, sans appliquer de droits 777 de façon générale, et exécutez php artisan optimize.

Ouvrez le domaine en HTTPS et vérifiez la page d'accueil, les routes internes et les fonctions qui interrogent la base de données. Vérifiez aussi que /.env ne renvoie pas le fichier. Si une erreur 500 apparaît, consultez storage/logs/laravel.log et les journaux de l'hébergement ; n'activez pas le débogage public pour afficher l'erreur à tous les visiteurs.

6. Programmez le scheduler

Si vous publiez le projet avec Deploy+, l'assistant s'en charge pour vous : laissez coché Programmer le scheduler de Laravel et la tâche est ajoutée à la fin du premier déploiement, comme nous l'expliquons dans Deploy+. Vérifiez-la tout de même avec php artisan schedule:list.

Sinon, dans cPanel > Tâches Cron, ajoutez une tâche qui s'exécute chaque minute avec le PHP de votre application :

* * * * * /opt/alt/php84/usr/bin/php /home/tu_usuario/mi-proyecto/artisan schedule:run > /dev/null 2>&1

Remplacez php84 par votre version et le chemin par celui de votre projet ; avec Deploy+, c'est /home/tu_usuario/deploy/nombre-repo/current/artisan. N'utilisez pas /usr/local/bin/php ni php tout court : il peut s'agir d'une autre version de PHP, avec d'autres extensions, et le scheduler lance les tâches planifiées avec le même PHP que celui avec lequel il démarre.

Avant de la laisser en place, exécutez cette même commande à la main, sans ignorer la sortie, et vérifiez php artisan schedule:list. Vous trouverez plus de détails sur le cron dans tâches cron dans cPanel.

7. Files d'attente

Depuis Laravel 11, un nouveau projet enregistre les jobs dans la base de données (QUEUE_CONNECTION=database). Dans un projet antérieur, créez d'abord la table avec php artisan queue:table et lancez la migration. Ce qui change selon votre offre, c'est qui les traite.

Avec des processus persistants (Avanza, Max et Elastic)

Créez un Worker de files d'attente dans Outils > Processus, avec le dossier de l'application et sa version de PHP. Il reste actif, traite chaque job dès son arrivée et redémarre tout seul s'il s'arrête. Lorsque vous publiez une version avec Deploy+, il redémarre automatiquement pour prendre en compte le nouveau code. Tous les détails se trouvent dans processus persistants.

Sans processus persistants

Dans n'importe quelle offre, le scheduler peut lancer chaque minute un worker qui traite ce qui est en attente puis s'arrête. Dans routes/console.php :

use Illuminate\Support\Facades\Schedule;

Schedule::command('queue:work --stop-when-empty --tries=3 --max-time=300')
    ->everyMinute()
    ->withoutOverlapping(10)
    ->runInBackground();

withoutOverlapping(10) évite que deux workers se chevauchent et libère le verrou au bout de 10 minutes si l'un s'interrompt en cours de route ; runInBackground() permet aux autres tâches planifiées de s'exécuter à l'heure prévue. Un job peut attendre jusqu'à une minute avant d'être traité.

Si vous préférez ne pas dépendre du scheduler, une tâche cron avec flock fait la même chose sans chevauchement :

* * * * * cd /home/tu_usuario/mi-proyecto && /usr/bin/flock -n /home/tu_usuario/.cola-mi-proyecto.lock /opt/alt/php84/usr/bin/php artisan queue:work --stop-when-empty --max-time=300 > /dev/null 2>&1

Dans les deux cas, examinez les jobs échoués avec php artisan queue:failed.

8. Sessions, cache et Redis

Où stocker chaque élément :

• Sessions : dans la base de données (SESSION_DRIVER=database) dans n'importe quelle offre ; à partir d'Avanza, aussi dans le Redis persistant (redis).
• Files d'attente : dans la base de données (QUEUE_CONNECTION=database) dans n'importe quelle offre ; à partir d'Avanza, aussi dans le Redis persistant (redis).
• Cache : dans la base de données (CACHE_STORE=database) ou dans Redis Cache, dans n'importe quelle offre.
• Horizon : uniquement avec le Redis persistant, à partir d'Avanza.

Les deux Redis ne servent pas à la même chose :

• Redis Cache, dans toutes les offres, est uniquement un cache : il redémarre vide et supprime des clés lorsqu'il est plein. Utilisez-le pour CACHE_STORE=redis et jamais pour les sessions ni les files d'attente. Configuration dans Redis comme cache d'objets.
• Redis persistant, à partir d'Avanza, enregistre ses données sur disque et ne les supprime pas : c'est l'endroit pour les files d'attente, les sessions et Horizon. Il s'active dans le Gestionnaire de paquets et se connecte via un socket de votre compte. Configuration dans Redis persistant.

Vous pouvez utiliser les deux en même temps : le cache dans Redis Cache, et les files d'attente et les sessions dans le Redis persistant. Les sessions en base de données sont l'option par défaut depuis Laravel 11 et conviennent à toutes les offres ; dans un projet antérieur, créez leur table avec php artisan session:table.

9. Horizon

Horizon nécessite des files d'attente dans Redis et un processus actif ; il fonctionne donc à partir de l'offre Avanza : activez le Redis persistant, définissez QUEUE_CONNECTION=redis, installez laravel/horizon et créez un processus persistant de type Horizon. Ajustez maxProcesses dans config/horizon.php aux ressources de votre offre. Avec Deploy+, Horizon redémarre automatiquement après l'activation de chaque version ; si vous publiez autrement, exécutez php artisan horizon:terminate une fois le nouveau code en place. Les étapes se trouvent dans Redis persistant pour les files d'attente, les sessions et Horizon.

Horizon sur Redis Cache n'est pas sûr : si ce cache se vide ou se remplit, des jobs sont perdus.

10. Broadcasting et WebSockets

Nous ne proposons pas Reverb sur l'hébergement : c'est un serveur qui écoute sur son propre port, et nous ne prenons pas en charge ce type de programme, comme nous l'expliquons dans processus persistants. Pour les notifications et les événements en temps réel, connectez votre application à un service compatible avec le protocole Pusher, comme Pusher Channels ou Ably, que Laravel prend en charge nativement. Votre application effectue uniquement des requêtes HTTPS sortantes et les navigateurs se connectent au service. Comparatif et configuration dans WebSockets dans Laravel.

Ce qui ne convient pas à l'hébergement

• Octane : ici, PHP est servi par LiteSpeed, et Octane a besoin de son propre serveur d'application en frontal (Swoole, RoadRunner ou FrankenPHP).
• Reverb ou un autre serveur WebSockets à vous : utilisez un service compatible Pusher.
• Node.js en tant que serveur : Node sert à compiler les assets. Le SSR d'Inertia nécessite un serveur Node actif ; sans lui, Inertia effectue le rendu dans le navigateur comme d'habitude.
• Les services système ou l'accès root. Si votre projet en a besoin, expliquez-nous votre cas avant de commander.

Livewire, Inertia, Filament, Sanctum, Socialite ou Scout fonctionnent sans rien de particulier.

Publier les changements suivants avec Deploy+

Une fois le projet dans Git, Deploy+ publie chaque version dans son propre dossier, avec des fichiers partagés et des versions auxquelles revenir. Un script de déploiement pour Laravel :

composer install --no-dev --optimize-autoloader --no-interaction
php artisan migrate --force
php artisan optimize

Si vous compilez des assets, ajoutez les lignes npm qu'indique le guide de Deploy+. Pas besoin de queue:restart ni de horizon:terminate : après l'activation de chaque version, et aussi lors du retour à une version antérieure, Deploy+ redémarre les processus persistants de l'application. Un retour arrière du code n'annule pas automatiquement les modifications de la base de données : concevez les migrations en tenant compte de cette différence.

Le script recommandé, les processus pris en charge par l'hébergement et la comparaison avec un VPS sont résumés dans hébergement pour Laravel avec Deploy+.

Références : installation de Laravel, files d'attente et recommandations de déploiement.