Ferramentas para escrever um código WordPress melhor: Composer

Embora eu ache que o título desta série e os artigos de cada um sejam suficientemente claros, há outras coisas que pretendo fazer com esta série em contraste com as outras séries que escrevi até agora.

Especificamente, duas das coisas que estou tentando fazer são duas:

1. manter cada artigo relativamente sucinto (em comparação com os artigos anteriores),
2. concentre-se em uma coisa de cada vez e mantenha a descrição curta.

Como este é um conteúdo para membros, não me importo que seja um pouco mais longo do que o normal, mas também não quero que seja tão longo que seja difícil de seguir. Prefiro que seja uma leitura curta com algo prático que você possa implementar depois de ler cada post.

E uma das coisas que ajuda muito a escrever melhor código WordPress é o Composer.

Melhor código WordPress com o Composer

Se você lê este blog há algum tempo, então sabe que sou fã do Composer (no entanto, estou longe de ser a única pessoa que trabalha no WordPress que é).

E embora eu tenha escrito algum material sobre isso, não escrevi algo com o objetivo específico de colocá-lo em funcionamento até o final da leitura de um único artigo curto.

Para esse ponto, precisaremos fazer alguns compromissos: a saber, fornecerei um arquivo de configuração de amostra junto com uma maneira de organizar o diretório do seu plug-in. Então, no próximo post, explicarei alguns dos recursos do Composer.

O que é Compositor?

Primeiro, é importante entender o que é o Composer. E é fácil recitar a definição conforme consta no site, não é? É um gerenciador de dependências para PHP.

Mas primeiro, o que é uma dependência?

Para alguns, porém, isso levanta algumas questões:

• O que é uma dependência?
• Por que preciso gerenciá-los?

E se você se aprofundar um pouco mais, poderá descobrir que é um gerenciador de pacotes, e isso simplesmente levanta as mesmas questões, exceto que você substitui “dependency" por “package” e volta ao ponto de partida.

Então, farei o que puder para deixar isso o mais claro possível:

Uma dependência, ou um pacote, um pedaço de software que seu código usa. Pode ser algo no qual ele depende de funcionalidade durante o tempo de execução, como uma maneira de fazer solicitações HTTP, ou pode ser uma biblioteca para converter arrays em XML.

O Composer facilita a inclusão desses pacotes específicos em sua biblioteca, permitindo que você:

• baixe e inclua o pacote em seu plugin,
• carregar automaticamente seu plugin durante o tempo de execução,
• tornar mais fácil para o seu plugin instanciar ou chamar o plugin conforme necessário.

Isso significa que não precisamos encher os diretórios de nossa base de código com muitos arquivos adicionados manualmente e isso significa que não precisamos usar include ou require em todo lugar.

Eles terão seu lugar, que discutirei no próximo post, mas não precisarão ser instalados automaticamente. Em vez disso, o Composer irá gerenciá-los. Portanto, o gerenciador de dependências faz parte de seu propósito.

Agora que você o instalou, você tem algum contexto.

Usando o Composer

Escrever esta seção em particular é um pouco difícil porque todos nós temos necessidades diferentes, certo? Mas, pelo menos, todos podemos tirar proveito de um carregador automático.

Isso é algo que todos nós podemos usar.

Então aqui está o que vou fazer:

1. Vou configurar um diretório básico de plugins,
2. Crie os arquivos necessários para conduzir o plugin,
3. Configure um arquivo Composer simples,
4. Execute

E então eu vou deixar você ver os resultados. Podemos entrar em bibliotecas de terceiros ou outros recursos em um post futuro (ou séries futuras, na verdade).

Mas se nada mais, isso mostrará como usar o Composer para definir um autoloader para que você possa se concentrar em escrever código e não em se perguntar se as classes estão incluídas.

O diretório de plug-ins

Eu geralmente estruturo meus plugins assim:

• há um arquivo bootstrap lido pelo WordPress,
• existe um  diretório src no qual todos os diretórios e arquivos PHP são mantidos,
• há um  diretório de ativos de nível superior onde imagens, arquivos JavaScript e arquivos Sass são mantidos,
• e há uma  pasta de fornecedor criada pelo Composer para abrigar as dependências e o autoloader.

Ocasionalmente, pode haver alguma outra pasta estranha, como uma pasta inc ou lib, mas isso é altamente irregular neste ponto no tipo de trabalho que faço. E por causa disso, não vou me preocupar com isso para este post.

Em vez disso, meu diretório se parece com isso.

O  diretório do fornecedor está ausente porque ainda não criei um arquivo do Composer que é usado para execução. Mas veremos isso antes do final do post.

Arquivos de exemplo

Vamos obter um arquivo de amostra configurado no plugin. E quando digo amostra, também quero dizer simples.

Este arquivo terá um único propósito: imprimir uma mensagem no painel ao fazer login no WordPress.

Lembre-se, porém, que o objetivo disso não é mostrar como escrever um plugin bem arquitetado. Em vez disso, é mostrar como gerar um autoloader para que os arquivos do plugin sejam gerados automaticamente.

Então o bootstrap do plugin se parece com isso :

E o arquivo especificamente responsável por exibir a mensagem se parece com isso :

E se você está curioso sobre o arquivo HTML, também é simples :

Eu disse que era simples.

O arquivo de configuração do compositor

Este arquivo em particular pode ser tão simples ou tão complicado quanto necessário. Para este post, vamos simplificar. O objetivo, para este post, é simplesmente dar um nome, descrição, licença, os autores e depois como configurar o autoloader.

Dê uma olhada aqui, e depois vou explicar o que você vê logo abaixo:

{
    "name": "tommcfarlin/sample-plugin",
    "description": "A sample plugin used for a blog post.",
    "type": "wordpress-plugin",
    "license": "GPL-3.0-or-later",
    "authors": [
      {
        "name": "Tom McFarlin",
        "email": "tom@tommcfarlin.com",
        "homepage": "https://tommcfarlin.com"
      }
    ],
      "autoload": {
        "psr-4": {
          "SamplePlugin": "src/"
        }
      }
  }

Primeiro, o nome, a descrição, o tipo e a licença devem ser fáceis de seguir. A área do autor também é direta.

O carregamento automático é a área com a qual estamos preocupados agora. Deve ficar bem claro.

Resumindo, temos uma diretiva para PSR4 sobre a  qual você pode ler mais e onde um namespace está localizado. Portanto, no exemplo acima, qualquer coisa no namespace SamplePlugin está localizada em src. 

Isto é o que diz ao autoloader onde procurar certos arquivos. E no nosso caso, será apenas procurar a  classe Messenger.

Compositor em execução

Agora que cobrimos o básico do arquivo de configuração do Composer, é hora de executá-lo. Lembre-se de que seu diretório de plugins deve se parecer com isto:

No seu terminal, digite o seguinte comando :

E você deve ver algo assim:

Supondo que tudo tenha corrido bem, você poderá fazer login no WordPress e ativar o plug-in.

Vendo tudo junto

Depois que o plug-in for ativado, você poderá navegar até o painel do seu site. Lá, você deve ver um aviso descartável que se parece exatamente com o que vimos no início do post:

Se você chegou até aqui, então você está pronto para ir! Caso contrário, verifique novamente sua sintaxe para garantir que tudo esteja bem. Se algo estiver errado, é provável que você não tenha conseguido chegar tão longe e, supondo que tenha as constantes de depuração básicas definidas, provavelmente verá onde existe o problema.

Isso não é tudo

Há muito mais no Composer, e eu recomendo ler a documentação dele. Algumas dessas coisas serão abordadas ao examinar as ferramentas que pretendo abordar posteriormente nesta série, mas, por enquanto, recomendo familiarizar-se com algumas das convenções.

Oh! E eu não recomendo verificar o diretório do fornecedor em seu repositório. Isso pode se tornar um diretório enorme mais tarde, e pode minar todo o propósito do Composer.

No próximo post, falarei sobre o porquê. Algumas pessoas fazem isso, e tudo bem, e eu já fiz isso antes, mas é importante ser criterioso sobre quando você faz.

Errar do lado de não fazê-lo. E explicarei o porquê no próximo post.