A linguagem de programação PHP, assim como outras linguagens, permite que os desenvolvedores escrevam código de diversas maneiras possíveis. Essa característica é até interessante, pois garante mais liberdade para os desenvolvedores, porém isso também pode ser um problema.
A diferença no modo como os desenvolvedores escrevem código pode gerar uma verdadeira salada de frutas dependendo do tamanho da equipe e quantas pessoas já passaram no projeto ao longo do tempo.
Baseado nisso muitas linguagens e tecnologias definem recomendação de padrões. No PHP essas recomendações são criadas por um grupo chamado PHP-FIG e são chamadas de PSR.
PHP-FIG
PHP Framework Interop Group (PHP-FIG) é um grupo formado por desenvolvedores da comunidade PHP em 2009. O objetivo inicial do grupo era definir recomendações que fossem aplicadas aos Frameworks PHP participantes e facilitasse a interoperabilidade entre os frameworks que cresciam rapidamente.
Ao passar do tempo o grupo começou a perceber que as recomendações poderiam ser úteis em outros tipos de aplicações, não somente em frameworks, já que a linguagem PHP possui grandes CMSs como Wordpress, Magento, Drupal, Joomla e diversos outros. Com isso o grupo ganhou membros também de outros tipos de projetos, não somente Frameworks.
As recomendações precisam ser votadas e aprovada pelos membros do PHP-FIG para que possam ter validade. Somente membros podem votar, porém qualquer desenvolvedor da comunidade que queira participar das discussões pode, basta entrar nos canais de contato do PHP-FIG.
PSR
As recomendações criadas pelo PHP-FIG são agrupadas em PHP Standard Recommendation (PSR). Uma PSR basicamente possui recomendações sobre um tema específico, como por exemplo, a PSR-12 que fala sobre padronização de sintaxe de código.
Cada PSR é identificada por um número e possui um status. O status nos ajuda a saber se devemos ou não seguir as recomendações daquela PSR:
Rascunho - enquanto uma PSR está em discussão e construção ela é definida como rascunho;
Aceito - quando uma PSR é votada e aprovada o status dela passa para aceita;
Descontinuada - se por algum motivo depois de aceita aquela PSR não é mais relevante ela é descontinuada;
Abandonada - quando o rascunho de uma PSR não é aceito, ela passa para o estado abandonada e é mantida por questão de documentação.
Existem PSRs que tratam de diversos temas como: estilo de código, autoload, cache, log, HTTP e outros. É possível ver a lista de PSRs e seus estados no site do PHP-FIG.
RFC
Assim como o PHP-FIG se propôs a discutir recomendação de padrões para a linguagem PHP, existem outros grupos que definem recomendações para diversos tipos de processos que acontece na internet. Esses grupos criam documentos técnicos chamados de Request For Comments (RFC), em português requisição para comentários. As RFCs possuem um funcionamento muito parecido com as PSRs, inclusive o processo de criação das PSRs é inspirado no processo de criação das RFCs.
As PSRs usam RFCs dentro de suas recomendações. Elas são usadas tanto como base para padronização de alguma recomendação, quanto para orientar o requerimento de uma recomendação.
Nível de requerimento
A RFC mais importante para conseguirmos interpretar corretamente as recomendações das PSRs é a RFC 2119. Ela padroniza os níveis de requerimento de uma determinada recomendação.
Podemos dividir os níveis de requerimentos em:
Deve - representado pelas palavras (MUST, REQUIRED e SHALL)
Não deve - representado pelas palavras (MUST NOT e SHALL NOT)
Recomendado - representado pelas palavras (SHOULD e RECOMMENDED)
Não recomendado - representado pelas palavras (SHOULD NOT e NOT RECOMMENDED)
Opcional - representado pelas palavras (MAY e OPTIONAL)
Vamos pegar um exemplo prático para entender o nível de requerimento. A PSR-1 que fala sobre padrão básico de codificação tem a seguinte recomendação:
Files MUST use only <?php and <?= tags.
Em português ficaria: arquivos DEVEM usar somente as tags <?php e <?= .
O nível de requerimento é representado por uma das palavras listadas na RFC2119, ele nos ajuda a entender quando devemos ou não seguir uma recomendação dentro de uma PSR. No exemplo acima nós DEVEMOS usar somente essas duas tags se quisermos dizer que nosso código segue a PSR-1.
PSR-1 e PSR-12
As duas primeiras PSRs que aconselho estudar são: a PSR-1 e a PSR-12. A primeira fala sobre padronização básica do nosso código e a segunda fala sobre o estilo como o código é escrito. A PSR-12 substituiu e estendeu a PSR-2, que precisou ser revisada devido a avanços na linguagem de programação PHP.
Nos próximos artigos vamos falar sobre essas duas importantes PSRs. Fique atento em nosso blog e redes sociais.
PSR — Padrões necessários para ter um código de qualidade
Dhyogo Almeida
6 min read Sep 28, 2018
Introdução
Creio que muito de nós pouco sabíamos que existia um padrão de escrita de código em PHP quando começamos nossa jornada nessa linguagem. A famosa frase: “Funciona? Então tá valendo!” era a que pairava sobre meus pensamentos.
Porém, com o tempo, percebemos (ou deveríamos) evoluir e buscar não somente o funcionamento da aplicação em si, mas sim, a qualidade da escrita do código. Então nos deparamos com as PSRs, um acrônimo de PHP Standards Recommendations (https://www.php-fig.org/psr/), que nos oferece padrões para escrevermos o nosso código.
PHP-FIG. O que é? O que faz?
FIG significa Framework Interoperability Group, formado por um grupo composto por representantes de grandes projetos PHP (CakePHP, Doctrine, Zend Framework, etc.). O objetivo desse grupo é criar padrões que todos esses projetos citados possam adotar. Tais padrões podem ser adotados em nossos projetos e são grandes os benefícios que alcançamos ao utilizá-los, tais como: código legível; fácilidade de dar manutenção; interoperabilidade (componentes de um framework ou pessoa podem ser facilmente integrados em outro).
Neste artigo, vamos falar resumidamente da PSR-1 e PSR-2. Para ter o detalhamento completo e conhecer as demais PSRs, acesso o site oficial da documentação: https://www.php-fig.org/psr/.
PSR-1 — Basic Coding Standard
1. O código PHP deve usar as tags <?php ?> ou short-echo <?= ?>. Não utilize <? ?>.
2. Os arquivos PHP devem usar somente a codificação UTF-8 sem BOM (Byte Order Mark)
UTF-8 sem BOM é a codificação padrão do editores. Sabemos que a codificação de um arquivo pode nos dar dores de cabeça.
3. Você pode declarar classes, funções, constantes, etc. e não causar outros efeitos colaterais ou deve executar a lógica com efeitos colaterais, mas não deve fazer as duas coisas juntas.
O que isso significa? Os arquivos PHP devem ter suas responsabilidades separadas. Vejamos um exemplo:
Neste exemplo, o arquivo está alterando uma configuração do PHP, incluindo um outro arquivo PHP, gerando uma saída e ainda declarando uma função. Vamos à um exemplo correto:
4. Namespace e classes devem seguir um autoloading especificado na PSR-0 e PSR-4 que serão abordadas em uma outra oportunidade.
5. As classes devem ser declaradas utilizando o padrão chamado pelo PHP-FIG de StudlyCaps.
Isso significa que se tenho uma classe que deriva da junção de dois ou mais nomes, como por exemplo, HomeController, o H de home e o C de controller devem ser maiúsculas. Uma classe homeController estaria com o nome errado, não diferente de Homecontroller, que também estaria incorreta.
E se a classe tiver apenas um nome, como por exemplo Home? O correto é exatamente Home, com H maiúsculo.
Este padrão também se aplica à Traits e Interfaces.
6. As constantes devem ser declaradas em maiúsculo e separadas por underscore (se necessário).
As PSRs não restringem quanto à definição do uso de nomes para as propriedades.
8. Métodos devem ser declarados em camelCase().
Os métodos devem ser declarados com o caractere da primeira inicial palavra em minúsculos e a demais iniciais em maiúsculo, como por exemplo, o método camelCase(). E se o método tiver somente uma palavra? Então ficaria camel().
PSR-2 — Coding Style Guide
Como vimos, a PSR-1 é simples e sua aplicação é de fácil entendimento. Com a PSR-2 não é diferente, e uma completa a outra. E adivinha qual a primeira especificação da PSR-2? Exato! Isso mesmo, seguir a PSR-1!
1. O seu código deve utilizar 4 espaços para indentação (recuo), e não TABs.
Um dia com certeza alguns de nós já utilizamos o TAB para indentar o nosso código. O problema não é utilizar o TAB em si, mas utilizá-lo sem configurar a quantidade de espaços adequada, no nosso caso, 4 espaços. Graças aos bons editores que temos, como Sublime, Visual Studio Code e etc., podemos configurar sem problemas. E para nos ajudar mais ainda e não restar dúvidas quanto à indentação de nosso código, podemos utililizar uma ferramenta de linha de comando, chamada PHP CS Fixer, que nada mais é do que um projeto open source hospedado no github (https://github.com/FriendsOfPHP/PHP-CS-Fixer) que nos ajuda e muito a aplicar a PSR-1, PSR-2 e mais um pouco.
2. Não deve haver um limite rigoroso (hard limit) no comprimento das linhas, o limite "suave"(soft limit) deve ser de 120 caracteres, as linhas deveriam ser de 80 caracteres ou menos.
Polêmico? Creio que não. Podemos dividir essa recomendação em algumas partes.
Primeira: não deve haver um hard limit.
Segunda: o soft limite deve ser de 120 caracteres em uma linha.
Terceira: o recomendado é que se tenha no máximo 80 caracteres em uma linha.
Mas e agora? É 120 ou 80 caracteres por linha? A RFC 2119 (http://www.ietf.org/rfc/rfc2119.txt) nos ajuda a interpretar as palavras chaves que são utilizadas nas PSRs, conforme o próprio PHP-FIG usa e destaca:
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
Recomendado significa que: podem existir razões válidas para ignorar este item em particular, ou seja, os 80 caracteres, mas que essa decisão deve ser tomada cuidadosamente para fazer o contrário, ou seja, ultrapassar os 80 caracteres.
3. Deve haver uma linha em branco após o namespace e deve haver outra linha em branco após o bloco de declarações use.
Mais uma coisa: Utilize uma keyworduse por declaração.
E para os métodos? A mesma regra aplicada para classes: abrir chaves na próxima linha após a declaração e fechar chaves após o corpo do método.
Ah! Essa regra também se aplica à Interfaces e Traits.
5. As keywords extends e implements devem ser declaradas na mesma linha que o nome da classe. Os implements podem ser declarados na mesma linha ou dividos em várias linhas, onde cada linha é indentada uma vez. O primeiro item da lista deve estar na próxima linha e deve havar apenas uma interface por linha.
9. Quando presentes, as keywords abstract e final devem vir antes da visibilidade. E também quando presente a keyword static, esta deve vir após a visibilidade.
10. Abaixo segue a regra geral para as estruturas de controle. Vamos utilizar If, elseif, else e switch,case.
Deve haver um espaço após a keyword da estrutura;
Não deve haver espaço após o parêntese de abertura e também não deve haver espaço que anteceda o parêntese de fechamento;
Deve haver um espaço entre o parêntese de fechamento e a abertura de chaves;
O corpo da estrutura deve ser indentado uma vez (4 espaços);
A chave de fechamento deve estar na próxima linha após o corpo;
Vamos aos exemplos do if, elseif e else:
Para switch, case, temos:
A colocação de parênteses e chaves segue a mesma racional do if;
O case deve ser indentado uma vez (4 espaços) utilizando como referência o switch;
A keyword break (ou outra keyword de finalização) deve ser indentada uma vez (4 espaços) utilizando como referência o case;
Deve haver um comentário informando quando não for utilizado o break. Vamos ver tudo isso aplicado no exemplo abaixo:
Conclusão
Em meio às diversas PSRs existentes, utilizando a PSR-1 e PSR-2 já teremos grandes benefícios se aplicados os padrões que ambas propõem. Sugiro que você a partir de agora comece a aplicar estes padrões e assim escreva códigos mais legíveis e elegantes. Pense no seu código como um livro no qual você é o autor. Um código bem feito traz benefícios para todos, incluindo você e sua equipe. Think about it!
Padrão novo no PHP – PSR-18 (HTTP Client)
Fala pessoal, tudo bom? Hoje vamos sair um pouco das bibliotecas e falar um pouco sobre uma nova PSR que foi aprovada essa semana.
Para quem não sabe, as PSRs (PHP Standards Recommendations) são recomendações de “padrões” para algumas características em PHP. Por exemplo, temos padrões de autoload (PSR-4), padrões de escrita de código (PSR-1 e PSR-2), padrões de logging (PSR-3), caching (PSR-6), entre outras. A idéia é que tenhamos uma pequena padronização entre os frameworks e demais projetos. Essas PSRs são propostas pelo PHP-FIG.
O PHP-FIG (The PHP Framework Interop Group) é um grupo formado de líderes de grandes projetos PHP. E eles propõem alguns modelos de padrões para que fique mais fácil a integração entre os diversos projetos PHP. Esses padrões nem sempre são seguidos e nem obrigatórios. Mas, quando utilizados facilitam demais a vida de quem programa em PHP.
A PSR-18 trata de interfaces para HTTP Clients. Um HTTP Client é uma biblioteca que tem como objetivo enviar mensagens de solicitação HTTP e retornar uma mensagem de resposta HTTP.
O objetivo deste PSR é permitir que os desenvolvedores criem bibliotecas desacopladas das implementações do Client HTTP. Isso tornará as bibliotecas mais reutilizáveis, pois reduz o número de dependências e reduz a probabilidade de conflitos de versões.
Um segundo objetivo é que os Clients HTTP possam ser substituídos de acordo com o princípio da substituição de Liskov. Isso significa que todos os Clients DEVEM se comportar da mesma maneira ao enviar uma solicitação.
Definições
Client – Um Client é uma biblioteca que implementa essa especificação com o objetivo de enviar mensagens de solicitação HTTP compatíveis com o PSR-7 e retornar uma mensagem de resposta HTTP compatível com o PSR-7 para uma Calling Library.
Calling Library – Uma calling library é qualquer código que faz uso de um Client. Ele não implementa as interfaces desta especificação, mas consome um objeto que as implementa (um Client).
Client
Um Client é um objeto que implementa ClientInterface.
Um Client pode:
Optar por enviar uma solicitação HTTP alterada daquela que foi fornecida. Por exemplo, poderia compactar um corpo de mensagem de saída.
Optar por alterar uma resposta HTTP recebida antes de retorná-la a Calling Library. Por exemplo, ele poderia descompactar um corpo de mensagem de entrada.
Se um Client optar por alterar a solicitação HTTP ou a resposta HTTP, ele DEVE garantir que o objeto permaneça internamente consistente. Por exemplo, se um Client optar por descompactar o corpo da mensagem, ele também deverá remover o cabeçalho Content-Encoding e ajustar o cabeçalho Content-Length.
Note que, como resultado, como os objetos PSR-7 são imutáveis, a Calling Library NÃO DEVE assumir que o objeto passado para ClientInterface::sendRequest() será o mesmo objeto PHP que é realmente enviado. Por exemplo, o objeto Request que é retornado por uma exceção PODE ser um objeto diferente daquele passado para sendRequest(), portanto, a comparação por referência (===) não é possível.
Um Client deve:
Remontar uma resposta HTTP 1xx de várias etapas para que o que é retornado para a Calling Library seja uma resposta HTTP válida do código de status 200 ou superior.
Tratamento de erros
Um Client não deve tratar uma solicitação HTTP bem formada ou uma resposta HTTP como uma condição de erro. Por exemplo, os códigos de status de resposta nas faixas 400 e 500 NÃO PODEM causar uma exceção e DEVEM ser devolvidos a Calling Library normalmente.
Um Client deve lançar uma instância de Psr\Http\Client\ClientxceptionInterface se, e somente se, ele não puder enviar a solicitação HTTP ou se a resposta HTTP não puder ser analisada em um objeto de resposta PSR-7.
Se uma solicitação não pode ser enviada porque a mensagem de solicitação não é uma solicitação HTTP bem formada ou está faltando alguma informação crítica (como um host ou método), o Client deve lançar uma instância de Psr\Http\Client\RequestExceptionInterface.
Se a solicitação não puder ser enviada devido a uma falha de rede de qualquer tipo, incluindo um tempo limite, o Client DEVE lançar uma instância de Psr\Http\Client\NetworkExceptionInterface.
Os Clients podem lançar exceções mais específicas do que as definidas aqui (um TimeOutException ou HostNotFoundException, por exemplo), desde que implementem a interface apropriada definida acima.
Interfaces
Client Interface
namespacePsr\Http\Client;usePsr\Http\Message\RequestInterface;usePsr\Http\Message\ResponseInterface;interfaceClientInterface{/**
* Sends a PSR-7 request and returns a PSR-7 response.
*
* @param RequestInterface $request
*
* @return ResponseInterface
*
* @throws \Psr\Http\Client\ClientExceptionInterface If an error happens while processing the request.
*/publicfunctionsendRequest(RequestInterface $request): ResponseInterface;}
ClientExceptionInterface
namespacePsr\Http\Client;/**
* Toda exceção relacionada ao HTTP Client DEVE implementar essa interface.
*/interfaceClientExceptionInterfaceextends\Throwable{}
RequestExceptionInterface
namespacePsr\Http\Client;usePsr\Http\Message\RequestInterface;/**
* Exceção para quando uma solicitação falhou.
*
* Exemplos:
* - A solicitação é inválida (por exemplo, o método está ausente)
* - Erros de solicitação de tempo de execução (por exemplo, o fluxo do corpo não é pesquisavel)
*/interfaceRequestExceptionInterfaceextendsClientExceptionInterface{/**
* Returns the request.
*
* The request object MAY be a different object from the one passed to ClientInterface::sendRequest()
*
* @return RequestInterface
*/publicfunctiongetRequest(): RequestInterface;}
NetworkExceptionInterface
namespacePsr\Http\Client;usePsr\Http\Message\RequestInterface;/**
* Lançada quando a solicitação não pode ser concluída devido a problemas de rede.
*
* Não há objeto de resposta, pois essa exceção é lançada quando nenhuma resposta é recebida.
*
* Exemplo: o nome do host de destino não pode ser resolvido ou a conexão falhou.
*/interfaceNetworkExceptionInterfaceextendsClientExceptionInterface{/**
* Retorna a requisição
*
* O objeto request pode ser um objeto diferente daquele passado para ClientInterface::sendRequest()
*
* @return RequestInterface
*/publicfunctiongetRequest(): RequestInterface;}
Em breve veremos essas implementações na maioria dos Clients HTTP e será muito mais fácil as integrações.
