Креатив
Верный ход
Качество
Надёжность

phpDocumentoris инструмент документации, который позволяет нам легко создавать документацию из исходного кода PHP. Документация извлекается из источника и из специальных комментариев в источнике; эти комментарии очень похожи на те, что используются JavaDoc.

Этот пример демонстрирует, как мы могли бы задокументировать простую функцию:

/**
 * Adds two integers together
 *
 * @param int $value1 Base value
 * @param int $value2 Value to add
 * @return int Resultant vaue
*/
function addition($value1, $value2)
{
    return ((int)$value1 + (int)$value2)
}

Многострочный комментарий обозначает DocBlock, заметьте, что он использует двойную звездочку в запуске. Первая строка - общее описание функции, это описание может охватить больше чем одну строку. теги @param и @returnare.

Тег @param используется для определения параметра в формате (имя не обязательно):

@param type [$name] description

Тег @return используется, чтобы определить возвращаемое значение в формате:

@return type description

Таким образом, наш начальный пример говорит нам, что у функции addition() есть два целочисленных параметра, названные этим, это добавит togther и возвратит результирующее целочисленное значение.

Когда мы документируем сложные функции, мы могли бы обеспечить два описания, подробное описание и краткое описание. Этот пример демонстрирует, как мы делаем это:

/**
 * Does some complex processing
 *
 * A verbose description of the function that spans more than
 * one line
 *
 * @param int $value1 Base value
 * @param int $value2 Value to add
 * @return int Resultant vaue
*/
function someComplexFunction($value1, $value2)
{
// does some complex processing
}

Функции не единственные элементы, которые могут быть задокументированы. Элементы, которые мы можем задокументировать, включают:

  • методы класса
  • переменные класса
  • классы
  • define()
  • файлы
  • объявления функции
  • глобальные переменные (требует использования тега @global)
  • include() / include_once()
  • require() / require_once()

Этот список определяет некоторые общие теги, с которыми мы, вероятно, встретимся:

  • @access private|protected|public
  • @author name
  • @param type [$name] description
  • @return type description
  • @static

 DocBlocks просто считать, когда они выведены на экран в коде, но что еще более важно мы можем автоматически создать документацию из исходного кода. Для получения дополнительной информации об использовании phpDocumentor обратитесь к http://www.phpdoc.org/.

 Вернуться к оглавлению

Использование стандартного формата делает код более удобным для чтения и позволяет другим разработчикам редактировать код более легко. Joomla! использует стандарты кодирования PEAR. Полное руководство по стандартам кодирования PEAR доступно в http://pear.php.net/manual/en/standards.php.

Остановимся ниже на более общих правил:

  • Отступы - четыре пробела:
{
    // four space before me!
  • Управляющие структуры имеют один пробел между именем и первой скобкой:
if (true) {
  • Используйте фигурные скобки, даже если они не являются обязательными.
  • Функции и методы именуются стандартом camelCase со строчным первым символом.
  • У функций и объявлений метода нет пробелов между именем и первой круглой скобкой. Списки параметров не имеют пробелы на концах. Параметры разделены одним пробелом: foo($bar0, $bar1, $bar2);
  • Дополнительные параметры функций и методов должны быть в конце списка параметров.
  • Необязательные значения параметров, обозначеные знаком равенства, разделяются пробелами: function foo($bar0, $bar1, $bar2 = '')
  • Используйте теги phpDocumentor, чтобы прокомментировать код http://www.phpdoc.org/.
  • Предпочитайте include_once() и require_once() вместо include() и require().
  • Используйте <?php ?>, отдавая им предпочтение всем другим разделителям блоков PHP.

 Вернуться к оглавлению

Главная сила Joomla! в встроенной многоязычной поддержке. Язык по умолчанию сконфигурирован в Менеджере языков и может быть переопределен предпочтениями зарегистрированного пользователя.

Статический класс JText - стандартный механизм, используемый для перевода строк. У JText есть три метода для перевода строк, _ (), sprintf (), и printf (). Метод, который вы будете, вероятно, использовать больше всего, _ (). Этот метод является самым основным; он переводит строку.

В этом примере мы выводим перевод "Monday" (если перевод не может быть найден для строки, возвращается исходная строка):

echo JText::_('Monday');

Метод JText::sprintf () сопоставим с функцией PHP sprintf (). Мы передаем одну строку, чтобы перевести и любое число дополнительных параметров, чтобы вставить в переведенную строку. Дополнительные параметры не будут переведены.

В этом примере, если перевод для "SAVED_ITEMS" - это "Сохранено %d элемента", возвращенное
значение будет "Сохранено 3 элемента".

$value = JText::sprintf('SAVED_ITEMS', 3);

Альтернативно мы можем использовать метод JText::printf (). Этот метод сопоставим с функцией PHP printf (). Этот метод возвращает длину результирующей строки и выводит перевод.

$length = JText::printf('SAVED_ITEMS', 3);

Если мы хотим создать какие-либо новые переводы для наших расширений, мы можем создать специальные INI файлы перевода. Более полное объяснение того, как создать файл перевода, доступно в Главе 7.

Вернуться к оглавлению

Для полной многоязычной поддержки, Joomla! использует набор символов Unicode и UTF-8 (Unicode Transformation Format-8) кодировку. Unicode - набор символов, который пытается включать все символы для каждого общего языка.

UTF-8 - кодировка Unicode без потерь, которая использует переменную символьную длину. Это делает его идеальным для использования Интернета, потому что это использует минимальное количество пропускной способности, но представляет весь набор символов Unicode.

При контакте с английскими символами UTF-8 использует те же кодировки в качестве ASCII и ANSII. У этого есть последствие; закодированные UTF-8 строки, которые используют эти символы, кажутся идентичными их ASCII и ANSII альтернативам. Приложения, которые не знают Unicode, следовательно, способны обрабатывать множество UTF-8 строк.

Одно из таких приложений, которые не знают Юникод, является PHP. Мы поэтому должны быть осторожными при управлении строками. PHP предполагает, что все символы составляют восемь битов (один байт), но поскольку закодированные символы UTF-8 могут быть более длинными, это может вызвать повреждение данных Unicode.

Есть модуль PHP, mbstring, который добавляет поддержку символов многобайтовых кодировок; к сожалению, не у всех систем PHP есть mbstring модуль. В Joomla! нам предоставлен статический класс JString; этот класс позволяет нам выполнять многие нормальные функции обработки строк с символами UTF-8.

Этот пример демонстрирует, как мы можем использовать JString, чтобы преобразовать строку в верхний регистр. Обратите внимание на то, что имя метода идентично функции PHP, которую мы обычно использовали бы:

$string = JString::strtoupper($string);

Следующая таблица описывает строковые функции PHP и соответствующие методы JString:

Функция PHP Метод JString Описание
strpos strpos Находит первое вхождение строки в строку.
substr substr Получает часть строки.
strtolower strtolower Преобразовывает строку в нижний регистр.
strtoupper strtoupper Преобразовывает строку в верхний регистр.
strlen strlen Подсчет длины строки.
str_ireplace str_ireplace Возвращает строку, в котором все вхождения подстроки (без учета регистра символов) заменены на другую подстроку.
str_split str_split Разделяет строку на массив.
strcasecmp strcasecmp Сравнивает строки.
strcspn strcspn Получает длину строки прежде, чем символы от других параметров будут найдены.
stristr stristr Находит первое вхождение строки в строку (без учета регистра).
strrev strrev Инвертирует строку.
strspn strspn Считает самый длинный сегмент строки, содержащей определенные символы.
substr_replace substr_replace Заменяет определенную часть строки.
ltrim ltrim Удаляет пробелы слева от строки.
rtrim rtrim Удаляет пробелы справа от строки.
trim trim Удаляет пробел из обоих концов строки.
ucfirst ucfirst Преобразовывает первый символ в верхний регистр.
ucwords ucwords Преобразовывает первый символ каждого слова к верхнему регистру.
  transcode Преобразует строку из одной кодировки в другую. Требуется модуль PHP Iconv.

Вернуться к оглавлению

Есть более чем 400 констант, многие из которых являются частью сторонних библиотек, хотя мы не должны знать их все. Одна константа, с которой мы быстро станем знакомыми, является _JEXEC; эта константа используется, чтобы гарантировать, что, когда файлы включаются, они включаются от действительной точки входа. Вы должны включать следующий код, или подобный, вверху ваших файлов PHP:

defined('_JEXEC') or die('Restricted access');

Константы, которые вы, вероятно, будете чаще всего использовать относятся к путям. Константа DS - символ, используемый операционной системой, чтобы разделить каталоги; это обычно - наклонная черта влево (\) или наклонная черта вправо (/). Эта таблица описывает различные константы пути; примеры, описанные в круглых скобках, предполагают, что система расположена в /joomla и что мы получаем доступ к системе от фронтэнда; фактические пути будут отличаться в зависимости от установки Joomla!:

Имя Описание
DS Разделитель каталога (/)
JPATH_ADMINISTRATOR Путь администратора (/joomla/administrator)
JPATH_BASE Путь к базовому каталогу (/Joomla)
JPATH_CACHE Путь кэша (/joomla/cache)
JPATH_COMPONENT Путь к компоненту (/joomla/components/com_example)
JPATH_COMPONENT_ADMINISTRATOR Путь к компоненту бэкэнда (/joomla/administrator/components/com_example)
JPATH_COMPONENT_SITE Путь к компоненту фронтэнда (/joomla/components/com_example)
JPATH_CONFIGURATION Путь конфигурации (/joomla)
JPATH_INSTALLATION Путь установки (/joomla/installation)
JPATH_LIBRARIES Путь библиотек (/joomla/libraries)
JPATH_PLUGINS Путь плагинов (/joomla/plugins)
JPATH_ROOT Путь к базовому каталогу фронтэнда (/joomla)
JPATH_SITE Путь к общедоступному каталогу (/joomla)
JPATH_THEMES Путь к шаблонам (/joomla/templates)

Четыре константы даты определяют различные форматы даты. Эти форматы разработаны, чтобы использоваться при отображении дат, используя класс JDate; полное описание класса JDate доступно в Главе 12. Значения формата варьируются в зависимости от локали языка, форматы по умолчанию используются, если они не будут определены в соответствующем файле языка локали (много язычную поддержку мы обсудим позже).

Имя Формат по умолчанию Пример
DATE_FORMAT_LC3 %A, %d %B %Y Sunday, 23 June 1912
DATE_FORMAT_LC2 %A, %d %B %Y %H:%M Sunday, 23 June 1912 00:00
DATE_FORMAT_LC3 %d %B %Y 23 June 1912
DATE_FORMAT_LC4 %d.%m.%y 23.06.12

Некоторые константы в Joomla! 1,5 устарели. Следующие константы включены для совместимости с прежними системами. Вы не должны использовать их в новых расширениях. Эти константы доступны, только если модуль унаследованной системы опубликован.

Устаревшая константа Описание
_ISO Набор символов
_VALID_MOS Используйте _JEXEC вместо этого
_MOS_MAMBO_INCLUDED Используйте _JEXEC вместо этого
_DATE_FORMAT_LC Используйте DATE_FORMAT_LC вместо этого
_DATE_FORMAT_LC2 Используйте DATE_FORMAT_LC2 вместо этого

Вернуться к оглавлению

Войти на сайт

Запомнить меня

Новости

  • Перевод Mastering Joomla! 1.5

    14.03.2013

    Продолжается перевод книги "Mastering Joomla! 1.5". На данный момент полностью переведено 2 главы. Полностью перевод книги...

    Подробнее...

  • Модернизация сайта

    28.05.2012

    Уважаемые посетители! Мы полностью модернизировали наш сайт и надеемся что сейчас им станет...

    Подробнее...