Dicas de uso do compositor

Instalação

O Composer é um arquivo executável .phar que você pode baixar e instalar da seguinte forma.

Windows

Use o instalador oficial Composer-Setup.exe.

Linux, macOS

Tudo que você precisa são 4 comandos, que você pode copiar a partir desta página.

Além disso, ao copiar para a pasta que está no sistema PATH, o Composer torna-se acessível globalmente:

$ mv ./composer.phar ~/bin/composer # or /usr/local/bin/composer

Uso em Projeto

Para começar a usar o Composer em seu projeto, tudo o que você precisa é um arquivo composer.json. Este arquivo descreve as dependências de seu projeto e pode conter também outros metadados. O mais simples composer.json pode se parecer com este:

{
	"require": {
		"nette/database": "^3.0"
	}
}

Estamos dizendo aqui que nossa aplicação (ou biblioteca) depende do pacote nette/database (o nome do pacote consiste de um nome de fornecedor e o nome do projeto) e quer a versão que corresponda à restrição da versão ^3.0.

Portanto, quando temos o arquivo composer.json na raiz do projeto e executamos:

composer update

O Composer irá baixar o banco de dados Nette no diretório vendor. Ele também cria um arquivo composer.lock, que contém informações sobre exatamente quais versões de biblioteca ele instalou.

O compositor gera um arquivo vendor/autoload.php. Você pode simplesmente incluir este arquivo e começar a usar as classes que estas bibliotecas fornecem sem nenhum trabalho extra:

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

$db = new Nette\Database\Connection('sqlite::memory:');

Pacotes de atualização para as versões mais recentes

Para atualizar todos os pacotes usados para a versão mais recente de acordo com as restrições de versão definidas em composer.json use o comando composer update. Por exemplo, para a dependência "nette/database": "^3.0" será instalada a versão mais recente 3.x.x, mas não a versão 4.

Para atualizar as restrições da versão no arquivo composer.json para, por exemplo, "nette/database": "^4.1", para permitir a instalação da versão mais recente, use o comando composer require nette/database.

Para atualizar todos os pacotes Nette usados, seria necessário listá-los todos na linha de comando, por exemplo

composer require nette/application nette/forms latte/latte tracy/tracy ...

O que é impraticável. Portanto, use um simples roteiro Composer Frontline que o fará por você:

php composer-frontline.php

Criando um novo projeto

O novo projeto Nette pode ser criado através da execução de um simples comando:

composer create-project nette/web-project name-of-the-project

Em vez disso, o name-of-the-project você deve fornecer o nome do diretório para seu projeto e executar o comando. O compositor buscará o repositório nette/web-project no GitHub, que já contém o arquivo composer.json, e logo em seguida instalará o próprio Nette Framework. A única coisa que resta é verificar as permissões de escrita nos diretórios temp/ e log/ e você está pronto para ir.

Se você sabe em que versão do PHP o projeto será hospedado, não deixe de configurá-lo.

Versão PHP

O Composer sempre instala as versões dos pacotes que são compatíveis com a versão do PHP que você está usando atualmente (ou melhor, a versão do PHP usada na linha de comando quando você executa o Composer). Que provavelmente não é a mesma versão que seu web host está usando. É por isso que é muito importante adicionar informações sobre a versão do PHP em sua hospedagem ao seu arquivo composer.json. Depois disso, somente versões de pacotes compatíveis com o host serão instaladas.

Por exemplo, para configurar o projeto para rodar no PHP 8.2.3, use o comando:

composer config platform.php 8.2.3

Esta é a forma como a versão é escrita no arquivo composer.json:

{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}

No entanto, o número da versão PHP também está listado em outra parte do arquivo, na seção require. Enquanto o primeiro número especifica a versão para a qual os pacotes serão instalados, o segundo número diz para qual versão o aplicativo em si é escrito. (É claro, não faz sentido que estas versões sejam diferentes, portanto, a entrada dupla é uma redundância). Você define esta versão com o comando:

composer require php 8.2.3 --no-update

Ou diretamente no arquivo `composer.json':

{
	"require": {
		"php": "8.2.3"
	}
}

Ignorando a versão do PHP

Normalmente, os pacotes especificam a versão mais baixa do PHP com a qual são compatíveis e a versão mais alta com a qual foram testados. Se você planeja usar uma versão ainda mais recente do PHP, talvez para fins de teste, o Composer se recusará a instalar esse pacote. A solução é usar a opção --ignore-platform-req=php+, que faz com que o Composer ignore os limites superiores da versão do PHP necessária.

Falsos relatórios

Ao atualizar pacotes ou mudar números de versão, conflitos acontecem. Um pacote tem requisitos que entram em conflito com outro e assim por diante. No entanto, o Composer ocasionalmente imprime uma mensagem falsa. Ele relata um conflito que realmente não existe. Neste caso, ele ajuda a apagar o arquivo composer.lock e tenta novamente.

Se a mensagem de erro persistir, então o objetivo é sério e você precisa ler a partir dela o que modificar e como.

Packagist.org – Repositório Global

Packagist é o principal repositório de pacotes, no qual o Composer tenta pesquisar pacotes, se não for dito o contrário. Você também pode publicar seus próprios pacotes aqui.

E se não quisermos o Repositório Central

Se temos aplicações internas ou bibliotecas em nossa empresa, que não podem ser hospedadas publicamente na Packagist, podemos criar nossos próprios repositórios para esse projeto.

Mais sobre os repositórios na documentação oficial.

Carregamento automático

Uma característica chave do Composer é que ele fornece auto-carga para todas as classes que ele instala, que você começa por incluir um arquivo vendor/autoload.php.

Entretanto, também é possível utilizar o Composer para carregar outras classes fora da pasta vendor. A primeira opção é deixar o Composer escanear as pastas e subpastas definidas, encontrar todas as classes e incluí-las no autoloader. Para fazer isso, configure autoload > classmap em composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  includes the src/ folder and its subfolders
		]
	}
}

Em seguida, é necessário executar o comando composer dumpautoload a cada mudança e deixar as mesas de auto-carga se regenerar. Isto é extremamente inconveniente, e é muito melhor confiar esta tarefa ao RobotLoader, que executa a mesma atividade automaticamente em segundo plano e muito mais rápido.

A segunda opção é seguir o PSR-4. Simplesmente dizendo, é um sistema onde os namespaces e nomes de classes correspondem à estrutura do diretório e nomes de arquivos, ou seja, App\Core\RouterFactory está localizado no arquivo /path/to/App/Core/RouterFactory.php. Exemplo de configuração:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # the App\ namespace is in the app/ directory
		}
	}
}

Consulte a documentação do Composer para saber exatamente como configurar este comportamento.

Teste de Novas Versões

Você quer testar uma nova versão de desenvolvimento de um pacote. Como fazer isso? Primeiro, adicione este par de opções ao arquivo composer.json, o que lhe permitirá instalar versões de desenvolvimento de pacotes, mas só o fará se não houver uma combinação estável de versões que atenda aos requisitos:

{
	"minimum-stability": "dev",
	"prefer-stable": true,
}

Também recomendamos apagar o arquivo composer.lock, porque às vezes o Composer incompreensivelmente se recusa a instalar e isso resolverá o problema.

Digamos que o pacote é nette/utils e a nova versão é a 4.0. Você o instala com o comando:

composer require nette/utils:4.0.x-dev

Ou você pode instalar uma versão específica, por exemplo, 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Se outro pacote depender da biblioteca e estiver bloqueado para uma versão mais antiga (por exemplo ^3.1), é ideal atualizar o pacote para trabalhar com a nova versão. Entretanto, se você quiser apenas contornar a limitação e forçar o Composer a instalar a versão em desenvolvimento e fingir que é uma versão mais antiga (por exemplo, 3.1.6), você pode usar a palavra-chave as:

composer require nette/utils "4.0.x-dev as 3.1.6"

Comandos de Chamada

Você pode chamar seus próprios comandos e scripts personalizados através do Composer, como se fossem comandos nativos do Composer. Os scripts localizados na pasta vendor/bin não precisam especificar esta pasta.

Como exemplo, definimos um roteiro no arquivo composer.json que utiliza o Nette Tester para realizar testes:

{
	"scripts": {
		"tester": "tester tests -s"
	}
}

Em seguida, realizamos os testes com composer tester. Podemos chamar o comando mesmo que não estejamos na pasta raiz do projeto, mas em um subdiretório.

Enviar agradecimentos

Mostraremos a vocês um truque que fará felizes os autores de código aberto. Você pode facilmente dar uma estrela no GitHub para as bibliotecas que seu projeto utiliza. Basta instalar a biblioteca symfony/thanks:

composer global require symfony/thanks

E depois correr:

composer thanks

Experimente!

Configuração

O Composer está estreitamente integrado com a ferramenta de controle de versão Git. Se você não usar Git, é necessário dizer isso ao Composer:

composer -g config preferred-install dist