Além da prefixação: um guia do desenvolvedor WordPress para namespaces PHP

Publicados: 2019-11-12

Prefixe tudo.

É um ditado tão antigo quanto o próprio software WordPress. A prefixação tem sido um padrão para os desenvolvedores do WordPress por tanto tempo que é difícil imaginar fazer algo diferente. Mas, chegou a hora de algo novo. Bem, está muito atrasado, mas o WordPress fica um pouco para trás nas práticas padrão no mundo PHP maior.

Prefixar é a prática de criar uma versão amigável ao código do nome do seu projeto e colocá-la na frente de funções, classes e outras coisas no namespace global. Por exemplo, você nomearia uma função tavern_get_post() em vez de get_post() para evitar conflitos de nome de função, o que resultaria em um erro fatal.

A prefixação é uma forma de “namespacing”, que é apenas uma maneira elegante de dizer que os nomes neste espaço pertencem a um projeto específico. No entanto, o prefixo (e o sufixo, que é menos comum) é um hack de uma época em que não existia solução para a linguagem PHP.

O PHP 5.3 introduziu um método oficial de namespace, então o padrão existe há anos. Como o WordPress 5.2 aumentou o requisito mínimo de PHP para 5.6, é hora de os desenvolvedores abandonarem seus velhos hábitos e alcançarem o resto do mundo PHP.

Namespace (quase) tudo

O namespace PHP cobre apenas os seguintes itens.

  • Aulas
  • Interfaces
  • Características
  • Funções
  • Constantes declaradas com a palavra-chave const mas não define()

Quando se trata de identificadores de script, nomes de tamanho de imagem, opções de banco de dados e outros itens no namespace global, você ainda deve prefixá-los. Esses são IDs e estão fora do escopo do namespace do PHP.

Como criar namespaces

Os namespaces são simples de declarar. Na parte superior de qualquer arquivo PHP que você deseja usar um namespace específico, declare-o conforme mostrado no trecho de código a seguir.

 <?php

namespace Taverna;

O que esta linha de código faz é declarar que tudo dentro deste arquivo em particular tem o namespace de Tavern .

Dê uma olhada em uma função simples sob esse namespace para gerar um Hello, World! mensagem.

 <?php

namespace Taverna;

função olá() {
    _e( 'Olá, Mundo!', 'example-textdomain' );
}

Se seguisse as regras antigas de prefixação, hello() teria sido nomeado tavern_hello() . No entanto, esse não é o caso dos namespaces. A função hello() é encapsulada dentro do namespace Tavern e não entrará em conflito com outras funções chamadas hello() .

Classes e interfaces funcionam da mesma forma que funções. Com um nome de classe de Article , o arquivo de classe pode ter a seguinte aparência.

 <?php

namespace Taverna;

artigo de classe {
    // ...
}

Nota: Deve haver apenas uma classe ou interface por arquivo. Isso é particularmente importante se você planeja usar um carregador automático.

Como nomear namespaces

Os desenvolvedores gostam de discutir sobre como nomear as coisas, e não há uma solução única para todos. A regra mais importante é ser único para evitar conflitos com o código de outros projetos. Uma das melhores maneiras de fazer isso é usar um namespace de Vendor de nível superior com um subnamespace de Package .

Suponha que o namespace do fornecedor fosse Tavern e o projeto em questão fosse um tema WordPress chamado News . O namespace do projeto pode ter a seguinte aparência.

 <?php

namespace Tavern\News;

Isso pode ser um pouco verboso para alguns desenvolvedores. Se o nome do seu projeto já for bastante exclusivo, como “Awesomesauce”, você pode simplesmente querer usar o seguinte.

 <?php

namespace Awesomesauce;

Você vai querer criar algum tipo de convenção padrão, no mínimo, para si mesmo. Eventualmente, você desejará entrar em coisas como carregamento automático, portanto, ter um sistema que você siga em todos os seus projetos ajudará. Sinta-se à vontade para examinar o padrão PHP-FIG Autoloader.

Importando classes e funções para um namespace diferente

Quando você precisa usar uma classe ou função de um namespace diferente do namespace atual, você precisa importá-la. Isso é feito através da palavra-chave use em PHP.

A instrução use deve vir após a declaração do namespace . Ele também deve fazer referência ao nome de classe totalmente qualificado. O código a seguir importa a classe Tavern\Helpers\Post para um arquivo com um namespace diferente.

 <?php

namespace Taverna\Modelo;

use Taberna\Ajudantes\Post;

Depois de importado, você pode usar a classe Post diretamente, conforme mostrado no próximo snippet.

 $postagem = nova postagem();

A partir do PHP 5.6, você também pode importar funções e constantes de outros namespaces usando a use function use const , respectivamente. O bloco de código a seguir demonstra como importar uma função e uma constante.

 <?php

namespace Taverna\Modelo;

use a função Tavern\Helpers\func_name;
use const Tavern\Helpers\CONSTANT_NAME;

Alias ​​de classes e funções

Eventualmente, você se deparará com uma situação em que precisará importar uma classe ou função que tenha o mesmo nome de uma classe ou função no namespace atual. Você pode estar pensando que esse é o problema que os namespaces deveriam resolver. Felizmente, o PHP fornece um método para criar um alias na importação.

Suponha que você tenha uma classe chamada Tavern\User e precise implementar a interface Tavern\Contracts\User . Ao importar a interface, você precisará criar um alias conforme mostrado abaixo.

 <?php

namespace Taverna;

use Tavern\Contracts\User como UserContract;

class User implementa UserContract {
    // ...
}

O as UserContract anexado ao final da instrução de use cria um alias para a interface do User . Você pode usar com segurança o novo nome UserContract sem erros.

Classes, interfaces, funções e constantes seguem o mesmo método para criar um alias.

Organizando a estrutura de pastas com base em namespaces

É uma prática padrão no mundo PHP mais amplo que os namespaces e a estrutura de arquivos e pastas do projeto correspondam. Isso facilita para outros desenvolvedores localizarem facilmente o código em seu projeto. Também simplifica a construção de carregadores automáticos para carregar classes sob demanda.

Geralmente, todo o código PHP deve ir para uma pasta /src , /inc ou com nome semelhante em seu projeto. Um exemplo de arquivo de plug-in e estrutura de pastas pode ser semelhante ao seguinte.

 /nome-plugin
    /src
        /Testemunho
            /Ativar.php
            /Setup.php
        /Visualizar
            /Post.php
            /Página.php

Se seguir a mesma estrutura com namespaces, os arquivos .php acima conterão as seguintes classes.

  • Tavern\Core\Activate
  • Tavern\Core\Setup
  • Tavern\View\Post
  • Tavern\View\Page

Observe que os nomes de arquivos e pastas diferenciam maiúsculas de minúsculas e devem corresponder exatamente ao namespace e ao nome da classe.

Claro, você é livre para seguir qualquer convenção que desejar. No entanto, a recomendação anterior é uma boa prática e simplificará a forma como você organiza seus projetos a longo prazo.

Benefícios do uso de namespaces

O benefício mais óbvio é evitar confrontos entre classes e funções com o mesmo nome. Você deve usar namespaces reais pelo mesmo motivo que usou prefixos.

Os namespaces ajudam a evitar nomes de classe longos. Digitar nomes longos em um projeto grande é, na melhor das hipóteses, uma prática tediosa.

Alterne implementações com mais facilidade importando. Depois de aprender a importar classes e interfaces de outros namespaces, você pode alternar a implementação de uma interface com uma única linha de código.

O carregamento automático de classes é muito mais fácil se você seguir o padrão PSR-4: Autoloader, que requer pelo menos um namespace de nível superior.

Para desenvolvedores no espaço profissional, você ganhará uma habilidade comercializável além do ecossistema WordPress. Você terá dificuldade em encontrar trabalho de desenvolvimento PHP se não souber como usar namespaces. Não é um conceito difícil de entender, mas pode haver uma curva de aprendizado para alguns na prática.