PHP PSR-1: Basic Coding Standard

PHP-logo.svg

Um dos primeiros esforços na padronização de código PHP foi elaborar uma forma de assegurar alto nível de interoperabilidade entre projetos diferentes, feitos por programadores diferentes. Para isto foi criada a recomendação de Padrão Básico de Codificação PHP ou PSR-1. Ela define formato de codificação do arquivo fonte, organização básica dos arquivos e nomenclatura de classes, constantes, propriedades, métodos e outros pontos que abordaremos a seguir.

1. PSR-1 Padrão Básico de Codificação

1.1 – Arquivos

1.1.1 – Tags PHP

Códigos PHP devem OBRIGATORIAMENTE usar a marcação longa <?php ?>  ou saída curta <?= ?> . Jamais utilizar quaisquer variações das marcações. Se o arquivo for puramente php como é o caso de arquivos de classe entidade ou de controle, finalizar o arquivo com ?>  é desnecessário.

1.1.2 – Codificação de caracteres

Os arquivos PHP do projeto devem usar OBRIGATORIAMENTE a codificação UTF-8 sem assinatura BOM. Igor Escobar explica o que é, o porquê e como converter ou retirar a assinatura BOM caso você a codificação já seja UTF-8.

1.1.3 – Organização de arquivos por contexto

Cada arquivo deve ter um objetivo específico, toda mudança de contexto acarreta na criação de um novo arquivo. Determinar o contexto pode levar a questões mais amplas, por isso o padrão determina dois cenários globais distintos em que a segregação deve acontecer: arquivos de declaração de símbolos e arquivos de “efeitos colaterais”. Vamos compreender primeiramente o que é o termo e sua relação aqui. Sempre que usamos a colocação “efeito colateral” tem que ver com uma determinada ação que pode acabar influenciando no resultado de outras. Trazendo para o universo PHP, um arquivo que pode causar efeito colateral é aquele que por ser meramente inserido na execução do script resulta em (a) saída no HTML, (b) uso explícito de require  ou include ; (c) modificação de atributos do arquivo de configurações do PHP por ini_set() ; (d) emissão de erros ou exceções como, por exemplo, throw new Exception  ou  die(); (e) alteração de valores em variáveis globais ou estáticas; (f) ler ou escrever arquivo. A lista pode ser bem extensa. Qualquer coisa que se pareça com os exemplos mostrados também é considerado arquivo de efeito colateral.

Agora que temos conhecimento do arquivo de efeito colateral fica mais fácil compreender o que é o arquivo de declaração de símbolos. Quando o arquivo determina a criação de classes, funções, constantes, propriedades e outros, é que consideramos ser um arquivo de declaração de símbolos. A execução da lógica desses arquivos não gera saída nem modifica qualquer configuração do servidor ou carrega de forma explícita arquivos. São como os arquivos de efeito colateral, só que ao contrário!

Aqui você pode achar haver um problema com  Validador::validarNumero(); pois como um método estático da classe Validador pode ser utilizado se não pode ser carregado por include  ou require ? Este é um problema que a PSR-4 vai resolver depois com o carregamento automático do arquivo desta classe quando for necessário (postagem em breve).

 

1.2 Namespace e nomes de classes

Tanto os nomes de classes quanto namespaces (incluídos na versão 5.3) devem OBRIGATORIAMENTE seguir o padrão de autocarregamento PSR-4 (postagem em breve). Cada classe deve ficar em seu próprio arquivo e dentro de um namespace de no mínimo um nível. O nome das classes deve ser declarado utilizando o padrão ortográfico StudlyCaps, enquanto que, caso a versão do PHP seja 5.3 ou superior, o arquivo deve necessariamente iniciar com um namespace.

Se por acaso a versão for igual ou menor à 5.2, existe uma convenção que simula o namespace ao colocá-lo como prefixo no nome da classe

 

1.3 Constantes, propriedades e métodos de Classes

1.3.1 Constatantes

As constantes de uma classe devem OBRIGATORIAMENTE ser declaradas com todas as letras em maiúsculo com underlines no lugar dos espaços em branco.

1.3.2 Propriedades

O guia recomenda a utilização dos padrões de ortografia $StudlyCaps , $camelCase  ou $under_score  para nomear as propriedades (variáveis globais ou locais de classe e seus atributos). Independente do padrão escolhido, este deve ser seguido consistentemente dentro de um escopo significativo, como um método, classe, pacote e namespace. Ou seja, a nível de método que é o menor de todos os escopos, nada de utilizar dois padrões diferentes.

1.3.3 Métodos

Todos os métodos devem ser declarados em camelCase(). Especificamente, o padrão indica a variação lowerCamelCase da convenção.

 

Deixe seu comentário