Padrões de codificação¶

Operadores ternários¶

Operadores ternários são admissíveis quando toda a operação ternária se encaixa em uma única linha. Já operações mais longas devem ser divididas em declarações if else. Operadores ternários nunca devem ser aninhados. Opcionalmente parênteses podem ser usados ao redor da verificação de condição ternária para esclarecer a operação:

// Bom, simples e legível
$variable = isset($options['variable']) ? $options['variable'] : true;

// Aninhamento é ruim
$variable = isset($options['variable']) ? isset($options['othervar']) ? true : false : false;

Arquivos de template¶

Em arquivos de template (arquivos .php) os desenvolvedores devem usar estruturas de controle por palavra-chave. A legibilidade em arquivos de template complexos é muito melhor dessa forma. As estruturas de controle podem tanto estar contidas em grandes blocos de código PHP, ou ainda em tags PHP separadas:

<?php
if ($isAdmin):
    echo '<p>Você é o usuário administrador.</p>';
endif;
?>
<p>A seguinte estrutura também é aceitável:</p>
<?php if ($isAdmin): ?>
    <p>Você é o usuário administrador.</p>
<?php endif; ?>

Declaração de tipo¶

Argumentos que esperam objetos, arrays ou callbacks (válidos) podem ser declarados por tipo. Nós apenas declaramos métodos públicos, porém, o uso da declaração por tipo não é livre de custos:

/**
 * Descrição do método.
 *
 * @param \Cake\ORM\Table $table A classe Table a ser usada.
 * @param array $array Algum valor em formato array.
 * @param callable $callback Algum callback.
 * @param bool $boolean Algum valor booleano.
 */
public function foo(Table $table, array $array, callable $callback, $boolean)
{
}

Aqui $table deve ser uma instância de \Cake\ORM\Table, $array deve ser um array e $callback deve ser do tipo callable (um callback válido).

Perceba que se você quiser permitir $array ser também uma instância de \ArrayObject você não deve declará-lo, pois array aceita apenas o tipo primitivo:

/**
 * Descrição do método.
 *
 * @param array|\ArrayObject $array Algum valor em formato array.
 */
public function foo($array)
{
}

Funções anônimas (Closures)¶

Para se definir funções anônimas, segue-se o estilo de codificação PSR-12, onde elas são declaradas com um espaço depois da palavra-chave function, e um espaço antes e depois da palavra-chave use:

$closure = function ($arg1, $arg2) use ($var1, $var2) {
    // código
};

Tipos de variáveis¶

Tipos de variáveis para serem usadas em DocBlocks:

Tipo

Descrição

mixed

Uma variável com múltiplos tipos ou tipo indefinido.

int

Variável de tipo int (número inteiro).

float

Variável de tipo float (número decimal).

bool

Variável de tipo bool (lógico, verdadeiro ou falso).

string

Variável de tipo string (qualquer valor dentro de « « ou “ “).

null

Variável de tipo null. Normalmente usada em conjunto com outro tipo.

array

Variável de tipo array.

object

Variável de tipo object. Um nome específico de classe deve ser usado, se possível.

resource

Variável de tipo resource (retornado de mysql_connect() por exemplo). Lembre-se que quando você especificar o tipo como mixed, você deve indicar se o mesmo é desconhecido, ou quais os tipos possíveis.

callable

Variável de tipo função.

Você também pode combinar tipos usando o caractere de barra vertical:

int|bool

Para mais de dois tipos é melhor usar mixed.

Ao retornar o próprio objeto, e.g. para encadeamento, use $this ao invés:

/**
 * Função Foo.
 *
 * @return $this
 */
public function foo()
{
    return $this;
}

Short Echo¶

O short echo deve ser usado em arquivos de template no lugar de <?php echo. Deve também, ser imediatamente seguido por um espaço em branco, a variável ou função a ser chamada pelo echo, um espaço em branco e a tag de fechamento do PHP:

// errado = ponto-e-virgula, sem espaços
<td><?=$name;?></td>

// certo = sem ponto-e-virgula, com espaços
<td><?= $name ?></td>

A partir do PHP 5.4 a tag short echo (<?=) não é mais considerada um atalho, estando sempre disponível independentemente da configuração da chave short_open_tag.

Funções¶

Escreva todas as funções no padrão «camelBack», isto é, com a letra da primeira palavra minúscula e a primeira letra das demais palavras maiúsculas:

function longFunctionName()
{
}

Classes¶

Escreva todas as funções no padrão «CamelCase», isto é, com a primeira letra de cada palavra que compõem o nome da classe maiúscula:

class ExampleClass
{
}

Variáveis¶

Nomes de variáveis devem ser tanto curtas como descritivas, o quanto possível. Todas as variáveis devem começar com letra minúscula e seguir o padrão «camelBack» no caso de muitas palavras. Variáveis referenciando objetos devem estar de alguma forma associadas à classe indicada. Exemplo:

$user = 'John';
$users = ['John', 'Hans', 'Arne'];

$dispatcher = new Dispatcher();

Visibilidade¶

Use as palavras reservadas do PHP5, private e protected para indicar métodos e variáveis. Adicionalmente, nomes de métodos e variáveis não-públicos começar com um underscore singular (_). Exemplo:

class A
{
    protected $_iAmAProtectedVariable;

    protected function _iAmAProtectedMethod()
    {
       /* ... */
    }

    private $_iAmAPrivateVariable;

    private function _iAmAPrivateMethod()
    {
        /* ... */
    }
}

Endereços para exemplos¶

Para qualquer URL e endereços de email, use «example.com», «example.org» e «example.net», por exemplo:

• Email: someone@example.com

• WWW: http://www.example.com

• FTP: ftp://ftp.example.com

O nome de domínio «example.com» foi reservado para isso (see RFC 2606), sendo recomendado o seu uso em documentações como exemplos.

Arquivos¶

Nomes de arquivos que não contém classes devem ser em caixa baixa e sublinhados, por exemplo:

long_file_name.php

Moldagem de tipos¶

Para moldagem usamos:

Tipo

Descrição

(bool)

Converte para boolean.

(int)

Converte para integer.

(float)

Converte para float.

(string)

Converte para string.

(array)

Converte para array.

(object)

Converte para object.

Por favor use (int)$var ao invés de intval($var) e (float)$var ao invés de floatval($var) quando aplicável.

Constante¶

Constantes devem ser definidas em caixa alta:

define('CONSTANT', 1);

Se o nome de uma constante consiste de múltiplas palavras, eles devem ser separados por um underscore, por exemplo:

define('LONG_NAMED_CONSTANT', 2);