Instalar o Composer: guia completo para Windows, macOS e Linux

O Composer é o gestor de dependências do PHP. Instala as bibliotecas de que um projeto precisa, resolve as dependências dessas bibliotecas, fixa as versões e gera o autoload das classes. Este tutorial cobre a instalação nos três sistemas, os comandos do dia a dia e os erros que custam tempo. Verificado com o Composer 2.10.3 em PHP 8.5.10.

Instalar, verificando a assinatura

A receita que se vê por todo o lado é curl -sS https://getcomposer.org/installer | php. Executa diretamente um ficheiro descarregado, sem verificar nada. O procedimento oficial compara o hash SHA-384 do script com o publicado pelo projeto antes de o lançar.

#!/usr/bin/env bash
set -euo pipefail

ATTENDU=$(curl -sS https://composer.github.io/installer.sig)
curl -sS https://getcomposer.org/installer -o composer-setup.php
CALCULE=$(php -r "echo hash_file('sha384', 'composer-setup.php');")

if [ "$ATTENDU" != "$CALCULE" ]; then
    >&2 echo 'ERREUR : signature invalide, ne pas exécuter'
    rm composer-setup.php
    exit 1
fi

php composer-setup.php --quiet --install-dir=/usr/local/bin --filename=composer
rm composer-setup.php
composer --version

Composer version 2.10.3 2026-08-27 13:34:23

Os dois hashes coincidem, o instalador é autêntico. São trinta segundos de trabalho a mais contra a execução de um script arbitrário com os direitos da tua conta.

Windows

Descarregar e executar o Composer-Setup.exe. O instalador deteta o PHP, configura o PATH e atualiza-se sozinho.

macOS

O script acima funciona tal como está. Com o Homebrew:

brew install composer

Uma nota sobre os tutoriais mais antigos: pedem que acrescentes um alias ao ~/.bash_profile. Desde o macOS Catalina (2019), a shell por omissão é o zsh e esse ficheiro deixou de ser lido. O ficheiro a alterar é o ~/.zshrc. E o alias nem sequer é necessário se o composer.phar estiver instalado em /usr/local/bin/composer com direito de execução.

Linux

sudo apt-get update
sudo apt-get install -y php-cli unzip curl
# depois o script de verificação acima

O pacote composer dos repositórios Debian e Ubuntu está muitas vezes várias versões atrasado. Mais vale o instalador oficial.

Arrancar um projeto

mkdir mon-projet && cd mon-projet
composer init          # questionário interativo
composer require monolog/monolog

Este comando cria ou atualiza três coisas:

• composer.json, o que tu pedes. Vai para o versionamento.
• composer.lock, as versões exatas instaladas, até ao commit. Também vai para o versionamento: é o que garante que toda a equipa e a produção têm o mesmo código.
• vendor/, os ficheiros descarregados. Não se versiona, vai para o .gitignore.

/vendor/

install ou update: a distinção que conta

Lançar composer update num servidor de produção instala versões que ninguém testou. É a causa de um número notável de colocações em produção falhadas.

# Atualizar um só pacote
composer update monolog/monolog

# Atualizar um pacote e as suas dependências
composer update monolog/monolog --with-dependencies

# Ver o que mudaria, sem mudar nada
composer update --dry-run

As restrições de versão

{
    "require": {
        "php": ">=8.2",
        "monolog/monolog": "^3.5",
        "symfony/console": "~6.4.0",
        "vendor/paquet": "2.1.3"
    }
}

O ^ é a boa escolha por omissão: aceita as correções e os acrescentos, recusa as quebras de compatibilidade. Fixar uma versão exata parece prudente, mas bloqueia as correções de segurança.

Declarar a versão do PHP em require evita instalar um pacote que não vai correr no servidor. E se a máquina de desenvolvimento não tiver a mesma versão que a produção, o config.platform faz resolver as dependências para a versão alvo:

{
    "config": {
        "platform": {
            "php": "8.4.0"
        }
    }
}

O autoload

É a funcionalidade mais útil do Composer e a última que se descobre. A norma PSR-4 associa um prefixo de namespace a uma pasta.

{
    "autoload": {
        "psr-4": {
            "App\\": "src/",
            "App\\Tests\\": "tests/"
        },
        "files": [
            "src/fonctions.php"
        ]
    }
}

As barras invertidas duplicam-se num ficheiro JSON. É o erro mais frequente neste ficheiro, e fica silencioso até ao momento em que o Composer se recusa a ler o ficheiro:

"App\": "src/"     -> JSON INVALIDE (l'antislash échappe le guillemet)
"App\\": "src/"    -> correct

Com esta configuração, a classe App\Personnages\Guerrier é procurada em src/Personnages/Guerrier.php. O caminho decorre do nome, com barras invertidas no código e barras normais nas pastas.

<?php

declare(strict_types=1);

namespace App\Personnages;   // barras invertidas, nunca barras normais

final class Guerrier
{
    // …
}

<?php

require __DIR__ . '/vendor/autoload.php';

use App\Personnages\Guerrier;

$conan = new Guerrier();

Depois de qualquer alteração à secção autoload:

composer dump-autoload

Nada de comentários no composer.json

O JSON não tem comentários. Um // deixado no ficheiro torna-o ilegível:

In JsonFile.php line 398:
  "./composer.json" does not contain valid JSON
  Lexical error on line 5. Comments are not allowed.

O comando composer validate verifica o ficheiro antes de o problema aparecer noutro sítio.

Verificar as vulnerabilidades

O composer audit confronta os pacotes instalados com a base de avisos de segurança do ecossistema PHP.

composer audit

No security vulnerability advisories found.

É um comando a colocar na integração contínua, depois de composer install: sem pasta vendor/ responde apenas « No installed packages found ». Devolve um código de saída diferente de zero quando um aviso diz respeito ao projeto.

Detetar os pacotes abandonados

O Composer assinala os pacotes cujo autor declarou o abandono, no momento da instalação. O aviso passa muitas vezes despercebido no meio da saída:

Package facebook/php-sdk is abandoned, you should avoid using it.
Use facebook/graph-sdk instead.

Um pacote abandonado deixa de receber correções, incluindo as de segurança. Esta mensagem merece uma paragem em vez de a deixar passar.

Colocar em produção

composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist

E uma regra que vale a pena repetir: nunca lançar o Composer com sudo. Os ficheiros de vendor/ passariam a pertencer ao root, o servidor web deixaria de os conseguir ler, e a cache do Composer iria parar a /root/.composer. Se a instalação global pede sudo, é apenas para escrever em /usr/local/bin, uma vez.

Os comandos do dia a dia

# O que está instalado
composer show
composer show monolog/monolog        # detalhe de um pacote
composer show --tree                 # árvore das dependências

# O que poderia ser atualizado
composer outdated
composer outdated --direct           # só as tuas dependências diretas

# Porque é que este pacote está aqui?
composer why psr/log
composer why-not symfony/console 7.0 # o que bloqueia uma subida de versão

# Remover um pacote
composer remove monolog/monolog

# Reparar uma instalação duvidosa
rm -rf vendor composer.lock && composer install

Duas flags do Composer 1 ainda arrastam pelos tutoriais. O composer show -i devolve agora um aviso, já que os pacotes instalados são o que se mostra por omissão:

You are using the deprecated option "installed". Only installed packages are
shown by default now. The --all option can be used to show all packages.

E composer --V não existe, é -V ou --version:

The "--V" option does not exist.

Fontes de pacotes especiais

{
    "require": {
        "moi/mon-paquet": "dev-main"
    },
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/moi/mon-paquet"
        }
    ]
}

Para desenvolver um pacote em paralelo com o projeto que o usa, o repositório do tipo path cria uma ligação simbólica: as alterações ficam visíveis de imediato, sem reinstalação.

{
    "repositories": [
        {
            "type": "path",
            "url": "../mes-paquets/mon-paquet",
            "options": {
                "symlink": true
            }
        }
    ]
}

Os scripts

{
    "scripts": {
        "test": "phpunit",
        "analyse": "phpstan analyse src --level=8",
        "verifier": [
            "@analyse",
            "@test"
        ]
    }
}

composer verifier

Isto evita ter de decorar os caminhos para vendor/bin e dá a toda a equipa os mesmos comandos.

A reter

• Verificar o hash do instalador antes de o executar.
• Versionar o composer.lock, ignorar o vendor/.
• install em produção, update apenas em desenvolvimento.
• Duplicar as barras invertidas no composer.json, nenhum comentário.
• composer audit na integração contínua, nunca sudo.

O Composer é a porta de entrada da maior parte das bibliotecas: o PHPMailer para enviar um e-mail e o Ratchet para um servidor WebSocket instalam-se ambos com composer require.

Para continuar: as boas práticas do Composer, as bases da POO em PHP para tirar partido do autoload, e o hub Desenvolvimento web.