Mamura
Mamura Programador web com mais de 15 anos de experiência.

Guia completo - Instalando o Composer

Guia completo - Instalando o Composer

Um passo a passo detalhado para Windos, macOs, Linux (Ubuntu/Debian, Fedora/RHEL, Arch, Alpine), WSL2 e Docker. Com dias de verificação, atualização, desinstalação e solução de problemas.

O que é o Composer e por que você deve usá-lo

O Composer é o gerenciador de dependências padrão do ecossistema PHP. Ele permite declarar as bibliotecas necessárias para o seu projeto em um arquivo composer.json e instalar versões compatíveis de forma reprodutível (com o composer.lock).

Principais benefícios:

  • Gerenciamento de pacotes via Packagist.org, com resolução semântica de versões.
  • Autoload PSR-4/PSR-0 automático (gerado pelo vendor\autioload.php).
  • Scripts do projeto (tarefas como composer test, composer cs, etc).
  • Ambientes consistentes (lockfile e faixas de versões).

Conceitos rápidos:

  • composer.json: declara dependências, autoload e scripts.
  • composer.lock: trava versões exatas instaladas (garante reprodutibilidade).
  • vendor/: onde as dependências são instaladas.

Requisitos gerais: PHP CLI instalado (verifique com php -v) e conexão com internet. É recomendado ter openssl habilitado no PHP por sergurança (instalador verificado por hash).

Verifique seu ambiente

1
2

php -v                   # versão do PHP CLI
php -m | grep -i openssl # confirma se a extensão OpenSSL está habilitada

Instalação no Windows

Opção 1 - Instalador Oficial (recomendado para maioria)

  1. Baixe o Composer-Setup.exe no site oficial (instalador gráfico).
  2. Durante o assistente:
    • Aponte o caminho do php.exe (XAMPP/WAMPP/Uniform Server/etc).
    • Deixe marcada a opção para adicionar o Composer ao PATH do usuário.
  3. Conclua e feche o instalador.
  4. Verifique no Prompt de Comando ou PowerShell: 
    1
2

    composer --version
where composer

Opção 2 - Gerenciadores de pacotes

  • winget (Windows 10/11): 
    1

    winget install --id Composer.Composer -e
  • Chocolatey: 
    1

    choco install composer -y
  • Scoop: 
    1

    scoop install composer

Se usar WSL2 (Ubuntu dentro do Windows), instale o Composer dentro do WSL seguindo as instruções de Linux (abaixo). Evite compartilhar a pasta vendor/ entre Windows e WSL.

Instalação no macOS

Opção 1 - Homebrew (simples)

1
2

brew install composer
composer --version

Opção 2 - Instalador oficial via PHP (universal)

  1. Baixe o instalador e a assinatura (hash) oficial e verifique a integridade: ```bash cd ~ php -r “copy(‘https://getcomposer.org/installer’, ‘composer-setup.php’);”

php -r “copy(‘https://composer.github.io/installer.sig’, ‘installer.sig’);”

php -r “if (hash_file(‘sha384’,’composer-setup.php’) === trim(file_get_contents(‘installer.sig’))) { echo ‘Installer verified’.PHP_EOL; } else { echo ‘Installer corrupt’.PHP_EOL; unlink(‘composer-setup.php’); exit(1); }”

1
2
3
4

2. Instale globalmente (Intel):
```bash
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Em Apple Silicon (M1, M2, M3) com Homebrew em /opt/homebrew:

1

sudo php composer-setup.php --install-dir=/opt/homebrew/bin --filename=composer
  1. Limpe os arquivos: ```bash php -r “unlink(‘composer-setup.php’); unlink(‘installer.sig’);”

composer –version

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

> Alternativa: MacPorts - `sudo port install composer`

# Instalação no Linux
> **Dica:** O método mais universal e atual é o instalador oficial (verificação por hash). Alguns repositórios de distro podem trazer versões defasadas.

## Método universal - instalador oficial
```bash
cd ~

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

php -r "copy('https://composer.github.io/installer.sig', 'installer.sig');"

php -r "if (hash_file('sha384','composer-setup.php') === trim(file_get_contents('installer.sig'))) { echo 'Installer verified'.PHP_EOL; } else { echo 'Installer corrupt'.PHP_EOL; unlink('composer-setup.php'); exit(1); }"

  

# Instalação global

sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

  

# Limpeza

php -r "unlink('composer-setup.php'); unlink('installer.sig');"

  

composer --version

which composer

Ubuntu/Debian

  • Dependências úteis: 
    1
2

    sudo apt update
sudo apt install -y php-cli inzip curl
  • Instalação rápida via APT (pode ser versão anterior): 
    1
2

    sudo apt install -y composer
composer --version

Fedora/RHEL/CentOS (DNF/YUM)

1
2
3

sudo dnf install -y composer php-cli php-json php-zip unzip curl

composer --version

Arch/Manjaro

1
2
3

sudo pacman -Syu composer

composer --version

Alpine Linux (containers/VMs minimalistas)

1
2
3
4
5

apk add --no-cache php81 php81-phar php81-openssl curl unzip

curl -sS https://getcomposer.org/installer | php81 -- --install-dir=/usr/local/bin --filename=composer

composer --version

Instalação por usuário (sem sudo)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

mkdir -p "$HOME/.local/bin"

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

php composer-setup.php --install-dir="$HOME/.local/bin" --filename=composer

rm composer-setup.php

  

# Adicione ao PATH (bash/zsh)

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # ou ~/.zshrc

source ~/.bashrc

  

composer --version

WSL2 (Linux no Windows)

Siga as instruções de Linux dentro do seu distro WSL (ex.: Ubuntu). Evite compartilhar a pasta vendor/ entre Windows e WSL para prevenir problemas de permissões e path.

Usando Composer via Docker (sem instalar localmente)

Se você usa Docker, pode chamar o Composer pelo container oficial macOS/Linux (bash/zsh):

1
2
3
4

docker run --rm -it \
	-v "$(pwd)":/app \
	-w /app composer:2 \
	composer --version

Windows PowerShell:

1

docker run --rm -it -v ${PWD}:/app -w /app composer:2 composer --version

Para instalar dependências do projeto:

1

docker run --rm -it -v "$(pwd)":/app -w /app composer:2 composer install --prefer-dist --no-dev

Conferindo a instalação

1
2

composer --version
composer diagnose

Se aparecer a versão e o diagnóstico passar, você está pronto para usar.

Primeiro uso: iniciando um projeto

Criar um composer.json interativo

1

composer init

Responda às perguntas e gere o arquivo. Depois, para instalar uma biblioteca:

1

composer require monolog/monolog:^3.0

Exemplo mínimo de composer.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
	"name": "acme/meu-projeto",
	"description": "Exemplo de projeto PHP usando Composer",
	"type": "project",
	"require": {
		"monolog/monolog": "^3.0"
	},
	"autoload": {
		"psr-4": {
			"App\\": "src/"
		}
	},
	"scripts": {
		"start": "php -S localhost:8000 -t public"
	}
}

Depois de instalar dependências:

1
2
3
4
5
6
7

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

use App\Hello;

$hello = new Hello();
echo $hello->say();

Atualização e desinstalação

Atualizar o Composer

1
2

composer self-update # Atualiza para a última estável
composer self-update --rollback # Volta à versão anterior

Se você instalou via gerenciador de pacotes (apt/dnf/pacman/brew), prefira atualizar por ele.

Desinstalar

  • Instalador oficial: remova o binário (ex.: /usr/local/bin/composer ou C:\\ProgramData\\ComposerSetup\\bin\\composer.exe).
  • Homebrew: brew uninstall composer
  • APT/DNF/Pacman: sudo apt remove composer / sudo dnf remove composer / sudo pacman -R composer
  • Windows: use Adicionar/Remover Programas, winget uninstall Composer.Composer, choco uninstall composer ou scoop uninstall composer.

Solução de problemas (FAQ)

1) **composer: command not found**

  • Verifique which composer (ou where composer no Windows).
  • Confirme se o diretório de instalação está no PATH (ex.: /usr/local/bin, /opt/homebrew/bin ou $HOME/.local/bin).

2) Problemas de SSL/**openssl**

  • Habilite a extensão openssl no php.ini do CLI e reinicie o terminal.

3) Limite de memória em instalações grandes

  • Use variável temporária (sessão atual): 
    1

    COMPOSER_MEMORY_LIMIT=-1 composer update
  • No Windows (PowerShell): 
    1

    $env:COMPOSER_MEMORY_LIMIT="-1"; composer update

4) Rede corporativa / Proxy

  • Configure proxy nas variáveis de ambiente: 
    1
2

    export HTTP_PROXY="http://usuario:senha@proxy:8080"
export HTTPS_PROXY="$HTTP_PROXY"
  • Tokens para GitHub/GitLab (evita limite de API): 
    1
2

    composer config -g github-oauth.github.com SEU_TOKEN
composer config -g gitlab-token.gitlab.com SEU_TOKEN

5) **Permission denied** ao instalar globalmente

  • Use sudo ou instale por usuário em $HOME/.local/bin (seção acima).

6) Repositórios da distro desatualizados

  • Prefira o instalador oficial para obter a versão mais recente.

7) Conflitos entre Windows e WSL2

  • Não compartilhe a pasta vendor/ nem misture caminhos entre ambientes distintos.

Comandos úteis do dia a dia

1
2
3
4
5
6
7
8
9

composer init # cria um composer.json interativamente
composer require vendor/pacote:^1.2 # adiciona dependência ao projeto
composer install # instala dependências do lock
composer update # atualiza conforme faixas do composer.json
composer outdated # lista pacotes desatualizados
composer dump-autoload # regenera autoload otimizado
composer run-script test # executa script "test" do composer.json
composer show vendor/pacote # informações do pacote
composer diagnose # verifica o ambiente

Boas práticas

  • Commite composer.json e composer.lock (para apps). Para bibliotecas, geralmente se commita só o composer.json.
  • Não commitar a pasta vendor/ (adicione ao .gitignore).
  • Use faixas de versão semânticas com cuidado (^, ~, >=, *).
  • Em produção, prefira composer install --no-dev --prefer-dist --optimize-autoloader.

Conclusão

Com o Composer instalado e verificado, você tem o que precisa para trabalhar com qualquer framework moderno (Laravel, Symfony, etc.) e organizar dependências com segurança e reprodutibilidade. Se quiser, posso adaptar este guia para a sua stack (ex.: Laravel + Sail/Docker, WSL2, múltiplas versões de PHP) ou gerar uma versão em PDF.

Rating:

comments powered by Disqus