Convenções de Nomenclatura

Classes

O Zend Framework utiliza um padrão de nomes de classes de forma que os nomes das classes mapeiam diretamente os diretórios onde estão armazenadas. O diretório raiz da biblioteca padrão do Zend Framework é o diretório "Zend/" e o diretório raiz da biblioteca de extras é "ZendX/". Todas as classes do Zend Framework são armazenadas hierarquicamente sob tais diretórios.

Nomes de classes devem conter somente caracteres alfanuméricos. Números são permitidos em nomes de classes mas são desencorajados na maioria dos casos. Underscores são permitidos somente no lugar de separador de diretórios. O arquivo "Zend/Db/Table.php", por exemplo, deve mapear a classe de nome "Zend_Db_Table".

Se um nome de classe é composto de mais de uma palavra, a primeira letra de cada nova palavra deve ser maiúscula. Letras maiúsculas em sequência não são permitidas. A classe "Zend_PDF", por exemplo, não é permitida, enquanto "Zend_Pdf" é.

Estas convenções definem um mecanismo de pseudonamespace para o Framework. O Zend Framework irá adotar o recurso de namespace do PHP assim que ele se tornar disponível e prático para nossos desenvolvedores os utilizarem em suas aplicações.

Exemplos desta convenção de nomenclatura podem ser vistos em nomes de classes nas bibliotecas padrão e de extras.

Nota

Importante: Códigos que devem ser disponibilizados junto às bibliotecas do Zend Framework mas não são parte das bibliotecas padrão ou de extras (por exemplo, código de aplicação ou bibliotecas que não são distribuídas pela Zend) nunca devem iniciar com "Zend_" ou "ZendX_".

Classes abstratas

Em geral, classes abstratas seguem as mesmas convenções de classes, com uma regra adicional: nomes de classes abstratas devem terminar com o termo "Abstract", que não pode ser precedido por um underscore. Por exemplo, Zend_Controller_Plugin_Abstract é considerado um nome inválido, mas Zend_Controller_PluginAbstract ou Zend_Controller_Plugin_PluginAbstract seriam nomes válidos.

Nota

Esta convenção de codificação é nova na versão 1.9.0 do Zend Framework. Classes de datas anteriores a esta versão podem não seguir esta regra mas serão renomeadas no futuro a fim de obedecê-la.

A razão de tal mudança é o uso de namespace. Como pretendemos que o Zend Framework 2.0 utilize PHP 5.3, utilizaremos namespaces. A maneira mais fácil de automatizar a conversão para namespaces é simplemente converter underscores para o separador de namespace -- mas sob as antigas convenções de nomenclatura isto deixa o nome da classe como somente "Abstract" ou "Interface" -- as quais são palavras-chave reservadas em PHP. Se prefixarmos o nome do (sub)componente ao nome da classe, podemos evitar tais problemas.

Para ilustrar a situação, considere converter a classe Zend_Controller_Request_Abstract para utilizar namespaces:

namespace Zend\Controller\Request;

abstract class Abstract
{
    // ...
}

Claramente isto não irá funcionar. Sob as novas convenções de nomenclatura, entretanto, isso se tornaria:

namespace Zend\Controller\Request;

abstract class RequestAbstract
{
    // ...
}

Ainda retemos a semântica e a separação de namespace enquanto omitimos os problemas com palavras-chave; ao mesmo tempo, a classe abstrata é melhor descrita.

Interfaces

Em geral, interfaces seguem as mesmas convenções de classes, com uma regra adicional: nomes de interface podem opcionalmente terminar com o termo "Interface", que não pode ser precedido por um underscore. Por exemplo, Zend_Controller_Plugin_Interface é considerado um nome inválido, mas Zend_Controller_PluginInterface ou Zend_Controller_Plugin_PluginInterface seriam nomes válidos.

Embora esta regra não seja obrigatória, ela é fortemente recomendada, já que provê uma boa pista visual aos desenvolvedores sobre quais arquivos contém interfaces em vez de classes.

Nota

Esta convenção de nomenclatura é nova na versão 1.9.0 do Zend Framework. Classes de datas anteriores a esta versão podem não seguir esta regra, mas serão renomeadas no futuro a fim de obedecê-la. Veja a seção anterior para informações sobre a razão da mudança.

Nomes de arquivos

Para todos os outros arquivos, somente caracteres alfanuméricos, underscores e hifens são permitidos. Espaços são estritamente proibidos.

Qualquer arquivo que contenha código PHP deve terminar com a extensão ".php", com a notável exceção de scripts de view. Os exemplos a seguir mostram nomes de arquivo aceitáveis para classes do Zend Framework:

Zend/Db.php

Zend/Controller/Front.php

Zend/View/Helper/FormRadio.php

Nomes de arquivos devem mapear nomes de classes, como descrito acima.

Funções e métodos

Nomes de funções devem conter somente caracteres alfanuméricos, não sendo underscores permitidos. Números são permitidos mas desencorajados na maioria dos casos.

Nomes de funções devem sempre começar com letra minúscula e, quando consistir de mais de uma palavra, a primeira letra de cada palavra deve ser maiúscula. Esta formatação é comumente chamada de "camelCase".

A utilização de verbos é geralmente encorajada, devendo os nomes de funções ser tão verbais quanto prático a fim de descrever de forma clara seu propósito e comportamento.

Estes são exemplos de nomes aceitáveis de funções:

filterInput()

getElementById()

widgetFactory()

Para programação orientada a objetos, acessores de variáveis estáticas ou de instância devem sempre ser prefixados com "get" ou "set". Ao implementar padrões de design (“design patterns”), como o singleton ou o factory, o nome do método deve conter o nome do padrão onde prático a fim de descrever claramente seu comportamento.

Para métodos de objetos que são declarados com o modificador "private" ou "protected", o primeiro caractere do nome do método deve ser um underscore. Esta é a única aplicação aceitável de um underscore em um nome de método. Métodos declarados como "public" nunca devem conter um underscore.

Funções em escopo global (também chamadas de "funções flutuantes") são permitidas mas desencorajadas na maioria dos casos. Considere encapsular estas funções em uma classe estática.

Variáveis

Nomes de variáveis devem conter somente caracteres alfanuméricos, não sendo underscores permitidos. Números são permitidos mas são desencorajados na maioria dos casos.

Para variáveis de instância declaradas com o modificador "private" ou "protected", o primeiro caractere do nome da variável deve ser um underscore. Esta é a única aplicação aceitável de um underscore em nome de variável. Variáveis-membras declaradas com "public" nunca devem começar com um underscore.

Assim como nomes de funções (veja seção 3.3), nomes de variáveis devem sempre começar com uma letra minúscula e seguir a convenção "camelCase".

A utilização de verbos é encorajada, ou seja, variáveis devem sempre ser tão verbais quanto prático para descrever os dados que o desenvolvedor pretende armazenar nelas. Nomes concisos de variáveis como "$i" e "$n" são desencorajados para todos os contextos de laço, exceto os menores. Se um loop contém mais de 20 linhas de código então as variáveis de índice devem ter nomes mais descritivos.

Constantes

Constantes devem conter tanto caracteres alfanuméricos quanto underscores. Números são permitidos.

Todas as letras usadas em um nome de constante devem ser maiúsculas, enquanto todas as palavras devem ser separadas por underscores.

Por exemplo, EMBED_SUPPRESS_EMBED_EXCEPTION é permitido enquanto EMBED_SUPPRESSEMBEDEXCEPTION não.

Constantes devem ser definidas como membras de classe com o modificador "const". Definir constantes em escopo global com a função "define" é permitido mas fortemente desencorajado.