Widgets do WordPress: Refatoração, Parte 1

A última postagem incluiu muitas informações sobre como configurar ferramentas de qualidade de código em seu ambiente de desenvolvimento WordPress, mas elas são necessárias se formos fazer muita refatoração.

Mas, como mencionei no início deste post, colocar ferramentas de qualidade de código primeiro nos fornece uma base que podemos usar à medida que refatoramos o clichê (o que claramente precisamos fazer, dada a quantidade de vermelho mostrada pelo GrumPHP).

Honestamente, eu vejo isso como necessário se você estiver fazendo qualquer tipo de desenvolvimento, daí a necessidade de mostrar como configurá-los.

Independentemente disso, o post anterior mostra quanto trabalho cortamos para nós, certo?

Agora vamos começar com a refatoração do WordPress Widget Boilerplate.

Isso não apenas melhorará a qualidade do código, mas também nos guiará por alguns princípios orientados a objetos que podemos aplicar ao construir nossos widgets e podemos aplicar em futuros esforços de desenvolvimento do WordPress.

The WordPress Widget Boilerplate: Refatoração, Parte 1

Talvez a coisa mais empolgante para mim seja trazer esse repositório para os padrões modernos. Se você observar o branch master no GitHub no momento deste post (ou o histórico do repositório posteriormente), verá que ele tem seis anos.

Essa coisa tem seis anos (no momento deste post).

Isso é muito tempo em anos de Internet, não é?

De qualquer forma, em nossos esforços de refatoração, faremos algumas coisas:

• criando uma ramificação a partir da qual trabalhar antes de mesclá-la novamente na ramificação mestre,
• implementando uma maneira mais coesa de organizar arquivos,
• atualizar os padrões de codificação para seguir o que está mais alinhado com o PSR,
• e mais.

Eu coloco isso agora porque provavelmente não vamos chegar a tudo isso neste post, mas vamos cobrir muito terreno. Dito isso, vamos começar.

1 Criando um Ramo de Desenvolvimento

Supondo que você tenha uma cópia do repositório de em sua máquina local, que você deve ter após o último post, a primeira coisa que precisamos fazer é criar um branch para fazer nosso trabalho.

É uma prática recomendada não trabalhar no branch master. Em vez disso, o mestre deve sempre ser usado para implantar a versão estável mais recente do código.

Para isso, digite o seguinte comando no seu terminal:

$ git checkout -b develop

Isso criará uma nova ramificação local. Ele ainda não foi enviado ao GitHub ou ao seu repositório remoto (onde quer que você o esteja mantendo).

A seguir, digite o seguinte comando:

$ git push --set-upstream origin develop

Isso enviará a ramificação de desenvolvimento para o repositório remoto. Feito isso, você poderá ver todas as alterações que implementamos na última postagem em seu repositório remoto.

Se você estiver usando o GitHub, deve ser algo assim:

Se você estiver usando outro serviço, ele ainda deve ser semelhante. Ou seja, a estrutura de diretórios deve ser a mesma, mas a aparência no navegador varia.

Uma Nota sobre o Ramo

Lembre-se, o propósito deste ramo é que façamos todo o nosso trabalho. Dessa forma, não estamos interferindo no branch master do qual muitas pessoas irão extrair.

Para ser claro, talvez ninguém vai tirar isso. Talvez eles vão. Independentemente disso, essas práticas apresentadas aqui visam mostrar como executar um projeto usando ferramentas de controle de origem e qualidade de código para que você possa criar projetos melhores para você, sua empresa e muito mais.

2 Reorganizando Arquivos

A primeira coisa que devemos fazer é reorganizar os arquivos, para que imitem uma estrutura mais moderna. Farei o meu melhor para justificar as decisões que estou tomando para o projeto enquanto fazemos isso; no entanto, sinta-se à vontade para tomar liberdades com a forma como deseja fazê-lo.

As decisões que eu tomo vão afetar o Boilerplate primário. O que você optar por fazer afetará como você poderá usá-lo em seu trabalho diário ou como você optará por avançar com o projeto como um todo.

Atualizando diretórios

Uma das coisas que tento fazer é dividir meus diretórios, para que fiquem o mais claros possível. Isso significa que eu tento fazer o seguinte:

• crie um diretório de ativos para JavaScript e folhas de estilo,
• crie um diretório src para todos os arquivos PHP,
• crie um diretório de idioma para arquivos de internacionalização,
• mantenha todos os outros arquivos na raiz do repositório, para que seja fácil para outros seguirem junto com o README fornecido.

Para fazer isso, vou primeiro remover e mover algumas coisas. Eu tentei organizar isso em uma ordem específica:

1. Vou remover o arquivo README.txt. Este arquivo é usado como um modelo README padrão se você for enviar código para o WordPress Plugin Repository, mas não é necessário para o que eu quero para o Boilerplate.
2. Vou renomear plugin.php para Plugin .php para seguir as convenções do PSR.
3. Também vou renomear lang para idiomas.
4. Vou criar um diretório de ativos e mover e, em seguida, mover os diretórios css e js para esse diretório. Vou criar um subdiretório dev em cada um desses diretórios onde podemos trabalhar em arquivos Sass e JavaScript unminified (ambos virão mais tarde na série).
5. Depois disso, vou criar um diretório src e mover a folha de estilo de visualizações para esse diretório.
6. Eu também renomearei views para Views e também colocarei em maiúsculas os arquivos contidos nela.
7. Finalmente, vou mover tudo para a raiz do diretório. Isso significa que o widget-boilerplate desaparecerá e todos os arquivos residirão no diretório raiz do repositório.

São muitos passos, mas são pequenos. Eu gosto de descrevê-los primeiro para que fique claro o que acontecerá no restante desta seção.

Remova o README

Para fazer isso, basta digitar o seguinte comando em seu terminal na raiz do diretório widget-boilerplate :

$ rm readme.txt

Isso removerá o arquivo. Se você digitar o seguinte comando no seu terminal:

$ git status

Você deve ver algo assim:

Eu sou um fã de garantir que as várias alterações que são enviadas sejam claras e concisas, para que seja mais fácil revertê-las uma de cada vez. Então vamos em frente e confirmar e empurrar essa mudança.

Digite o seguinte:

$ git rm README.txt
$ git add. $ git commit -n -m "Removing the original README.txt template."
$ git push

Isso dirá ao Git para remover o arquivo, adicionar a única alteração ao conjunto de alterações, confirmá-lo sem executar nenhuma ferramenta de qualidade de código (porque não precisamos fazer isso agora; caso contrário, ele falhará) e o enviará por push para o branch de desenvolvimento do repositório remoto .

Agora que temos isso feito, vamos em frente e renomear alguns arquivos.

Renomeando arquivos

Enquanto estamos nisso, não vamos apenas renomear o arquivo plugin .php, mas também os outros arquivos PHP. Esses são arquivos que podem ser agrupados logicamente no mesmo changeset, então faz sentido ir em frente e fazer isso.

Então, no seu terminal, digite os seguintes comandos:

$ mv plugin.php Plugin.php
$ mv views/admin.php views/Admin.php
$ mv views/widget.php views/Widget.php

Ao fazer isso, ainda não fizemos nenhuma alteração nos arquivos, então não há nada para confirmar. Vamos avançar com a renomeação de diretórios.

Criar diretórios; Renomear diretórios

Assim como fizemos com os arquivos, vamos em frente e criar um novo diretório de ativos. No seu terminal, digite o seguinte comando:

$ mkdir assets

Em seguida, queremos mover os diretórios css e js para esse diretório, então digite o seguinte no terminal também:

$ mv css assets
$ mv js assets

E vamos renomear o diretório lang para Languages ​​digitando o seguinte comando:

$ mv lang Languages

Por fim, vamos renomear view para Views:

$ mv views Views

Neste ponto, fizemos todo o possível com os arquivos atualmente no diretório principal. No entanto, ainda precisamos preparar subdiretórios para nossos ativos pré-processados.

Antes de fazer isso, porém, é um bom hábito executar uma rápida verificação de status do git para ver o que existe que pode ser adicionado a um changeset. Se o seu repositório for como o meu, é provável que você veja algo como o seguinte:

Nesse caso, acho que não há problema em adicionar tudo em um único conjunto de alterações com um comentário indicando que renomeamos e movemos os arquivos.

Você pode diferir e se assim for, tudo bem. Seus comandos serão um pouco diferentes dos meus, mas aqui está o que tenho para o meu commit:

$ git add. $ git commit -n -m "Creating new directories; Renaming files."
$ git push

Agora, vamos aos subdiretórios para nossos arquivos pré-processados.

Criar subdiretórios

No diretório CSS, crie um subdiretório chamado dev e crie um arquivo vazio chamado admin.scss e widget.scss, pois trabalharemos com esses arquivos posteriormente na série.

Em seguida, adicione um diretório dev ao diretório JavaScript e adicione o arquivo admin.js vazio e os arquivos widget.js a esses arquivos. Se você quiser, pode mover os arquivos pré-existentes para os diretórios dev, pois esses são os arquivos que usaremos como base para nossos arquivos de desenvolvimento.

Essa é uma etapa opcional; no entanto, fui em frente e fiz isso porque é assim que prefiro trabalhar. Aqui está o conjunto de comandos que eu executei.

Do diretório css …

$ mkdir dev
$ mv admin.css admin.scss && mv widget.css widget.scss
$ mv *.scss dev

Acima, criei o diretório dev para minhas folhas de estilo, renomeei-as para arquivos Sass e as movi para o diretório dev.

Antes de prosseguir, agora é um bom momento para fazer uma verificação de status do git e confirmar as alterações relacionadas às folhas de estilo:

$ git add. $ git commit -n -m "Renaming and moving stylesheets into a dev directory."
$ git push

Agora, no diretório js …

$ mkdir dev
$ mv *.js dev

Como não precisamos alterar o tipo de arquivo dos arquivos associados, podemos simplesmente movê-los para o novo diretório.

Finalmente, vamos fazer a mesma coisa e ver se há alguma mudança que podemos fazer através de uma verificação rápida de status do git (que deve haver). Aqui está uma lista dos comandos que executei para confirmar e enviar minhas alterações:

$ git add. $ git commit -n -m "Adding a JavaScript dev directory and moving the development files."
$ git push

Estamos quase terminando. Tudo o que resta a fazer é mover certos diretórios para a raiz do repositório e renomear o diretório principal para src. Então vamos fazer isso agora.

Mover diretórios para a raiz

Essencialmente, precisamos mover tudo, exceto o arquivo de plug-in e o diretório Views, para fora do diretório widget-boilerplate, e precisamos renomear widget-boilerplate para src.

Parece simples, certo? É bem direto. De dentro do diretório widget-boilerplate :

$ mv assets .. && mv languages ..
$ cd ..
$ mv widget-boilerplate src

Em seguida, confirmarei a alteração no GitHub usando o seguinte:

$ git add. $ git commit -n -m "Reorganizing the directory structure."
$ git push

Agora temos uma estrutura de diretório muito mais moderna configurada. Você pode vê-lo aqui no meu ramo de desenvolvimento.

Uma palavra sobre POO

E agora que temos tudo isso no lugar, podemos começar a escrever código. Mas não se engane: uma parte da programação orientada a objetos também é análise orientada a objetos e design orientado a objetos.

O que fizemos neste post é essencialmente aplicar um projeto arquitetônico orientado a objetos baseado na análise de como o plugin se encaixa.

A próxima parte, porém, é atualizar o código para se livrar de todo o vermelho que vimos ao farejar nosso código.

Na próxima postagem

O objetivo principal do próximo post é continuar atualizando os padrões de codificação para que possamos resolver todos os problemas lançados pelo nosso IDE ou por meio das ferramentas de qualidade de código que estamos executando na linha de comando.

Devemos também ter um repositório muito mais limpo e organizado, e estarmos prontos para mesclar nosso trabalho de volta ao branch master.

Por enquanto, porém, certifique-se de ter um bom controle sobre tudo acima antes de prosseguir, pois é necessário entender o restante do trabalho que temos pela frente.