Se você já achou uma biblioteca PHP legal no GitHub e desistiu de usá-la porque lá está escrito “Instale através do Composer”, este post é para você.

Você não precisa mais fugir dessa mensagem!

O que é o Composer do PHP?

Composer é o gerenciador de dependências do PHP. Toda vez que o seu site ou aplicação precisar de um código ou biblioteca de terceiros, provavelmente é uma boa ideia inclui-la através do Composer. Se o seu código precisa de uma biblioteca, e esta biblioteca precisa de uma terceira, o próprio Composer gerenciará isso para você.

Embora seja possível usar código disponível em qualquer lugar (desde repositórios no GitHub até um zip em algum lugar qualquer), o lugar padrão para o Composer é o Packagist.

Exemplos de uso do Composer

Gateways de pagamento e APIs de redes sociais

É muito comum que gateways de pagamento e redes sociais disponibilizem bibliotecas em várias linguagens de programação para facilitar o uso de suas APIs. Se o seu gateway de pagamento tem um pacote em PHP, mas não tem um plugin em WordPress, o código do plugin não precisa reinventar a roda. É só usar a biblioteca PHP como base. O mesmo vale para a sua rede social favorita, ou qualquer outro serviço parecido.

Bibliotecas utilitárias

Outro uso comum do Composer é incluir bibliotecas utilitárias, como, por exemplo, um conjunto de funções matemáticas.

Como instalar o Composer

O único pré-requisito é ter o PHP disponível na linha de comando.

Linux e Mac

Para instalar no Linux e no Mac, basta seguir as instruções descritas na documentação oficial. Basicamente você vai baixar um arquivo em PHP que vai conferir algumas configurações da versão PHP disponível na sua linha de comando. Se tudo estiver bem, este arquivo irá baixar o composer.phar (phar vem de PHP Archive, que é tipo o .jar do Java). Para chamar o Composer, bastará chamar php composer.phar <comando>.

Se vocẽ quiser deixar o Composer disponível em todas as pastas, basta mover o arquivo composer.phar para uma pasta que faça parte do sua variável de ambiente $PATH e renomeá-lo para composer (sem extensão). Assim você não precisa mais colocar aquele php na frente. Para fazer isso tudo em um comando basta chamar:

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

Windows

Para usuários Windows, basta baixar e instalar o Composer através do arquivo executável neste link da documentação oficial. Ele vai fazer basicamente a mesma coisa que no Linux e no Mac, mas criando um arquivo .bat para você.

Como usar o Composer SEM instalá-lo

Pouca gente sabe (porque não leu a documentação), mas é possível usar o Composer sem fazer todos esses passos. Você pode simplesmente ir até a página de Download do Composer, baixar a última versão estável e renomear o arquivo para composer.phar. Assim, dentro da pasta onde você estiver trabalhando, o Composer ficará disponível chamando php composer.phar <comando>, ou ainda somente ./composer <comando> se você der ao arquivo permissão de execução com:

chmod +x composer

Note que é preciso usar o ./ antes do composer.

Exemplo prático: Consulta de CEP usando um pacote Composer

Vamos supor que estamos fazendo um plugin para o WordPress onde é preciso consultar um CEP. Este repositório parece fornecer esta funcionalidade, então não precisaremos escrever tanto código. Agora que nós já sabemos o que é e como instalar o Composer, aquele Install Via Composer já não nos assusta mais.

Criando o plugin

Para criar o plugin é bem fácil, vamos criar uma pasta chamada exemplo-composer dentro da pasta wp-content/plugins da nossa instalação do WordPress. Dentro dela, um arquivo chamado exemplo-composer.php somente com o mínimo cabeçalho possível:

<?php
/**
 * Plugin Name: Exemplo com Composer
 */

Feito isso, ative o seu plugin no Painel do WordPress.

Instalando o pacote via Composer

Só para mostrar como é fácil, não vamos instalar o Composer no computador. Vamos apenas baixá-lo direto para a pasta do nosso plugin. Lembre-se que, se você é um programador PHP, espera-se que você tenha o Composer instalado do jeito normal.

Depois de seguir os passos para usar o Composer sem instalá-lo, a pasta do nosso plugin estará assim:

O VS Code entende que, mesmo sem extensão, o arquivo é um pacote do PHP

Vamos então instalar o pacote com o comando

./composer require flyingluscas/viacep-php

Isso fará o Composer:

  • Criar um arquivo composer.json, onde ficarão os nomes dos pacotes que estamos usando;
  • Criar um arquivo composer.lock com as versões de todas as dependências encontradas pelo Composer;
  • Criar a pasta vendor, onde os pacotes ficarão de fato.

Dentro da pasta vendor, o Composer criará o arquivo autoload.php. Para usar toda a mágica do Composer e os pacotes que instalamos, basta que a gente faça um include ou um require deste arquivo.

Para ilustrar, aqui vai outra imagem, desta vez com toda a estrutura:

Usando o pacote no nosso plugin WordPress

Segundo a documentação do pacote, para obter os dados de um determinado CEP precisamos usar o método findByZipCode de uma instância da classe FlyingLuscas\ViaCEP\ViaCEP. Só para mostrar, vamos usar o filtro the_content para substituir o conteúdo de todos os posts com os dados de um determinado CEP. Se quiser, você pode criar uma página no seu site só com esta funcionalidade.

Não se esqueça de incluir o arquivo autoload.php da pasta vendor criada pelo Composer.

O código final do plugin fica assim:

<?php
/**
 * Plugin Name: Exemplo com Composer
 */

require 'vendor/autoload.php';

add_filter(
	'the_content',
	function( $content ) {
		$viacep = new \FlyingLuscas\ViaCEP\ViaCEP();

		$address = $viacep->findByZipCode( '01001000' )->toArray();

		return '<pre>' . print_r( $address, true ) . '</pre>';
	}
);

O post ficará desta forma:

As possibilidades são infinitas: pegar o CEP de um metafield, de um parâmetro $_GET, de um valor de formulário, etc.

Perguntas frequentes sobre o Composer

Meu servidor também precisa ter o Composer disponível?

Não. Basta subir a pasta vendor com todo o seu conteúdo. Na verdade, o Composer só faz alguma coisa quando você o executa pela linha de comando. Todos os arquivos e pastas que ele cria funcionam só através do PHP mesmo.

Como o Composer afeta o versionamento do meu projeto?

Depende de você e da estratégia que a sua equipe decidir adotar. Você pode versionar somente os arquivos composer.json e composer.lock e forçar a equipe a executar composer install para baixar os pacotes. Esta é uma estratégia normalmente considerada mais limpa, porque você não versiona o mesmo código duas vezes e mantém o seu repositório mais enxuto.

Por outro lado, nada impede que você versione tudo. Isso também vai funcionar.

Posso alterar o conteúdo da pasta vendor?

Isso não é recomendado, porque os pacotes podem ser sobrescritos se alguém executar um composer install. Os pacotes bem feitos são configuráveis por fora da pasta, seja estendendo uma classe seja chamando algum método específico para definir chaves de API, etc. Infelizmente, existem alguns casos onde os pacotes precisam ser alterados diretamente. Lembre-se sempre de se comunicar com a equipe sobre esta necessidade e documentar isso em algum lugar.

O Composer pode me ajudar a gerenciar plugins e temas de um site WordPress?

Fico feliz que você tenha perguntado isso! A resposta é SIM, e esse será o assunto de uma segunda parte deste conteúdo. Não esqueça de assinar o canal e a newsletter para não perder.