Uma análise e anotações sobre as principais recomendações do PHP Framework Interop Group (PHP-FIG).

O PHP Framework Interop é um grupo que define diversos padrões de desenvolvimento usando PHP, estamos falando de recomendações de escrita de código, nomenclaturas de arquivos, criação de diretórios, carregamento de classes e formas de implementações de rotinas. Penso em fazer um artigo específico falando com mais detalhes sobre o PHP-FIG, o que vocês acham?

Agora vou colocar minhas anotações sobre as recomendações e alguns padrões que passei adotar aos meus projetos no dia a dia, todas podem ser encontradas diretamente no site do PHP-FIG.

PSR-1: Padrão básico de codificação: 

O que deve ser considerado como codificação padrão para garantir um alto nível de interoperabilidade técnica entre códigos compartilhados.

Tags:

Use as tags para abertura e fechamento e para saída. Nunca use outras variações (ex: <%, %>, <%=)

Codificação de caracteres:

Arquivos devem usar apenas UTF-8 sem BOM para código PHP. (IDE, Charset, Etc.)

Efeitos colaterais (side effects):

Você pode (incluir um arquivo, conectar a um serviço, gerar uma saída) OU (declarar uma classe, criar uma função, definir uma constante). Mas nunca faça ambos no mesmo arquivo. 

Classes PHP:

Cada classe deve estar em seu próprio arquivo e ter pelo menos um nível de namespace (padrão PSR-4). O nome da classe deve ser declarada em StudlyCaps. 

• Constantes da classe devem ser declaradas em maiúscula e quando preciso podem ser separadas por under_score.
• Propriedades da classe podem ser escritas em $StudlyCaps, $camelCase ou $under_score, não existe uma recomendação rígida para elas, mas é sempre importante escolher uma e usar sempre a mesma. Se for $camelCase, use sempre $camelCase e nunca as outras.
• Métodos da classe devem ser declarados sempre em camelCase().

PSR-2: Guia de estilo de codificação:

Reduzir o atrito cognitivo ao escanear códigos de diferentes autores. A PSR-2 enumerando um conjunto compartilhado de regras e expectativas sobre como formatar o código PHP. 

• Padrão básico de codificação: O código deve seguir todas as recomendações listadas na PSR-1.
• Arquivos: sempre devem terminar com uma linha em branco (Unix linefeed);
• Somente PHP: um arquivo somente com PHP deve omitir a tag ?> de fechamento.;
• Linhas: procure manter suas linhas com no máximo 80 caracteres, quando necessário você poderá usar até 120. Configurado em IDE;
• Espaços finais: certifique-se que o último caractere da linha não é um espaço em branco. Configurado em IDE;
• Legibilidade: pode adicionar linhas em branco para separar blocos de código;
• Recuo: use 4 espaços para indentar seu código, nunca o TAB. Configurado em IDE;
• Declaração: não deve ter mais de uma por linha de código. Configurado em IDE;
• true, false, null: são palavras-chave e constantes do PHP, devem ser escritas sempre em letra minúscula. 

A IDE é sua ferramenta de programação, PHPStorm, netBeans entre outras. Elas já implementam as PSR`s ou tem recursos para automatizar essa implementação.

Namespaces:

Após declarar um, sempre deixe uma linha em branco para então continuar seu código.

• use: quando presentes devem ser declarados após os namespaces;
  • DEVE haver um use por declaração;
  • DEVE haver um espaço após o bloco de declaração do use;

• Regras gerais da PSR para estruturas de controle: 
  • DEVE haver um espaço após a palavra-chave da estrutura de controle;
  • NÃO DEVE haver um espaço após o parêntese de abertura nem antes do parêntese de fechamento;
  • DEVE haver um espaço entre o parêntese de abertura e a chave de abertura;
  • O corpo da estrutura de controle DEVE ser recuado uma vez;
  • A chave de fechamento DEVE estar na próxima linha após o corpo da estrutura;
  • O corpo de qualquer estrutura DEVE estar entre chaves.

Closures: 

• DEVEM ser declaradas com um espaço depois de function e um espaço antes e depois de use;
• A chave de abertura DEVE ir na mesma linha do nome, a chave de fechamento DEVE ir uma linha após o corpo;
• NÃO DEVE haver espaço após o parêntese de abertura ou antes do parêntese de fechamento na lista de argumentos ou variáveis;
• DEVE haver na lista de argumentos ou variáveis um espaço depois da vírgula, mas nunca antes;
• Argumentos com valor padrão DEVEM ir ao final da lista de argumentos. 

PSR-4: Carregamento automático:

Este PSR descreve uma especificação para o carregamento automático e interoperável das classes, assim como mostra onde colocar os arquivos em seu projeto. 

Especificação: 

Entenda classes como todas as classes, interfaces e traits.

1. Um nome de classe totalmente qualificado deve seguir o seguinte formato:
   
   1. O namespace completo DEVE ter um nome de nível superior (Vendor);
   2. O namespace PODE ter um ou mais subnamespaces;
   3. O namespace DEVE terminar com o nome da classe;
   4. Underscore não tem qualquer efeito especial no namespace;
   5. Caracteres alfabéticos PODEM ter qualquer combinação de minúsculas e maiúsculas;
   6. Todos os namespaces DEVEM ser referenciados de forma única;
   7. O Vendor namespace e alguns dos primeiros níveis de sub-namespace DEVEM corresponder a um diretório base;
   8. Cada sub-namespace seguinte deve corresponder a um sub-diretório dentro do diretório base, cada separador de sub-namespace corresponde a um separador de diretório no sistema operacional.
2. Implementações de autoloader NÃO DEVEM lançar exceções, gerar erros de qualquer nível ou retornar um valor.

Usando autoload do composer:

Uma forma mais prática, inteligente e interoperável de criar seu autoload usando o Composer para gerenciar todas as dependências do projeto:

O exemplo abaixo mostra o arquivo de configuração composer.json do Composer. Com ele o gerenciador de dependências PHP poderá automatizar todo o processo de carregamento de classes e componentes para você. A configuração autoload:

Estrutura simples do composer.json:

{
 "name": "UpInside/fsphp",
 "description": "Full Stack PHP Developer",
 "minimum-stability": "stable",
 "authors": [
 {
 "name": "Robson V. Leite",
 "email": "cursos@upinside.com.br"
 "homepage": "https://upinside.com.br",
 "role": "Developer"
 }
 ],
 "config": {
 "vendor-lib": "vendor"
 },
 "autoload": {
 "psr-4": {
 "Source\\": "source/"
 }
 }
}

Configuração do autoload:

"autoload": {
     "psr-4": {
      "Source\\": "source/"
     }
}

Neste ponto estamos informando que nossas classes estão no namespace fornecedor Source, e dentro da pasta raiz source do projeto. Depois de rodar o Composer, basta invocar o autoload: 

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

Essas foram algumas anotações e pontos importantes que encontrei até agora, se tiver alguma sugestão deixe nos comentários. 

Bons projetos e estudos!