Como Criar seu Próprio Pacote Composer

Com a reutilização de código, surge o problema do gerenciamento de dependências, historicamente um processo bastante manual e propenso a erros. Felizmente, nos últimos anos, a maioria das linguagens de programação resolveu esse problema com a introdução de várias ferramentas para o gerenciamento de dependências. No ecossistema PHP, o Composer tornou-se o padrão graças à sua facilidade de uso, flexibilidade e adoção ampla.

Embora o Composer tenha sido criado para o gerenciamento de dependências, você também pode usá-lo para tarefas como:

• Carregamento automático: Carregar automaticamente classes e funções de bibliotecas externas para torná-las prontamente acessíveis a partir do seu código e simplificar o processo de integração de código externo ao seu projeto.
• Geração de código: Gerar código padrão para o seu projeto, como arquivos de configuração ou outros snippets de código usados com frequência, para acelerar o processo de desenvolvimento e garantir a consistência.
• Criação de scripts: Um sistema de script incorporado pode automatizar tarefas comuns, como a execução de testes ou a geração de documentação a partir da sua base de código. Isso pode ajudar a otimizar seu fluxo de trabalho de desenvolvimento e reduzir o trabalho manual.

Este tutorial passo a passo orienta você a criar seu próprio pacote do Composer e publicá-lo no Packagist, um repositório de pacotes PHP que os desenvolvedores de todo o mundo podem usar em seus próprios projetos.

Como o Composer funciona?

Primeiro, vamos nos certificar de entender o Composer. Em termos simples, o Composer funciona usando um arquivo composer.json que contém as definições das dependências em seu projeto PHP. Ele procura esses pacotes em um repositório centralizado e, em seguida, baixa e instala automaticamente essas dependências usando o repositório de pacotes.

Supondo que você já tenha o Composer instalado em seu ambiente de trabalho PHP, veja como é o processo de download e instalação de dependências:

1. Defina as dependências necessárias para o seu projeto em um arquivo composer.json no diretório raiz do seu projeto. Esse arquivo inclui informações sobre as bibliotecas necessárias e suas versões, e quaisquer outras definições de configuração ou dependências para essas bibliotecas.
2. Você pode resolver as dependências no Composer com comandos como install para instalar as dependências necessárias; update para atualizar as dependências existentes; e require para adicionar novas dependências ao arquivo composer.json. Quando você executa um comando, o Composer lê o arquivo composer.json para determinar as dependências necessárias, verifica o repositório de pacotes em busca da versão mais recente de cada dependência apropriada para o seu ambiente PHP e, em seguida, verifica se há conflitos ou restrições de versão.
3. O Composer baixa e instala as dependências necessárias, incluindo as bibliotecas, no diretório vendor do seu projeto. O Composer cria um arquivo composer.lock que registra as versões exatas das dependências instaladas.
4. O Composer configura um carregador automático que carrega classes e funções das dependências instaladas automaticamente. Isso facilita o uso das bibliotecas instaladas em seu projeto sem a necessidade de incluir manualmente cada arquivo.

Em resumo, o Composer simplifica o gerenciamento de dependências em projetos PHP, facilitando a instalação, a atualização e o uso de bibliotecas e frameworks externos.

Criando e publicando um pacote do Composer

Este tutorial mostra como criar uma biblioteca PHP simples chamada tempconv, que converte a temperatura em Celsius para Fahrenheit e vice-versa, e termina publicando-a como um pacote do Composer.

Pré-requisitos

Você precisará de algumas coisas antes de começar:

• No momento em que este artigo foi escrito, a versão mais recente do Composer é a v2.6.6, mas essas instruções devem funcionar com qualquer variante da v2.
• Uma conta do GitHub para criar um repositório para hospedar seu código.
• Uma conta do Packagist para publicar sua biblioteca.

Crie um repositório de projeto

Crie seu próprio repositório do GitHub para este tutorial, aonde você poderá enviar o código e os arquivos finalizados da biblioteca.

Este tutorial usa o nome de projeto tempconv. No campo Description (Descrição), forneça breves detalhes sobre o aplicativo. Marque a caixa para adicionar um arquivo README, escolha o template Composer na opção Add .gitignore e selecione uma licença de sua escolha — este tutorial usa a licença MIT. Por fim, clique em Create repository (Criar repositório).

Clone o repositório

Clone o repositório que você acabou de criar em seu computador local. Não se esqueça de substituir a URL pela sua própria, tanto aqui quanto em todo este tutorial:

$ git clone https://github.com/rexfordnyrk/tempconv.git

Isso cria um diretório chamado tempconv em seu diretório de trabalho atual. Neste momento, ele contém apenas os arquivos README.md, LICENSE e .gitignore, mas você também criará os arquivos do pacote aqui.

Criando sua biblioteca PHP

No diretório do seu projeto, adicione um arquivo chamado TemperatureConverter.php com o seguinte código:

<?php

namespace Rexfordnyrk\Tempconv;

class TemperatureConverter
{
    //Caller must provide the temperature value and the unit either C Celsius or F Fahrenheit
    public function convert($temperature, $unit)
    {
        //Checking whether the unit we're working with is Celsius or Fahrenheit
        if ($unit === 'C') {
            $fahrenheit = ($temperature * 9 / 5) + 32;
            return $fahrenheit;
        } elseif ($unit === 'F') {
            $celsius = ($temperature - 32) * 5 / 9;
            return $celsius;
        } else {
            //Throwing error if the unit provided is neither C nor F
            throw new \InvalidArgumentException('Invalid unit, only C (Celsius) or F (Fahrenheit) are allowed');
        }
    }
}

Essa classe tem um único método chamado convert que recebe a temperatura e a unidade como argumentos e retorna a temperatura convertida. E lança uma exceção se a unidade for inválida.

Por enquanto, isso é o suficiente. Em um cenário do mundo real, você provavelmente escreveria testes de unidade para garantir que seu código funcione conforme o esperado após modificações ou atualizações.

Criando o pacote Composer

Com o código da biblioteca pronto, é hora de transformá-lo em um pacote Composer. Você gerará um arquivo composer.json para o seu pacote usando um assistente passo a passo. Abordaremos algumas práticas recomendadas para organizar seu código como um pacote antes de enviá-lo para o seu repositório.

Gerando um arquivo de pacote composer.json

Embora você possa escrever manualmente o conteúdo de um arquivo composer.json na raiz do diretório do seu projeto, é melhor gerá-lo usando o seguinte comando do Composer:

$ composer init

Esse comando conduz você por um pequeno assistente passo a passo. As respostas que você fornecer às solicitações, como o nome do pacote, a descrição, as informações do autor e o tipo de licença, gerarão seu arquivo de pacote composer.json.

A documentação do Composer descreve os valores esperados, bem como outras opções que você pode usar para definir o composer.json do seu projeto.

Observe que o assistente fornece respostas predefinidas para as perguntas quando aplicável, por exemplo, derivando seu nome e e-mail do git. Sinta-se à vontade para alterá-las se quiser.

Essa biblioteca não depende de nenhum outro pacote para funcionar, e portanto você pode responder No às perguntas que especificam dependências.

O assistente mostra uma visualização do conteúdo do arquivo gerado e pede que você confirme para concluir o assistente.

Organizando os arquivos do pacote

Ao concluir o assistente, você cria dois diretórios, além do arquivo composer.json:

• src para o seu código-fonte
• vendor para as dependências que você baixou

Mova o arquivo TemperatureConverter.php para o diretório src. Se sua biblioteca tiver dependências, execute composer install para gerar o carregador automático e instalar as dependências do pacote.

Carregando o código no GitHub

Adicione suas alterações e novos arquivos ao git:

$ git add -A

Faça o commit das alterações feitas no repositório local e envie-as para o repositório remoto no GitHub para que você possa publicar facilmente o projeto na próxima seção:

$ git commit -am "Initial Release" && git push

Crie uma versão de lançamento para sua biblioteca

Com o código no seu repositório, você pode criar uma versão da sua biblioteca com um número de versão para que outros desenvolvedores possam acompanhar suas atualizações estáveis e significativas.

Navegue até o seu repositório no GitHub e clique em Releases abaixo da seção About (Sobre). Na página Releases, onde se espera que você não tenha nada no momento, clique em Create a new release (Criar nova versão).

Preencha alguns detalhes sobre sua versão, como a versão da tag e o título da versão. A versão da tag deve ser um identificador exclusivo para essa versão (exemplo: v1.0.0), e o título da versão deve descrever as alterações incluídas na versão (por exemplo, Versão inicial).

Opcionalmente, você pode adicionar uma descrição da versão. Se você quiser carregar um arquivo, como um binário compilado ou um arquivo de código-fonte, arraste e solte o arquivo na área Attach binaries by dropping them here or selecting them (Anexe binários soltando os arquivos aqui ou selecionando-os), mas isso não é necessário para este tutorial.

Clique em Publish release (Publicar versão) para criar a versão.

Seu projeto agora deve estar disponível na página Releases do seu repositório. Os usuários podem baixar todos os arquivos que você anexou e visualizar as notas da versão. Além disso, se você adicionou uma tag para a versão, outros desenvolvedores poderão usar essa tag para verificar o código exato que foi incluído na versão.

Sua biblioteca está pronta para ser compartilhada com o mundo. Vamos publicá-la como um pacote no Packagist.

Como começar a usar o Packagist

O Packagist é o principal repositório de pacotes do PHP. Ele fornece um local central para que os desenvolvedores publiquem e compartilhem seus pacotes PHP e para que outros desenvolvedores descubram e usem esses pacotes em seus próprios projetos. Vamos publicar seu pacote!

Navegue até o site do Packagist, clique em Login e selecione GitHub como o método de login, para usar sua conta do GitHub para autenticação.

Clique em Authorize (Autorizar) para conceder permissão ao Packagist para acessar sua conta.

Enviando seu pacote Composer para o Packagist

Para publicar um pacote no Packagist, envie o repositório do GitHub que contém o arquivo composer.json que descreve o pacote e suas dependências. Clique em Submit (Enviar) no site do Packagist, forneça a URL do seu repositório na página que aparece e clique em Check (Verificar) para validá-la.

Se o repositório for válido, o Packagist detectará o nome do pacote, e o botão Check se tornará Submit.

Clique em Submit, e o Packagist aguardará um momento para configurar e publicar seu projeto.

É isso aí! Seu pacote agora está disponível no Packagist para que outros desenvolvedores o utilizem como dependência em seus próprios projetos.

Usando seu pacote Composer em outros projetos

Você pode usar seu pacote publicado em outros projetos adicionando-o como uma dependência no arquivo composer.json. Você pode criar e editar o arquivo manualmente, mas é melhor usar o comando do Composer da seguinte forma:

$ composer require rexfordnyrk/tempconv

O Composer cria automaticamente o arquivo composer.json se ele ainda não existir. Em seguida ele localiza, baixa e carrega automaticamente o pacote do Packagist. A saída deve ser semelhante a esta:

Crie um arquivo demo.php que contenha o código do aplicativo de demonstração para trabalhar com a biblioteca.
Você pode usar a classe TemperatureConverter no código do aplicativo desta forma:

<?php
use Rexfordnyrk\Tempconv\TemperatureConverter;

require_once './vendor/autoload.php';

$converter =  new TemperatureConverter();

$fahrenheit = $converter->convert(20, 'C');
echo "20°C is equivalent to $fahrenheit °F\n";

$celsius = $converter->convert(68, 'F');
echo "68°F is equivalent to $celsius °C\n";

Esse código usa a classe TemperatureConverter para converter as temperaturas de 20 Celsius e 68 Fahrenheit e gerar os resultados. O arquivo autoloader.php importado foi criado pelo Composer para carregar todas as dependências de que você precisa. Isso se encarrega de carregar a classe automaticamente quando necessário.

Por fim, execute este código no seu terminal:

$ php demo.php

Você obterá um resultado semelhante a este:

$ php demo.php
20°C is equivalent to 68 °F
68°F is equivalent to 20 °C

Resumo

Você acabou de criar uma biblioteca PHP simples que converte a temperatura de Celsius para Fahrenheit e vice-versa em uma classe orientada a objetos que pode ser reutilizada em outros aplicativos. Você viu como usar o Composer para criar um pacote a partir da classe com o comando Composer Init, e aprendeu algumas práticas recomendadas básicas de organização de código para sua biblioteca. Você publicou sua biblioteca no Packagist para que você e outros desenvolvedores possam usá-la como dependência em outros projetos.

Obviamente, quando terminar de desenvolver seu aplicativo, você precisará hospedá-lo. Leve seu desenvolvimento PHP ao próximo nível com a hospedagem de aplicativos web na Kinsta. Você pode implantar seu aplicativo PHP baseado no Composer em minutos. Basta adicionar seu aplicativo por meio do repositório git do seu projeto, e a Kinsta cuida do resto. O arquivo Composer é detectado automaticamente e seu aplicativo é construído automaticamente. Você pode começar sem riscos hoje mesmo!

Rexford Nyarko

Rexford Nyarko is a solution architect with a background in software and network systems, cloud environments, server administration, and various database technologies. Rexford particularly enjoys explaining technical concepts to non-technical audiences.