Installer Composer et PHP sur macOS avec Homebrew

Après une mise à jour de macOS, il arrive que Composer, PHP ou Homebrew se mettent à tousser. Et, comme souvent avec les outils de développement, le message d’erreur semble accuser PHP alors que le vrai problème vient parfois du chemin système, de Homebrew ou des permissions.

La bonne approche consiste à repartir proprement : vérifier Homebrew, installer PHP avec le bon préfixe, installer Composer, puis contrôler que le terminal utilise bien les binaires attendus.

Composer, PHP et macOS : ce qui a changé

L’ancien article parlait de macOS Monterey et de PHP 8.1. Le principe reste valable, mais l’environnement a évolué. Aujourd’hui, Homebrew utilise généralement deux emplacements différents selon l’architecture du Mac :

• /opt/homebrew sur les Mac Apple Silicon ;
• /usr/local sur les Mac Intel.

C’est une nuance importante. Si vous appliquez une correction de permissions sur /usr/local alors que votre Mac utilise /opt/homebrew, vous corrigez le mauvais répertoire. C’est un peu comme changer la serrure du garage alors que la porte d’entrée est grande ouverte.

Vérifier Homebrew avant d’installer PHP et Composer

Commencez par vérifier que Homebrew répond correctement :

brew --version
brew doctor

Ensuite, vérifiez le préfixe utilisé par Homebrew :

brew --prefix

Vous devriez obtenir l’un de ces chemins :

/opt/homebrew

ou :

/usr/local

Ce résultat détermine ensuite le chemin à ajouter dans votre configuration shell.

Installer PHP avec Homebrew

Pour installer PHP sous macOS avec Homebrew, utilisez simplement :

brew install php

Si PHP est déjà installé, mettez plutôt Homebrew et PHP à jour :

brew update
brew upgrade php

Vérifiez ensuite la version utilisée par votre terminal :

php -v
which php

Sur Apple Silicon, which php devrait souvent pointer vers un chemin du type :

/opt/homebrew/bin/php

Sur Mac Intel, il pointera plutôt vers :

/usr/local/bin/php

Si vous voyez encore /usr/bin/php, votre shell utilise probablement l’ancien PHP fourni par macOS, ou un binaire placé avant Homebrew dans le PATH.

Corriger le PATH pour utiliser le PHP de Homebrew

Sur macOS récent, le shell par défaut est généralement Zsh. Ouvrez donc le fichier ~/.zshrc :

nano ~/.zshrc

Sur Apple Silicon, ajoutez cette ligne si elle n’existe pas déjà :

eval "$(/opt/homebrew/bin/brew shellenv)"Code language: JavaScript (javascript)

Sur Mac Intel, utilisez plutôt :

eval "$(/usr/local/bin/brew shellenv)"Code language: JavaScript (javascript)

Rechargez ensuite la configuration du shell :

source ~/.zshrc

Puis contrôlez à nouveau :

which brew
which php
php -v

Installer Composer avec Homebrew

Une fois PHP en place, l’installation de Composer devient très simple :

brew install composer

Vérifiez ensuite l’installation :

composer --version
which composer

Composer doit répondre depuis un chemin Homebrew, par exemple :

/opt/homebrew/bin/composer

ou :

/usr/local/bin/composer

À ce stade, vous avez une installation cohérente : PHP et Composer viennent du même gestionnaire de paquets.

Installer Composer manuellement, sans Homebrew

Homebrew reste la solution la plus pratique sur une machine de développement. Toutefois, Composer peut aussi s’installer manuellement avec l’installateur officiel.

La méthode officielle consiste à télécharger l’installateur, vérifier sa signature, puis créer le fichier composer.phar. Comme la signature change à chaque version, évitez de copier une vieille commande trouvée dans un ancien tutoriel. Utilisez toujours la commande publiée sur la page officielle de Composer.

Ensuite, vous pouvez déplacer Composer dans un répertoire présent dans votre PATH :

sudo mv composer.phar /usr/local/bin/composer

Cette méthode fonctionne bien, mais elle demande un peu plus d’attention. Pour un poste de développement macOS, Homebrew reste plus confortable à maintenir.

Corriger l’erreur “Permission denied @ apply2files”

L’erreur suivante peut apparaître pendant une installation ou une mise à jour Homebrew :

Error: Permission denied @ apply2filesCode language: JavaScript (javascript)

Dans l’ancien article, la correction proposée était :

sudo chown -R $(whoami):admin /usr/local/* \
&& sudo chmod -R g+rwx /usr/local/*Code language: JavaScript (javascript)

Cette commande peut dépanner sur un vieux Mac Intel, mais elle est trop large pour être lancée machinalement. Avant de modifier les permissions, vérifiez d’abord le préfixe Homebrew :

brew --prefix

Ensuite, demandez à Homebrew ce qui cloche :

brew doctor

Si Homebrew signale un problème de propriétaire sur son propre préfixe, corrigez uniquement ce répertoire. Sur Apple Silicon :

sudo chown -R "$(whoami)":admin /opt/homebrewCode language: JavaScript (javascript)

Sur Mac Intel :

sudo chown -R "$(whoami)":admin /usr/local/Homebrew /usr/local/bin /usr/local/etc /usr/local/include /usr/local/lib /usr/local/opt /usr/local/sbin /usr/local/share /usr/local/varCode language: PHP (php)

Relancez ensuite :

brew doctor
brew update

Le but n’est pas de rendre tout /usr/local modifiable au hasard. Le but est de rendre à Homebrew la maîtrise de ses propres dossiers.

Mettre à jour Composer

Si Composer a été installé avec Homebrew, mettez-le à jour avec Homebrew :

brew update
brew upgrade composer

Si Composer a été installé manuellement, utilisez plutôt :

composer self-updateCode language: PHP (php)

Évitez de mélanger les deux méthodes. Sinon, vous risquez de mettre à jour un Composer pendant que votre terminal en utilise un autre. Oui, c’est pénible. Et oui, ça arrive plus souvent qu’on ne veut l’admettre.

Tester Composer dans un projet PHP

Pour vérifier que Composer fonctionne correctement, créez un dossier de test :

mkdir composer-test
cd composer-test
composer init

Vous pouvez aussi tester l’installation d’un paquet :

composer require psr/logCode language: JavaScript (javascript)

Si Composer crée bien les fichiers composer.json, composer.lock et le dossier vendor, l’installation est saine.

Si vous obtenez une erreur Permission denied dans votre projet, le problème ne vient pas forcément de Composer lui-même. J’ai détaillé ce cas dans l’article Composer : résoudre file_put_contents composer.json Permission denied.

Commandes utiles pour diagnostiquer PHP et Composer

Voici les commandes à garder sous la main :

brew --prefix
brew doctor
which php
php -v
php --ini
which composer
composer --version
composer diagnose

La commande php --ini est particulièrement utile pour savoir quel fichier php.ini votre PHP CLI utilise réellement. Cela permet de vérifier les extensions chargées, notamment zip, curl, openssl ou mbstring.

Et pour WordPress ?

Composer sert souvent à installer des dépendances PHP dans des projets WordPress modernes : outils de qualité de code, bibliothèques, plugins privés, mu-plugins ou automatisations.

Si vous travaillez sur des plugins ou thèmes WordPress, vous pouvez compléter cette installation avec un environnement de validation propre. J’ai détaillé ce workflow dans Valider votre projet VSCode avec PHP CodeSniffer et WordPress Coding Standards.

Et si vous travaillez côté serveur, l’article Installer PHP 8.5 sous Ubuntu Server couvre l’installation PHP côté Linux. Ce n’est pas le même contexte que macOS, mais cela permet de garder des versions cohérentes entre développement local et serveur.

Enfin, si vous gérez des sites WordPress en SSH, installer WP-CLI sans accès root ni sudo peut vous éviter pas mal de contorsions sur des hébergements mutualisés.

Résumé rapide

• Utilisez Homebrew pour installer PHP et Composer sur macOS.
• Vérifiez d’abord le préfixe Homebrew avec brew --prefix.
• Sur Apple Silicon, Homebrew utilise généralement /opt/homebrew.
• Sur Mac Intel, Homebrew utilise généralement /usr/local.
• Ne corrigez pas les permissions de /usr/local à l’aveugle.
• Vérifiez toujours which php et which composer.
• Évitez de mélanger installation Homebrew et installation manuelle de Composer.

FAQ

Composer installe-t-il PHP automatiquement ?

Avec Homebrew, l’installation de Composer peut entraîner l’installation de PHP comme dépendance si PHP n’est pas déjà disponible dans l’environnement Homebrew. Toutefois, il reste préférable d’installer ou de vérifier PHP explicitement avec brew install php.

Pourquoi mon Mac utilise-t-il encore /usr/bin/php ?

Votre PATH donne probablement la priorité aux binaires système avant ceux de Homebrew. Ajoutez le shellenv de Homebrew dans ~/.zshrc, puis rouvrez le terminal ou lancez source ~/.zshrc.

Faut-il utiliser sudo avec Composer ?

Non, pas pour installer les dépendances d’un projet. Si Composer demande sudo dans un dossier de projet, vous avez probablement un problème de propriétaire ou de permissions dans ce dossier.

Quelle version de PHP faut-il utiliser avec Composer ?

La version récente de Composer fonctionne avec PHP 7.2.5 ou supérieur. Pour un poste de développement actuel, utilisez plutôt une version PHP maintenue, idéalement la même version majeure que votre serveur de production.

Puis-je installer plusieurs versions de PHP sur macOS ?

Oui. Homebrew propose plusieurs formules versionnées, comme php@8.4 ou php@8.3. Ensuite, vous devez gérer le lien actif avec brew link ou utiliser un outil spécialisé si vous jonglez souvent entre plusieurs projets.

Sources

• Composer — Introduction et prérequis
• Homebrew Formulae — PHP
• Homebrew Documentation — Installation

Report a typo