Главная / Zend Manual Core
Форматирование PHP-файлов

Соглашения по именованию

Классы

Zend Framework использует схему именования классов, в соответствии с которой имена классов напрямую указывают на директории, где они находятся. Корневой директорией стандартной библиотеки Zend Framework'а является директория "Zend/", а дополнительной - директория "ZendX/". Все классы Zend Framework расположены иерархически в этих корневых директориях.

Имена классов могут содержать только буквенно-числовые символы. Числа допустимы в именах классов, но не приветствуются. Символы нижнего подчеркивания допустимы в местах разделителей пути - имя файла "Zend/Db/Table.php" должно указывать на класс с именем "Zend_Db_Table".

Если имя класса состоит из более чем одного слова, то первая буква каждого слова должна быть заглавной. Последующие заглавные буквы недопустимы, например, имя класса "Zend_PDF" - недопустимо, в то время как "Zend_Pdf" - допустимо.

Эти соглашения определяют механизм псевдо-нэймспэйсов для Zend Framework. Zend Framework будет использовать функционал PHP нэймспэйсов, когда он станет доступен и применим для разработчиков для использования в их приложениях.

Смотри имена классов в стандартной и дополнительной библиотеках в качестве примера этой схемы именования.

Note: ВАЖНО: Код, который должен использоваться вместе с Zend Framework, но не являющийся частью стандартной либо дополнительной библиотек (тоесть код приложения или библиотеки, распространяемый не компанией Zend), не должен начинаться с префиксов "Zend_" или "ZendX_" .

Абстрактные классы

В основном, абстрактные классы следуют тем же соглашениям, что и классы, с одним дополнительным правилом: имена абстрактных классов должны заканчиваться словом "Abstract" и перед ним не должно быть нижнего подчеркивания. Как пример, Zend_Controller_Plugin_Abstract считается неправильным, в то время как Zend_Controller_PluginAbstract или Zend_Controller_Plugin_PluginAbstract - правильны.

Note: Эта схема именования появилась с версии 1.9.0 Zend Framework'a. Классы, предшествующие этой версии могут не следовать данному правилу, но в будущем будут переименованы для соответствия.
Логическое обоснование этому изменению связано с использованием нэймспэйсов. Планируя переход к Zend Framework 2.0 и использование PHP 5.3, мы готовимся использовать нэймспэйсы. Простейший способ автоматизировать переход к нэймспэйсам - это просто преобразовать нижнее подчеркивание в разделитель нэймспэйса, но в случае старой схемы именования это сделает итоговым именем классов просто "Abstract" или "Interface", которые являются зарезервированными ключевыми словами в PHP. Если же мы добавим имя (суб)компонента к имени класса, то сможем избежать этих проблем.
Для демонстрации ситуации, представьте преобразование класса Zend_Controller_Request_Abstract для использования нэймспэйсов:

  1. namespace Zend\Controller\Request;
  2.  
  3. abstract class Abstract
  4. {
  5.     // ...
  6. }
Очевидно, это не сработает. Но с новой схемой именования это будет выглядеть так:
  1. namespace Zend\Controller\Request;
  2.  
  3. abstract class RequestAbstract
  4. {
  5.     // ...
  6. }
Мы сохраняем семантику и разделением нэймспэйсами, в тоже время мы избегаем проблем с ключевыми словами. Так же, так лучше описывается абстрактный класс.

Интерфейсы

В основном, интерфейсы следуют тем же соглашениям, что и классы, с одним дополнительным правилом: имена интерфейсов должны заканчиваться словом "Interface" и перед ним не должно быть нижнего подчеркивания. Как пример, Zend_Controller_Plugin_Interface считается неправильным, в то время как Zend_Controller_PluginInterface или Zend_Controller_Plugin_PluginInterface - правильны.

Хотя это правило не считается обязательным, оно настоятельно рекомендуется, так как предоставляет разработчикам хороший визуальный ключ к пониманию, какие файлы содержат интерфейсы, а не классы.

Note: Эта схема именования появилась с версии 1.9.0 Zend Framework'a. Интерфейсы, предшествующие этой версии могут не следовать данному правилу, но в будущем будут переименованы для соответствия. Смотри предыдущую секцию для дополнительной информации по логическому обоснованию этого изменения

Имена файлов

Для файлов допустимы буквенно-числовые символы, символы нижнего подчеркивания и тире ("-"). Пробелы запрещены.

Любой файл содержащий PHP-код должен иметь расширение ".php", за исключением скриптов вида. Это примеры показывают допустимые имена файлов для классов из примеров в секции выше:

  1. Zend/Db.php
  2.  
  3. Zend/Controller/Front.php
  4.  
  5. Zend/View/Helper/FormRadio.php

Имена файлов отражаются на имена классов, как описано выше.

Функции и методы

Имена функций могут содержать буквенно-числовые символы. Символы нижнего подчеркивания не разрешены. Числа разрешены в именах функций, но не приветствуются.

Имена функций должны всегда начинаться с буквы в нижнем регистре. Когда имя функции состоит из более чем одного слова, первая буква каждого нового слова должна быть заглавной. Это обычно называется "верблюжьей(camelCase)" нотацией.

Многословность приветствуется. Имена функций должны быть настолько говорящими, насколько это практично для повышения понимаемости кода.

Это примеры допустимых имен функций:

  1. filterInput()
  2.  
  3. getElementById()
  4.  
  5. widgetFactory()

Для объектно-ориентированного программирования принято, чтобы методы доступа имели префикс "get" или "set". Когда используются шаблоны проектирования, такие, как "синглтон" или "фабрика", где возможно, имена методов должны содержать имя шаблона, чтобы можно было быстро узнать шаблон.

Для методов, объявленных с помощью префиксов области видимости "private" или "protected", первый символ имени должен быть нижним подчеркиванием. Это единственное допустимое применение нижнего подчеркивания в имени метода. Методы объявленные как "public" никогда не должны иметь нижнего подчеркивания в имени.

Функции в глобальной области видимости ("плавающие функции") допустимы, но не приветствуются. Рекомендуется обрамлять такие функции в статические классы.

Переменные

Имена переменных могут содержать буквенно-числовые символы. Символы нижнего подчеркивания не разрешены. Числа разрешены в именах переменных, но не приветствуются.

Для переменных - членов классов, определенных с помощью префиксов области видимости "private" или "protected", первый символ имени должен быть символом нижнего подчеркивания. Это единственное допустимое использование символа нижнего подчеркивания в имени. Переменные - члены классов определенные с помощью префикса области видимости "public" никогда не должны начинаться с символа нижнего подчеркивания.

Как и имена функций (смотри секцию 3.3), имена переменных должны начинаться с буквы в нижнем регистре и следовать "верблюжьей" нотации.

Многословность приветствуется. Имена переменных должны быть настолько говорящими, насколько это практично. Краткие имена переменных, такие как "$i" и "$n" не приветствуются нигде, кроме как в контексте маленьких циклов. Если цикл содержит более 20 строк кода, то переменные для индексов должны иметь более говорящие имена.

Константы

Константы могут содержать буквенно-числовые символы, символы нижнего подчеркивания. Числа в именах констант разрешены.

Имена констант должны быть в верхнем регистре, слова в имени должны быть разделены нижним подчеркиванием.

Например, EMBED_SUPPRESS_EMBED_EXCEPTION разрешены, а EMBED_SUPPRESSEMBEDEXCEPTION - нет.

Константы должны быть определены как члены классов с использованием ключевого слова "const". Определение констант в глобальной области видимости с помощью "define" допустимо, но не рекомендуется.


Форматирование PHP-файлов