Composer: Como criar pacotes PHP

pacotes Composer e PHP

Este é o meu terceiro artigo sobre o Composer (gerenciador de pacotes PHP) aqui no blog . Nele vamos falar sobre como criar nosso próprio pacote e como publica-lo no Packagist e alternativas para pacotes privados.

Se você quiser ser avisado quando novos artigos sairem, cadastre-se na newsletter do blog:

Quando aprendemos sobre modularização, uma das necessidades é podermos gerenciar as versões de cada módulo de forma que você possa lançar correções, novas funcionalidades, alterar recursos e descontinuar outros sem quebrar os projetos em que o módulo está instalado.

O Composer é um gerenciador de pacotes e uma das funções dele é exatamente cuidar para que sua aplicação receba as atualizações dos módulos/pacotes necessários sem quebrar o seu projeto.

Mas para chegar nesse ponto existem alguns detalhes que você precisa entender:

  • O que é versionamento semântico
  • Como versionar meu projeto
  • Como criar um pacote com Composer
  • O que é um repositório no Composer
  • Como publicar no Packagist
  • Repositórios privados (não abordado nesse artigo além de uma introdução)

Considerações

Este assunto é bem mais extenso do que trato aqui, eu queria que ele fosse um guia para o assunto e mesmo assim ficou enorme.

Novos artigos vem por aí dependendo da receptividade deste, então compartilhe e cadastre-se na newsletter, assim eu vou saber que este artigo é realmente interessante e que valeu escrever e revisar as mais de 2300 palavras nele.

Saber sobre modularização e pacotes me ajuda a “economizar” HORAS de trabalho todos os dias, já que eu posso reaproveitar partes inteiras de um mesmo projeto.

O que é versionamento semântico

No mundo de gerenciamento de software existe algo terrível conhecido como inferno das dependências (“dependency hell”). Quanto mais o sistema cresce, e mais pacotes são adicionados a ele, maior será a possibilidade de, um dia, você encontrar-se neste poço de desespero.

https://semver.org/lang/pt-BR/

Versionamento é uma forma de controlar o histórico de alterações de um sistema de forma a identificar e registrar alterações/correções executadas.

Existem MUITAS formas de se versionar um sistema, porém a mais adotada atualmente é o versionamento semântico.

Vamos tomar como exemplo o Laravel, framework PHP. No momento em que escrevo este artigo estamos na versão 6.12.0 e cada um destes números significa alguma coisa.

Neste ponto, a própria documentação oficial da Semantic Versioning 2.0.0 é bem clara:

6 versão Maior(MAJOR): quando fizer mudanças incompatíveis na API,
12 versão Menor(MINOR): quando adicionar funcionalidades mantendo compatibilidade, e
0 versão de Correção(PATCH): quando corrigir falhas mantendo compatibilidade.

É bem simples, quando você começa o desenvolvimento tome para sí que você está na versão 0.y.z, isso quer dizer que QUALQUER coisa pode mudar no projeto de uma hora para outra, a versão 0 é reservada para o desenvolvimento, mas no momento em que publicar um projeto a versão passa para 1.y.z e a partir daí, qualquer alteração gera uma nova versão de acordo com as regras de MAJOR, MINOR e PATCH.

Além disso você pode versionar etapas de teste, como por exemplo a versão 1.0.0-alpha, as palavras-chave que mais vejo são:

  • dev – Em desenvolvimento
  • alpha – Rodada de testes interno (equipe diretamente ligada ao desenvolvimento)
  • beta – Rodada de testes que soma pessoal que não participou diretamente do desenvolvimento
  • rc – Release candidate – Versão candidata ao lançamento, última rodada de testes

Cada uma das etapas acima pode ainda receber um novo número para versionamento, isso quer dizer que podem existir sub-etapas:

  • 1.0.0-dev
  • 1.0.0-alpha.1
  • 1.0.0-alpha.2
  • 1.0.0-alpha.3
  • 1.0.0-beta
  • 1.0.0-beta.2
  • 1.0.0-beta.3
  • 1.0.0-rc.1
  • 1.0.0-rc.1
  • 1.0.0-rc.2
  • 1.0.0-rc.22
  • 1.0.0-rc.23

Outro ponto importante são casos como as versões LTS (Long-term support) que costumam durar mais tempo sem alterações nas versões MAJOR e MINOR, com isso você pode usá-las com garantia de receber correções de bug e segurança sem alterações no projeto e por um longo período (alguns anos na maioria das vezes).

Claro que Semantic Versioning vai além do que eu estou escrevendo aqui, da uma olhada no site oficial e aprenda mais sobre, mas o que descrevi aqui já é mais que o suficiente para você poder avançar neste artigo.

Site oficial: https://semver.org/lang/pt-BR/

Como versionar meu projeto

Ok, mas como eu versiono um projeto? Utilizando um bom sistema de controle de versão.

Um sistema de controle de versão vai gerenciar cada alteração no seu projeto, é uma excelente ideia você usar um, além de versionar as alterações eles também ajudam na hora de “ramificar” a aplicação, gerando versões LTS ou até mesmo para gerenciar os testes e deploy.

Eu utilizo o Git para gerenciamento de versões e sigo o padrão Gitflow para organizar tudo, uma das grandes vantagens de se trabalhar com essa estrutura é que eu tenho um ramo chamado develop que é publicado no servidor de homolocação e o ramo master que vai para produção.

  • Homologação: ambiente “clone” do produção em que o projeto é publicado para testes antes da publicação final.
  • Produção: ambiente em que o projeto é publicado para acesso final.

Vou tomar como base aqui o GitHub, que é um “armazenador” (essa palavra existe?) de repositórios Git, se você não tem uma conta lá ta perdendo, se tem: ME SEGUE.

A primeira coisa que você precisa para começar a versionar seu código é baixar e instalar o Git no seu computador, como o processo muda um pouco de sistema operacional para sistema operacional, eu recomento dar uma Googlada sobre ou ir neste site:

https://git-scm.com/

Eu tenho certeza que um programador tem as skills necessárias para instalar um software.

O Git tem MUITOS recursos, mas os principais e mínimos necessários para este artigo são

  • git init – Cria um repositório Git no diretório atual
  • git add [arquivo] – Adiciona um arquivo em staging (pronto para ser “versionado”)
  • git commit – “Versiona” o arquivo

Eu sei, é muito superficial, mas vou deixar alguns links para te ajudar enquanto eu não escrevo artigos sobre o assunto, já que nesse exato momento estamos em mais de 800 palavras neste artigo e eu NEM COMECEI o assunto principal.

Leia nesta ordem:

  1. https://git-scm.com/book/pt-br/v2/Come%C3%A7ando-Sobre-Controle-de-Vers%C3%A3o
  2. https://git-scm.com/book/pt-br/v2/Fundamentos-de-Git-Obtendo-um-Reposit%C3%B3rio-Git

Este site que linkei acima tem 10 capítulos fora os apêndices, eu só estou pedindo os 2 primeiros SOMENTE você quiser ir além no assunto.

Prática

Para iniciar nosso projeto, vamos criar um repositório Git, adicionar arquivos, versionar e por fim, publicar no GitHub.

Primeiramente, crie um diretório para o projeto, eu chamei de pacotes-composer. Depois abra no Terminal/CMD e aponte para este diretório (comando cd), se você instalou o Git no Windows, da pra abrir o Git Bash clicando com botão direito no diretório do projeto e ir em Git Bash here.

Se for a sua primeira vez com Git, configure-o teclando:

git config --global user.name "Fulano de Tal"
git config --global user.email fulanodetal@exemplo.br

Claro, useu seus próprios dados no comando acima.

Em seguida inicie um repositório:

git init

Adicione um arquivo chamado HelloWorld.php dentro de um diretório chamado src:

<?php

namespace ErikFig;

class HelloWorld
{
    public function handler()
    {
        echo 'Hello World';
    }
}

Agora precisamos adicionar o arquivo na staging area, isso quer dizer que ele está pronto para ir para ser versionado no Git (ou “commitar”, para os mais íntimos – sim, conjugamos vermos em duas linguas ao mesmo tempo).

git add .

O ponto quer dizer que eu vou adicionar TODOS os arquivos na staging area, use com cautela, mas se você preferir pode adicionar o arquivo informando o caminho a partir da raiz do projeto (onde você rodou o git init).

git add src/HelloWorld.php

O resultado final vai ser o mesmo, com ponto ou com src/HelloWorld.php NESTE CASO.

E por fim, vamos adicionar o arquivo ao versionamento do Git:

git commit -m "mensagem que descreva as alterações"

Pronto, agora vamos enviar para o Github.

Mas antes, precisamos criar um repositório no GitHub, acesse o site a baixo e crie uma conta, se já tiver uma, certifique-se de estar logado.

https://github.com/

Agora clique no botão + e em seguida New repository.

GitHub - New Repository

Na próxima tela tome o cuidado de preencher conforme eu fiz com o meu:

Formulário de crição de repositório no GiitHub

O nome do repositório tem que ser único, mas somente no perfil selecionado, isso quer dizer que eu não posso criar outro repositório com o mesmo nome, mas você pode criar um com o nome que eu usei.

A visibilidade public (público) quer dizer que QUALQUER um vai poder ver o seu código e até sugerir correções (e por sugerir, quero dizer enviar as correções PRONTAS para você aprovar). O Packagist só trabalha com repositórios públicos, então você precisa configurar assim.

Em Initialize this repository with a README não marque.

Esta é a tela que você vai ver quando clicar no botão verde:

Aonde está escrito …or push an existing repository from the command line, copie os comandos (são duas linhas).

O meu é:

git remote add origin git@github.com:erikfig/pacote-composer.git
git push -u origin master

Claro que você tem que copiar as linhas de comando do SEU repositório, eu só mandei as minhas pra te ajudar localizar.

Execute os comandos no diretório do seu projeto, no mesmo que rodou os outros comandos Git.

Atualize a página do seu repositório no GitHub quando os comandos terminarem de executar.

O processo para enviar novas atualizações sempre que você alterar algo é:

  • git add [arquivo]
  • git commit – “mensagem”
  • git push origin master

Mas com o que temos já da pra avançar.

Como criar um pacote com Composer

Para saber como instalar o Composer, leia este artigo:

Para ver um guia inicial de como criar um projeto com o Composer, veja este artigo:

Eu recomendo a leitura COMPLETA dos artigos acima antes de continuar a leitura deste, mas para ajudar você a ir mais direto ao ponto vou colocar um guia de leitura para economizar nosso tempo.

O primeiro artigo é somente se você NÃO tem o Composer instalado e pode ir direto pro final, no tópico Instalando o Composer.

No artigo Colocando a mão na massa – iniciando projeto PHP você pode ir direto ao tópico Colocando a mão na massa – iniciando projeto PHP.

Em resumo ao segundo artigo, vamos precisar de um arquivo chamado composer.json:

{
    "name": "erikfig/pacotes-composer",
    "authors": [
        {
            "name": "Erik Figueiredo",
            "email": "erik.figueiredo@gmail.com"
        }
    ],
    "require": {},
    "autoload": {
        "psr-4": {
            "ErikFig\\": "src"
        }
    }
}

O bloco PSR-4 diz para o Composer carregar qualquer arquivo sob o namespace ErikFig automaticamente.

Rode o comando composer install.

Para testarmos tudo, crie um bootstrap.php na raiz do projeto com o seguinte conteúdo:

<?php

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

(new ErikFig\HelloWorld)->handler();

E rode ele com o PHP:

php bootstrap.php

Este deve ser o resultado:

Normalmente o próprio composer init cria um arquivo .gitignore, mas se isso não aconteceu, faça você mesmo:

/vendor/

Esse arquivo diz para o Git qual diretório não deve ser indexado (ou seja, ignorado), é uma boa ideia você remover o vendor gerado pelo Composer, além de deixar o processo mais rápido (com menos arquivos), alguns recursos dentro do vendor podem ser gerados com base no seu sistema operacional atual.

Vamos atualizar nosso repositório.

git add .
git commit -m "adicionado Composer"
git push origin master

Pronto, repositório no GitHub atualizado.

O que é um repositório no Composer

Agora que já temos nosso projeto publicado online, o próximo passo é configurá-lo em um repositório do Composer.

O Composer também trabalha com repositórios, no caso do Composer um repositório nada mais é que um local onde os arquivos estão registrados (no Packagist, por exemplo).

O mais importante e que você precisa entender é que NÃO importa o repositório, ele deve apontar para um diretório aonde exista um composer.json, que será usado pelo Composer para instalar e configurar o pacote, tudo automaticamente.

O Composer suporta vários tipos de tipos de repositórios

  • Tipo Composer: Esse é o padrão, um arquivo chamado packages.json que o Composer lê. Sempre que você roda o comando composer require [algum-pacote] o Composer vai ler o conteúdo de um packages.json no servidor do Packagist, mais especificamente este arquivo: http://repo.packagist.org/packages.json
  • Tipo VCS: Usa um endereço de sistema de controle de versão (Git, por exemplo) para instalar um pacote.
  • Tipo PEAR: Usado para instalar pacotes PEAR
  • Tipo Package: Usado para instalar pacotes de outras fontes

Também existem tipos de pacotes que podem ser hospedados por você mesmo e/ou de forma privada.

  • Packagist Privado: Serviço pago, para hospedar pacotes privados
  • Satis: Gerador de repositório estático, isso quer dizer que ele gera um tipo de “Packagist” estático que você mesmo gerencia e hospeda, ideal para pacotes privados.
  • Artifact: Basicamente um diretório com arquivos zip, claro, em uma explicação mais simplificada.
  • Path: Um diretório do seu próprio computador com um composer.json dentro (eu uso esse mais do que gostaria).

É claro que eu só dei uma ideia geral sobre o assunto, o que vamos usar neste artigo é o Packagist. Se você quiser saber mais sobre os diferentes tipos de repositórios, recomendo ler o site oficial:

https://getcomposer.org/doc/05-repositories.md

Como publicar no Packagist e Baixar no Composer

Publicar artigos no Packagist é bem simples, você só precisa:

  • Se cadastrar no site
  • Adicionar o pacote
  • Configurar o GitHub par avisar o Packagist quando alterações forem feitas.

Para se cadastrar, basta acessar o Packagist e clicar em Create Account no topo do site ou Sign in se já tiver conta, da até pra usar sua conta do GitHub pra não ter que preencher formulários (e melhorar a integração).

Após ter acessado, basta clicar no botão submit que tomará o lugar do menu anterior.

Agora basta colar a url do repositório e clicar no botão check, se tiver algum problema com seu arquivo ele vai mostrar aqui, olha o meu como ficou:

Botão verde mais uma vez e pronto:

A imagem em vermelho informa que você precisa configurar um hook do GitHub, isso serve para atualizar seu pacote no Packagist automaticamente sempre que atualizar no GitHub, caso contrário você vai ter que clicar no botão Update (verde) toda viz que fizer um git push.

Para fazer esta integração (caso não tenha logado com conta do GitHub), garanta que você está logado no Packagist com o GitHub ou integre as contas acessando https://packagist.org/profile/edit e clique no “botãozão” com o logo do GitHub.

Acesse o endereço do aplicativo do Packagist no Github e autorize o acesso:

https://github.com/settings/connections/applications/a059f127e1c09c04aa5a

Isso deve resolver e a mensagem em vermelho que diz “This package is not auto-updated” deve sumir.

Esse link deve dar mais informações:

https://packagist.org/about#how-to-update-packages

Para testar, vá em algum projeto com Composer (você pode criar outro) e instale usando o comando composer require [nome-do-pacote]:dev-master.

O nome do pacote é definido no parâmetro name do composer.json

Olha o meu:

composer require erikfig/pacotes-composer:dev-master

O dev-master no final do comando se refere ao branch (ramificação) que o composer deve acessar no Git, para não ter que informá-lo você precisa criar a primeira versão semântica.

Versionando o pacote

Para criar sua primeira versão, acesse o repositório no GitHub e clique em releases.

Depois em Create a new release.

Informe a versão (eu usei v1.0.0) e clique em Publish release.

Pode ser que demore alguns minutos para a versão ser publicada no Packagist e ela estará apontando para o ponto atual do histórico do Git, isso quer dizer que quando você enviar novas atualizações elas NÃO serão trazidas quando a versão 1.0.0 for informada, você vai obter a versão que tem/tinha quando o release foi criado.

Então:

  • composer require erikfig/pacotes-composer para pegar o release mais rescente publicado.
  • composer require erikfig/pacotes-composer:1.0.0 para pegar os arquivos exatamente como estavam na versão 1.0.0
  • composer require erikfig/pacotes-composer:dev-master para pegar os arquivos mais rescentes e independente de release.

Assim você pode pegar exatamente a versão do código que você quer e instalar com um comando!

Repositórios privados

Claro que ainda vou escrever mais sobre o assunto, mas para hospedar repositórios privados eu recomento usar o Satis, o Path ou um VSC com chave SSH configurada.

Você pode configurar uma chave SSH entre seu computador e o GitHub (por exemplo) e usar os repositórios privados do site para manter seus código protegido e ainda usar facilmente com o Composer.

Merece um artigo né?

Para ser avisado quando ele sair, cadastre-se na newsletter:

Agradeço muito e aproveito para me desculpar pelo artigo ter passado da cota.

Autor: Erik Figueiredo

Músico, gamer amador, tutor de programação, desenvolvedor freelancer full cycle, com foco em PHP (Laravel e CakePHP), Javascript (Front e Node.js), Dart (Front e Flutter) e infra.

Um comentário em “Composer: Como criar pacotes PHP”

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *