An open source and free payment gateway for laravel created by Beer And Code Community
- https://flowframework.readthedocs.io/en/stable/TheDefinitiveGuide/PartV/CodingGuideLines/PHP.html
- https://github.com/PhpGt/StyleGuide
Este guia descreve o estilo de codificação PHP para a colaboração no projeto Payment Gateway da comunidade Beer And Code. É provável que desenvolvedores e equipes individuais tenham suas próprias visões fortes sobre determinados estilos de codificação, portanto esse conjunto de documentos deve ser visto como um guia, não um livro de regras. Dito isto, tudo o que está documentado aqui é a preferência dos desenvolvedores principais, portanto, considere os pontos antes de enviar solicitações pull requests (PR). O objetivo deste documento é ajudar a orientar o estilo das contribuições de código para manter um estilo consistente no repositório, definir e justificar as decisões tomadas dentro dele.
O código de exemplo a seguir mostra uma visão geral do estilo proposto neste guia: <?php namespace FastFood\Page;
use FastFood\Logic\OrderLogic;
use FastFood\Menu\MenuFactory;
use Vendor\Food\FoodOrderInterface;
class OrderPage extends OrderLogic implements FoodOrderInterface {
const TYPE_MAIN = "order-type-main";
const TYPE_VEGETARIAN = "order-type-vegetarian";
const TYPE_VEGAN = "order-type-vegan";
const TYPE_GLUTENFREE = "order-type-glutenfree";
private OtherClass $menu;
public function go():void
{
$this->menu = MenuFactory::create($_GET["type"]);
$this->sampleMethod($this->menu->getName(), $this->menu->getSize());
$output = $this->longMethodWithManyArgs(
$this->getDefaultSize(),
123,
"example"
);
}
private function sampleMethod(string $name, int $size = 0):void
{
$maxSize = OtherClass::getMaxSize($name);
if($size === 0) {
$this->menu->fillEmpty(OtherClass::getDefault());
}
elseif($size > $maxSize) {
$size = $maxSize;
}
else {
switch($size) {
case OtherClass::SIZE_INDIVIDUAL:
$this->menu->setStyle("individual");
break;
case OtherClass::SIZE_FAMILY:
$this->menu->setStyle("family");
break;
default:
$this->menu->setStyle(Menu::SIZE_DEFAULT);
break;
}
}
}
public function longMethodWithManyArgs(
int $firstNumber,
int $secondNumber = 0,
string $exampleString = null
):Menu
{
$duplicate = MenuFactory::create($this->menu->getType());
if($duplicate->getSize() !== 0
&& $duplicate->name === $exampleString)
{
return MenuFactory::createDefault();
}
return $duplicate;
}
}
Consulte uma lista com marcadores simplificada abaixo:
- A primeira linha de todos os arquivos .php deve ser exatamente "<?php"
- Nunca use a tag PHP de fechamento (?>)
- Nunca use tags curtas (short tags) do PHP
- Todos os arquivos devem usar apenas UTF-8, sem BOM
- Sempre use o fuso horário America/Sao_Paulo para armazenar data e hora
- Todo arquivo de biblioteca .php deve conter exatamente uma classe
- Todo arquivo de biblioteca .php deve ser livre de efeitos colaterais
- Em arquivos e códigos, use palavras no singular (por exemplo, item, stylesheet, user) em vez de palavras no plural
- Evite notação húngara, onde nomes de arquivos / variáveis que indicam seu tipo
- Use camelCase para nomear variáveis
- Nunca use variáveis globais
- Propriedades sempre devem ser declaradas
- As variáveis sempre devem ser declaradas no topo do bloco em que são usadas
- Evite usar a palavra-chave final, a menos que seja necessário
- Evite chamar funções no namespace global
- Os códigos de programação, variáveis e funções deverão ser escritos em inglês
- Use 4 espaços ao invés de tabulação (PSR-12)
- Evite blocos de código com "dupla indentação" onde nenhuma indentação é necessária para facilitar a leitura
- Não deixe espaços em branco no final das linhas
- Seja o mais rigoroso possível para aplicar 80 linhas de caracteres
- As chaves de abertura DEVE seguir sua própria linha (PSR-12)
- As chaves de fechamento devem sempre ser colocadas no início de sua própria linha (PSR-12)
- Toda condicional if() deve conter chaves de abertura e fechamento, ainda que o corpo possua apenas 1 linha.
- Um nível de indentação deve ser aplicado dentro e somente dentro das chaves
- Os condicionais entre colchetes não devem obter indentação extra ao quebrar em linhas separadas
- Nunca deixe declarações condicionais sem restrições ou sem indentação
- Nenhum espaço extra deve ser colocado após uma palavra-chave da estrutura de controle ou nome da função
- Os colchetes de abertura não devem ter espaço depois; os colchetes de fechamento não devem ter espaço antes
- Vírgulas que separam listas de variáveis devem ter um espaço ou nova linha depois, sem espaço em branco antes
- Um espaço deve envolver operadores binários e ternários, mas não unários
- Um espaço deve envolver todos os operadores de tipo
- Diretórios e arquivos devem ser mapeados para namespace ou web (view)
- Os espaços para nome devem ser mapeados para os caminhos de arquivo, conforme PSR-4
- Arquivos e diretórios devem estar em minúsculas com hífen onde não forem mapeados para namespace
- Os arquivos e diretórios mapeados para namespace devem usar UpperCamelCase
- Arquivos e diretórios mapeados na Web devem usar palavras em minúsculas e hifenizadas
- Uma classe só deve ser carregada automaticamente - nunca use require ou include
- Constantes só devem ser declaradas em uma classe (deve atender somente à classe declarada)
- As constantes devem usar UPPERCASE_UNDERSCORED
- As propriedades devem usar $camelCase
- Os métodos devem usar camelCase()
- As classes devem ter todos ou nenhum membro estático
- Todos os parâmetros devem definir seu tipo sempre que possível
- Todos os métodos devem definir seu tipo de retorno sempre que possível
- Os métodos devem evitar ficar mais de 20-50 linhas
- Se possível evite comentários, pois um um bom código não precisa de comentários (se possível leia o livro Código Limpo)
- Para comentários embutidos, devem ser usados comentários com barra dupla (//)
- Comentários embutidos não devem ter indentação, começando na coluna 1
- Comentários embutidos podem abranger várias linhas, prefixadas com a barra dupla
- Os comentários de bloco devem ser usados apenas para fornecer documentação de classe e método na forma de blocos de documentos
- Os comentários, juntamente com os docblocks, devem ser esparsos e pesados para evitar documentação obsoleta
- As estruturas de dados que representam coleções devem ser acessíveis por array, collections e / ou iterables
- Estruturas de dados que representam itens individuais devem usar funções getter
- Arrays associativos devem ser usadas apenas para pares simples de valor-chave
- Mova arrays associativos para um object com getter / setter sempre que possível
- Classes estáticas devem ser usadas apenas quando verdadeiramente não tiverem estado
-
A princípio vamos trabalhar apenas com feat (feature, novo recurso) e fix (hotfix, correção de problemas)
-
O título (primeira linha do commit) deverá estar no imperativo (adiciona) e não adicionado.
-
A mensagem do commit deverá ser obrigatoriamente em português, conforme definido por todos em live
-
O commit deverá seguir a seguinte estrutura:
<tipo>[escopo opcional]: <descrição> <corpo opcional> <rodapé opcional>
Com base nisso, um commit de hotfix ficaria assim: fix(containers/profile.php): ajusta o argumento da função getPaymentMethods
getPaymentMethods usava o tipo XPTO para receber argumento. Agora recebe o argumento correto do tipo FOO.
Resolve a issue #132
OBS.: o escopo está opcional, pois quando for um novo recurso (feat) pode ser que entre vários arquivos, inviabilizando informar todos no escopo.
| Nome completo da classe | Nome não qualificado | Observações |
|---|---|---|
| \Neos\Flow\Session\Php | Php | A classe não é uma representação do PHP |
| \Neos\Cache\Backend\File | Php | A classe não é uma representação do PHP |
| \Neos\Flow\Session\Php | File | A classe não representa um arquivo! |
| \Neos\Flow\Session\Interface | Interface | Não permitido, "Interface" é uma palavra-chave reservada |
| \Neos\Foo\Controller\Default | Default | Não permitido, "Default" é uma palavra-chave reservada |
| \Neos\Flow\Objects\Manager | Manager | Apenas "Manager" é muito confuso |
| Nome completo da classe | Nome qualificado | Observações |
|---|---|---|
| \Neos\Flow\Session\PhpSession | PhpSession | Essa é uma sessão PHP |
| \Neos\Flow\Cache\Backend\FileBackend | FileBackend | Um arquivo de back-end |
| \Neos\Flow\Session\SessionInterface | SessionInterface | Um controlador padrão |
| \Neos\Foo\Controller\StandardController | StandardController | Não permitido, "Interface" é uma palavra-chave reservada |
| \Neos\Flow\Objects\ObjectManager | ObjectManager | "ObjectManager" é mais claro |
| \Neos\Flow\Objects\Manager | Manager | Apenas "Manager" é muito confuso |
| Nome completo da classe | Nome qualificado | Observações |
|---|---|---|
| \Neos\Flow\Mvc\ControllerInterface | ControllerInterface | Conseqüentemente, a interface pertence a todos os controladores no sub namespace Controller |
| \Neos\Flow\Mvc\Controller\ControllerInterface | Bem melhor! | |
| \Neos\Cache\AbstractBackend | AbstractBackend | O mesmo aqui: na realidade, essa classe pertence aos back-ends |
| \Neos\Cache\Backend\AbstractBackend | Bem melhor! |
Observação: Ao especificar nomes de classe para PHP, sempre faça referência ao espaço para nome global dentro do código no espaço de nomes usando uma barra invertida à esquerda. Ao fazer referência a um nome de classe dentro de uma string (por exemplo, dado ao método get do ObjectManager, em expressões pointcut ou em arquivos YAML), nunca use uma barra invertida à esquerda. Isso segue a noção nativa do PHP de nomes em strings sempre sendo vistos como totalmente qualificados.
Toda terça-feira, das 20:00h as 21:00h
Canal do discord do Beer And Code (LIVES > payment gateway)
Discord: https://discord.gg/mhyKFgv