Conventions de nommage

Classes

Zend Framework emploie une convention de nommage des classes où les noms des classes mènent directement dans les répertoires dans lesquels elles sont stockées. Le répertoire racine de Zend Framework est le répertoire "Zend/", tandis que le répertoire racine de la librairie extras de Zend Framework est "ZendX/". Toutes les classes sont stockées de façon hiérarchique sous ces dossiers racines.

Les noms de classes ne peuvent contenir que des caractères alphanumériques. Les nombres sont autorisés, mais déconseillés. Les tirets bas ("_") ne sont autorisés que pour être utilisés comme séparateur de chemin ; le nom de fichier "Zend/Db/Table.php" doit mener à la classe appelée "Zend_Db_Table".

Si un nom de classe comprend plus d'un mot, la première lettre de chaque nouveau mot doit être mis en majuscule. La mise en majuscule de lettres successives n'est pas autorisée, c'est-à-dire qu'une classe "Zend_PDF" est interdit alors que "Zend_Pdf" est autorisé.

Ces conventions définissent un pseudo mécanisme d'espace de noms pour Zend Framework. Zend Framework adoptera la fonctionnalité des espaces de noms de PHP quand celle-ci sera disponible et qu'il sera possible pour les développeurs de l'utiliser dans leurs applications.

Regardez les noms de classes dans les librairies standard et extras pour avoir des exemples de cette convention de nommage. IMPORTANT : le code qui opère avec le Framework mais qui n'en fait par partie, c'est-à-dire le code écrit par un utilisateur et pas Zend ou une des entreprises partenaires, ne doivent jamais commencer par "Zend_".

Abstract Classes

In general, abstract classes follow the same conventions as classes, with one additional rule: abstract class names must end in the term, "Abstract", and that term must not be preceded by an underscore. As an example, Zend_Controller_Plugin_Abstract is considered an invalid name, but Zend_Controller_PluginAbstract or Zend_Controller_Plugin_PluginAbstract would be valid names.

Note: This naming convention is new with version 1.9.0 of Zend Framework. Classes that pre-date that version may not follow this rule, but will be renamed in the future in order to comply.
The rationale for the change is due to namespace usage. As we look towards Zend Framework 2.0 and usage of PHP 5.3, we will be using namespaces. The easiest way to automate conversion to namespaces is to simply convert underscores to the namespace separator -- but under the old naming conventions, this leaves the classname as simply "Abstract" or "Interface" -- both of which are reserved keywords in PHP. If we prepend the (sub)component name to the classname, we can avoid these issues.
To illustrate the situation, consider converting the class Zend_Controller_Request_Abstract to use namespaces:

  1. namespace Zend\Controller\Request;
  2.  
  3. abstract class Abstract
  4. {
  5.     // ...
  6. }
Clearly, this will not work. Under the new naming conventions, however, this would become:
  1. namespace Zend\Controller\Request;
  2.  
  3. abstract class RequestAbstract
  4. {
  5.     // ...
  6. }
We still retain the semantics and namespace separation, while omitting the keyword issues; simultaneously, it better describes the abstract class.

Interfaces

In general, interfaces follow the same conventions as classes, with one additional rule: interface names may optionally end in the term, "Interface", but that term must not be preceded by an underscore. As an example, Zend_Controller_Plugin_Interface is considered an invalid name, but Zend_Controller_PluginInterface or Zend_Controller_Plugin_PluginInterface would be valid names.

While this rule is not required, it is strongly recommended, as it provides a good visual cue to developers as to which files contain interfaces rather than classes.

Note: This naming convention is new with version 1.9.0 of Zend Framework. Classes that pre-date that version may not follow this rule, but will be renamed in the future in order to comply. See the previous section for more information on the rationale for this change.

Noms de fichiers

Pour tous les autres fichiers, seuls des caractères alphanumériques, tirets bas et tirets demi-cadratin ("-") sont autorisés. Les espaces et les caractères spéciaux sont interdits.

Tout fichier contenant du code PHP doit se terminer par l'extension ".php". Ces exemples montrent des noms de fichiers acceptables pour contenir les noms de classes issus des exemples ci-dessus :

  1. Zend/Db.php
  2.  
  3. Zend/Controller/Front.php
  4.  
  5. Zend/View/Helper/FormRadio.php
Les noms de fichiers doivent correspondre aux noms des classes décris ci-dessus.

Fonctions et méthodes

Les noms de fonctions ne peuvent contenir que des caractères alphanumériques. Les tirets bas ("_") ne sont pas permis. Les nombres sont autorisés mais déconseillés.

Les noms de fonctions doivent toujours commencer avec une lettre en minuscule. Quand un nom de fonction est composé de plus d'un seul mot, la première lettre de chaque mot doit être mise en majuscule. C'est ce que l'on appelle communément la "notationCamel".

La clarté est conseillée. Le nom des fonctions devrait être aussi explicite que possible, c'est un gage de compréhension du code.

Voici des exemples de noms acceptables pour des fonctions :

filterInput()

getElementById()

widgetFactory()

Pour la programmation orientée objet, les accesseurs aux objets doivent toujours être préfixés par soit "get" soit "set". Lorsque vous utilisez des motifs de conception, comme le Singleton ou la Fabrique, le nom de la méthode doit contenir le nom du motif pour permettre une reconnaissance plus simple et plus rapide du motif.

Pour des méthodes d'objet qui sont déclarées avec la construction "private" ou "protected", le premier caractère du nom variable doit être un tiret bas simple ("_"). C'est la seule utilisation autorisé d'un tiret bas dans un nom de méthode. Les méthodes déclarées "public" ne devraient jamais commencer par un tiret bas.

Les fonctions à portée globale ("les fonctions flottantes") sont autorisées mais déconseillées. Il est recommandé de mettre ces fonctions dans des classes statiques.

Variables

Les noms de variables ne peuvent contenir que des caractères alphanumériques. Les tirets bas ne sont pas permis. Les nombres sont autorisés mais déconseillés.

Pour les variables membres de classe qui sont déclarées comme "private" ou "protected", le premier caractère du nom de la variable doit être un tiret bas simple ("_"). C'est la seule utilisation autorisé d'un tiret bas dans un nom de variable. Les variables membres "public" ne devraient jamais commencer par un tiret bas.

Tout comme les noms de fonction (cf la section 3.3 ci-dessus), les noms de variables doivent toujours commencer par un caractère en minuscule et suivre la convention de capitalisation de la "notationCamel".

La clarté est conseillée. Les variables devraient toujours être aussi claires que pratiques. Des noms de variables comme "$i" et "$n" sont déconseillé pour tout autre usage que les petites boucles. Si une boucle contient plus de 20 lignes de code, les variables pour les indices doivent avoir des noms descriptifs.

Constantes

Les constantes peuvent contenir des caractères alphanumériques et des tirets bas. Les nombres sont autorisés.

Les constantes doivent toujours être en majuscule, cependant les mots pouvant les composer doivent être séparés par des tiret-bats ("_").

Par exemple, EMBED_SUPPRESS_EMBED_EXCEPTION est permis mais EMBED_SUPPRESSEMBEDEXCEPTION ne l'est pas.

Les constantes doivent toujours être définies comme des membres d'une classe, en utilisant la construction "const". Définir des constantes globales avec "define" est permis mais déconseillé.

blog comments powered by Disqus