Snowcore’s блог

Одной из частей Zend Framework Certification является Zend Coding Standards. Рассмотрим, что нужно знать для успешной сдачи сертификации (материал из официального руководства по подготовке к сертификации).

Хорошие стандарты кодирования являются очень важным аспектом в разработке любого проекта.
Особенно, если над одним проектом трудятся несколько разработчиков.
Наличие стандартов кодирования помогает удостовериться, что код имеет высокое качество,
мало багов и его легко поддерживать.

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

• Никогда не используйте закрывающий тег “?>” для файлов, которые содержат только PHP код -
  это предотвращает от лишних пробелов и спецсимволов при выводе
• Отступ должен - 4 пробела, не используйте символ табуляции
• Максимальная длина строки - 120 символов, но старайтесь не превышать количества
  в 80 символов для понятности
• Строки должны заканчиваться символом перехода на новую строку (Unix), но не символом возврата каретки или комбинацей последнего с первым

Правила именования

Имена классов

• Имя класса должно быть привязано к его расположению в директориях (фактически имя класса - путь к файлу класса)
• Содержат только буквенно-цифровые символы. Цифры не одобряются. Знак нижнего подчеркивания используется только в качестве разделителя пути к файлу класса (например: Zend/Db/Table.php привязан к Zend_Db_Table)
• Имена, содержащие несколько слов: в общем случае, каждое слово содержит большую первую букву, остальные - в нижнем регистре (например: Zend_Pdf). Но есть исключения, когда слово представляет собой сокращение или какое-либо нестандартное слово (например: Zend_XmlRpc)
• Классы, созданные разработчиками ZF или его партнерами, должны начинаться на “Zend_” и обязаны быть расположены в иерархии папки Zend/ и с другой стороны класс, написанный не разработчиками ZF никогда не может начинаться на “Zend_”

Интерфейсы

Интерфейсы должны следовать таким же правилам, как и классы, и заканчиваться словом “Interface”
(например: Zend_Log_Adapter_Interface)

Имена файлов

• Для всех файлов разрешаются буквенно-цифровые символы, символ подчеркивания и дефис. Пробелы запрещены
• Любой файл, который содержит любой PHP код, должен иметь расширение “.php”, за исключением View скриптов

Имена функций

• Могут содержать только буквенно-цифровые символы. Символ подчеркивания не разрешается.
  Цифры не желательны
• Имена, состоящие из нескольких слов: camelCase стиль
• Функция должна иметь осмысленное имя для улучшения понимания кода (ну это и так понятно
• Аксессоры для объектов должны начинаться с “get” или “set” (ООП)
• (Примечание: не рекомендуется использование функций в глобальной области видимости. В таком случае сделайте эти функции методами статического класса)

Имена методов

• Всегда начинаются с буквы в нижнем регистре
• Должны содержать имя паттерна, если он применяется
• private и protected методы должны начинаться с символа нижнего подчеркивания
  (единственный случай, когда символ подчеркивания разрешен в имени метода) - хотя, сами Zendовцы не всегда придерживаются данного пункта

Имена переменных

• Также как и функции могут содержать только буквенно-цифровые символы. Символ подчеркивания не разрешается. Цифры не желательны
• Всегда начинаются с буквы в нижнем регистре, camelCase
• private и protected переменные начинаются с подчеркивания

Именование констант

• Могут содержать буквенно-цифровые символы и знаки подчеркивания
• Используются буквы в верхнем регистре
• Имена, состоящие из нескольких слов: каждое слово отделяется символом подчеркивания
• Должны быть определены как члены класса при помощи конструкции “const”

Стиль кодирования

Установка границ PHP кода

• PHP код должен быть разграничен тегами <?php и ?>
• Короткая запись тегов не разрешена (<? и ?>)

Строки - литералы

• Если строка является литералом (не содержит никаких подстановок переменных), то она определяется в одиночных кавычках (например: $str = ‘Пример строки-литерала’)
• В случае, если строка содержит апостроф, она может быть заключена в двойные кавычки. Это особенно одобряется для написания SQL запросов

Строки - конкатенация

• Строки могут быть сконкатенированы при помощи оператора “.”, при этом должен присутствовать пробел перед и после оператора
• Для более удобного восприятия длинные строки можно разбивать на несколько, при этом оператор конкатенации ставится в начале строки, на уровне знака присваивания:

$sql = “SELECT `id`, `name` FROM `people` “
     . “WHERE `name` = ‘Inga’ “
     . “ORDER BY `name` ASC”;

Массивы с цифровыми индексами

• Отрицательные значения не разрешены для использования в качестве индексов
• Могут начинаться с положительного индекса (больше нуля), но такое не одобряется. Лучше использовать 0 для начала индекса массива
• Для массивов, которые определяются при помощи функции array в несколько строк каждая следующая строка должна начинаться на уровне первого заданного значения в массиве

Ассоциативные массивы

• Если ассоциативный массив определяется при помощи функции array, то каждое новое значение должно быть записано с новой строки. Кроме того задаваемые значения должны находиться на одном уровне

$sampleArray = array(‘firstKey’  => ‘firstValue’,
                     ’secondKey’ => ’secondValue’);

Обявление класса

• Открывающая фигурная скобка ставится на следующей строке после имени класса (”one true brace” форма)
• Код класса должен иметь отступ в 4 пробела, без табуляций (зачем это снова напоминать?
• В одном файле - только один класс, не больше
• Добавление дополнительного кода в файл класса не рекомендуется. Если же данная ситуация имеет место, то класс и дополнительный код разделяются двумя пустыми строками

Свойства класса

• Именование свойств класса аналогично именованию обычных переменных (см. выше)
• Свойства класса определяются в самом верху тела класса (до методов)
• Объявление свойств класса осуществляется при помощи спецификаторов доступа private, protected или public (старая конструкция var запрещена)
• Доступ к свойствам класса на прямую, указав для них спецификатор public не одобряется. Пользуйтесь методами аксессорами (get/set)

Методы класса

• Именование методов аналогично правилам для функций
• Методы объявляются при помощи спецификаторов доступа private, protected или public
• Открывающая фигурная скобка пишется с новой строки, после имени метода. Между именем функции и открывающей круглой скобкой никаких пробелов
• Функции в глобальной области видимости сильно не одобряются
• Передача по ссылке разрешена только в объявлении функции
• Аргументы, которые передаются в функцию разделяются запятыми с пробелом

Операторы управления - if/else

• Управляющие операторы if/else должны иметь пробел перед открывающей круглой скобкой (условие), а также пробел после закрывающей круглой скобки
• Для условия внутри скобок операторы отделяются пробелами. Использование круглых скобок для группировки множественных условий одобряется
• Открывающая фигурная скобка пишется на строке, где написано условие. Закрывающая фигурная скобка пишется на отдельной строке. Код внутри фигурных скобок имеет отступ в 4 пробела (а они опять о том же

if ($someValue > 0) {
    $checked = true;
} else {
    $newValue = 7;
}

Switch

• Также как и для if - пробелы вокруг круглых скобок
• Все операторы switch должны иметь default case

switch ($key) {
    case KEY_UP:
        $obj->moveUp();
        break;
    case KEY_DOWN:
        $obj->moveDown();
        break;
    default:
}

Внутритекстовая документация - формат документации

• Все блоки документации (”docblocks”) должны быть совместимы с форматом phpDocumentor
• Все файлы с исходным кодом, написанные для Zend Framework, или которые взаимодействуют с фреймворком, должны содержать блок документации уровня файла (”file-level” docblock) в верхней части каждого файла. А также блок документации уровня класса(”class-level” docblock)

Внутритекстовая документация - файлы

• Каждый файл, содержащий PHP код должен иметь блок документации в формате phpDocumentor. Минимальный блок должен содержать следующее:

/**
 * Краткое описание для файла
 *
 * Длинное описание для файла (если есть)...
 *
 * LICENSE: информация о лицензии
 *
 * @copyright 2009 Zend Technologies
 * @license    http://www.zend.com/license/3_0.txt    PHP License 3.0
 * @version    $Id:$
 * @link         http://dev.zend.com/package/PackageName
 * @since      File available since Release 1.2.0
 *
 */

Внутритекстовая документация - классы

• Правила как и для файлов. Минимальный набор phpDocumentor тегов: Descriptions, @copyright, @license, @version, @link, @since, @deprecated

Внутритекстовая документация - функции

• Каждая функция и методы объектов должны иметь блок документации. Он должен содержать описание функции, все аргументы и все возможные возвращаемые значения
• Не обязательно использовать “@access” тег
• Для функций и методов, которые могут выбрасывать исключения лучше использовать @throws тег

Продолжаю свою подготовку к Zend exam. Zend Certification Study Guide (могу поделиться, кому нужно :), текущая тема - XML and Web Services.

PHP 5 предоставляет отличные средства для работы с XML документами. Одной из этих библиотек является SimpleXML.
Все объекты, созданные SimpleXML, являются экземплярами класса SimpleXMLElement. Рассмотрим на примере загрузку XML документа. У нас есть XML файл с информацией о продуктах в магазине следующего содержания (store.xml):

<?xml version=”1.0″ encoding=“UTF-8″ ?>
<store>
    <sku id=“7705“>
        <name>iPod classic</name>
        <price>330</price>
        <ean>0002520190555</ean>
    </sku>
    <sku id=“1139“>
        <name>ASUS A626</name>
        <price>310</price>
        <ean>0502770290391</ean>
    </sku>
    <sku id=“783“>
        <name>Sony iBook</name>
        <price>300</price>
        <ean>4506790441392</ean>
    </sku>
</store>

Загрузить XML документ можно несколькими способами. Первый способ предполагает использование функций simplexml_load_string и simplexml_load_file, которые возвращают объект SimpleXMLElement.

<?php
$xmlstr = file_get_contents(’store.xml’);
$store = simplexml_load_string($xmlstr);
?>

<?php
$store = simplexml_load_file(’store.xml’);
?>

Второй способ - использование конструктора объекта SimpleXMLElement.

<?php
$xmlstr = file_get_contents(’store.xml’);
$store = new SimpleXMLElement($xmlstr);
?>

<?php
$store = new SimpleXMLElement(’store.xml’, NULL, true);
?>

Пожалуй, самым интересным является последний способ. Загрузка XML через конструктор позволяет задать некоторые опции (второй параметр конструктора): все эти флаги начинаются на “LIBXML_”. При их помощи можно убрать пустые элементы (LIBXML_NOBLANKS), заменить entities (LIBXML_NOENT), отключить вывод ошибок и предупреждений (LIBXML_NOERROR), проверить загружаемый документ на валидность, используя DTD схему (LIBXML_DTDVALID) - подробное описание можно найти в мануале - глава “LXXVI. libxml Functions”.

После загрузки XML документа мы можем получить доступ к его элементам. Все элементы конвертируются в свойства объекта SimpleXMLElement, все атрибуты - в ассоциативный массив (имена элементов и атрибутов регистрозависимые):

<?php
foreach($store->sku as $sku)
{
 echo $sku[‘id’]  .‘<br />’;
 echo $sku->name  .‘<br />’;
 echo $sku->price .‘<br />’;
 echo $sku->EAN   .‘<br />’;
}
?>

Кроме этого SimpleXML предоставляет средства, при помощи которых можно узнать список всех элементов и атрибутов (и их имена).

SimpleXMLElement::children()
SimpleXMLElement::attributes()
SimpleXMLElement::getName()

Таким образом можно вывести XML, не зная имен элементов и атрибутов.

SimpleXML также позволяет выполнять запросы XPath (метод SimpleXMLElement::xpath(xpath_expression)). Данный метод возвращает массив элементов SimpleXMLElement. Например, мы можем получить названия всех товаров:

<?php
$productNames = $store->xpath(‘/store/sku/name’);
?>

или массив id всех товаров:

<?php
$productIDs = $store->xpath(‘/store/sku/@id’);
?>

Следует отметить, что XPath всегда возвращает массив объектов SimpleXMLElement (даже если результатом запроса является один элемент).

Изменение XML документа

В ранних версиях php (до 5.1.3), у SimpleXML не было возможности добавлять элементы и атрибуты в XML документы. Можно было только изменять существующие значения, но единственным способом добавления новых элементов и атрибутов было экспортирование SimpleXML объекта в DOM (используя функцию dom_import_simplexml). Добавление производится при помощи DOM (методы объекта DomDocument->create_element, DomDocument->create_attribute и др.). После этого DOM документ экспортируют обратно в SimpleXML (simplexml_import_dom). Согласитесь, не очень удобно.
С версией php 5.1.3 у SimpleXML появилось два новых метода SimpleXMLElement::addChild() и SimpleXMLElement::addAttribute().
Эти методы принимают 3 параметра - имя элемента (атрибута), его значение и пространство имен (опционально).
Рассмотрим на примере добавление нового продукта в наш документ store.xml:

<?php
$filename = ’store.xml’;
$store = new SimpleXMLElement($filename, NULL, true);
   
$newSku = $store->addChild(’sku’);
$newSku->addChild(‘name’, ‘Macbook Pro’);
$newSku->addChild(‘price’, ‘2400′);
$newSku->addChild(‘ean’, ‘1103610290850′);
    
$store->asXML($filename);
?>

В последней сроке используется метод SimpleXMLElement->asXML([filename]). Данный метод возвращает XML строку на основе текущего SimpleXMLElement, если определен параметр filename - то XML строка сохраняется в файл.

С XML можно работать при помощи DOM, но это будет рассмотрено уже в следующей статье.