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

Условно все программы такого типа можно разделить на два класса: с web интерфейсом и без него (десктопные).

Наиболее известным представителем первого класса является phpMyAdmin. Так или иначе, с ним сталкивались практически все web разработчики. Дело в том, что web приложения для администрирования баз (и не только) очень популярны на shared хостингах, т.к. для работы с базой не нужен SSH доступ и довольно легко устанавливать различные ограничения. С точки зрения пользователей тоже есть положительные моменты:

• не нужно ничего устанавливать и настраивать на своём компьютере;
• получить доступ к базе можно с любого устройства, подключённого к интернет;
• в phpMyAdmin реализованы практически все необходимые возможности (просмотр и редактирование данных, поиск, выполнение SQL запросов, экспорт, импорт и т.д.).

Но, как только вы переезжаете на VPS или выделенный сервер, ситуация меняется. И проблемы в использовании web приложений становятся заметнее:

1. Ограничения времени выполнения и ресурсов скриптов создают проблемы при экспорте/импорте данных. Т.е. для экспорта/импорта больших баз придётся использовать другие инструменты.
2. Т.к. приложение доступно из интернета, нужно следить за его безопасностью. В случае VPS или выделенного сервера это полностью ваша проблема, а не хостера.
3. Не получится работать одновременно с несколькими базами данных, расположенными на разных серверах.

Поэтому в таких случаях использовать десктопные приложения гораздо удобнее.

Подключение к базе данных

Тут очень важно, чтобы была возможность подключиться через SSH. Если её нет, то должны быть другие, очень веские причины для использования такого MySQL менеджера. Конечно, вы можете открыть доступ к MySQL серверу снаружи, но при этом придётся обеспечивать его безопасность (например, создавать списки IP адресов, с которых можно к нему подключаться), а это дополнительная работа.

В dbForge подключение через SSH реализовано, нужные настройки находятся на вкладке «Безопасность».

 

 

Примечание. Скриншоты для этой статьи я сделал с локального сервера, установленного в VirtualBox, поэтому использована аутентификация с помощью пароля. Для рабочих серверов лучше использовать ключи и запретить вход под root’ом.

Основные возможности

Под ними я понимаю: просмотр, изменение, удаление и добавление данных, а также поиск. Т.к. CRUD операции реализованы практически одинаково во всех подобных программах, я просто покажу скриншот из dbForge. Вы выбираете нужную таблицу, и программа покажет информацию о таблице и первые 1000 строк данных. Естественно, вы можете использовать постраничную навигацию, редактировать данные, структуру таблицы, создавать индексы и т.п.

 

Для создания правил фильтрации данных предусмотрен «Конструктор фильтра». Открывается из меню «Данные» -> «Фильтр» -> «Условие...». Конструктор сделан достаточно удобно, есть календарь для ввода дат, выпадающие списки с перечнем полей таблицы и условиями сравнения.

 

В целом, интерфейс достаточно приятный. Но если вы раньше пользовались другими MySQL клиентами, то нужно будет привыкнуть.

Переходим к более «продвинутым» возможностям.

Создание запросов

В dbForge Studio реализовано два режима создания запросов:

1. редактор SQL;
2. дизайнер запросов.

Для того чтобы создавать запросы, вы должны хотя бы на базовом уровне знать SQL. В противном случае никакие инструменты вам не помогут. Инструменты могут только сделать работу комфортнее. Например, выделить цветом ключевые слова, добавить отступы и алиасы для таблиц, показать варианты автодополнения. Кстати, автодополнение сделали в dbForge очень удобно (см. скриншот), они сгруппировали списки полей по таблицам.

 

Дизайнер запросов на первый взгляд очень напоминает аналогичный инструмент в Access. Но всё-таки он ближе к SQL режиму, чем реализация в Access. Это хорошо видно по представлению информации на вкладке «Соединения» (я специально показал её на скриншоте). Формат, в котором представлена связь, практически совпадает с записью в SQL режиме.

 

Также есть возможность переключиться в SQL режим и обратно.

Профилирование запросов

Ещё одна удобная функция. Вы указываете запрос, а программа вам показывает вывод

EXPLAIN ...request...
SHOW PROFILE FOR QUERY ...

и

SHOW SESSION STATUS;

Всю эту информацию можно получить с помощью обычных SQL запросов, но dbForge позволяет выбрать несколько результатов и сравнить их. Данные выводятся в соседних колонках (показано на скриншоте), которые можно отсортировать по возрастанию или убыванию.

 

Создание диаграмм

Этот режим полезен для разработки структуры MySQL баз. Вы можете либо добавлять новые таблицы на диаграмму, создавать поля и устанавливать связи, либо сформировать диаграмму из существующих таблиц. Последний вариант удобно использовать для подготовки документации и статей для блога

 

Обратите внимание. При создании связей между таблицами на диаграмме у вас есть возможность получить запрос, который эту связь создаёт. Для этого нажмите кнопку «Скрипт изменений» (показана на скриншоте).

 

Для данного примера вы получите следующий скрипт:

USE workshop;

--
-- Изменить таблицу "table2"
--
ALTER TABLE table2
  ADD CONSTRAINT FK_table2_table1_id FOREIGN KEY (t_id)
    REFERENCES table1(id) ON DELETE NO ACTION ON UPDATE NO ACTION;

Сравнение баз данных

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

Результаты сравнения в dbForge Studio выглядят следующим образом

 

Как видите, в данном случае в БД, которая расположена справа, отсутствует таблица wp_td_terms и используется движок MYISAM вместо INNODB.

Также можно сравнить и содержимое баз.

Резервное копирование и восстановление данных

Ради эксперимента я создал копию базы размером около 800 МБ. Процесс прошел довольно быстро и без ошибок. При создании копии можно указать множество настроек, например, заблокировать таблицы и т.п.

 

При восстановлении нужно только правильно указать кодировку дампа.

Также есть возможность экспорта данных в разные форматы, вроде CSV и XML.

Создание отчётов

Это ещё одна возможность, которая сильно напомнила Access. Отчеты создаются с помощью мастера, который предлагает либо использовать существующие таблицы, либо создать запрос. Также предлагается выбрать вариант оформления, группировку и сортировку. После завершения работы мастера открывается дизайнер отчета в котором можно сделать окончательные настройки.

 

Результат можно распечатать или экспортировать в один из поддерживаемых форматов (HTML, XLS, JPEG, PDF).

 

Заключение

В этом обзоре я останавливался в основном на возможностях, которые показались мне наиболее интересными, и доступны в версии для некоммерческого использования. А вообще dbForge распространяется в трёх редакциях: Express, Standard и Professional, которые отличаются ценой и набором поддерживаемых функций. Сравнить их можно здесь. При этом использование любой из версий упрощает MySQL разработку.

Подарок

Специально для вас компания Devart предоставлет 20% скидку на продукты линейки MySQL версий Standart и Professional.
Для того, чтобы ей воспользоваться, при заказе товара введите промо код

simplecoding

Промо код действителен до 20.11.2014.

Успехов!

The post dbForge Studio — менеджер MySQL баз данных first appeared on SimpleCoding.org.

Но, прежде всего, несколько замечаний о самом Logentries.

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

В бесплатном варианте Logentries предоставляет возможность отправить до 5ГБ логов в месяц и при этом время хранения составляет 7 дней. В платном варианте эти лимиты увеличиваются, а также появляются дополнительные функции (подробнее).

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

Способы отправки логов

Logentries поддерживает несколько методов передачи данных:

1) С помощью специальной программы (агента). Это один из самых простых вариантов с точки зрения настройки. Вы только устанавливаете программу и выбираете логи, которые нужно отправлять в Logentries. Но устанавливать на «боевом» сервере сторонний софт не желательно и, кроме того, нужно будет следить за его обновлениями.

2) С помощью syslog (rsyslog). Эта утилита установлена в большинстве linux-дистрибутивов. Тут вы только настраиваете отправку нужных логов.

3) С помощью библиотек. В этом случае вы сможете отправлять сообщения прямо из приложения, без сохранения в файловой системе. Библиотеки написаны для большинства распространённых языков, в том числе Java, PHP, Python, JavaScript/HTML5 и других.

Первые два варианта можно подойдут, если вы используете VPS или выделенный сервер. Т.е. у вас должен быть доступ к консоли, иначе вы просто не сможете сделать нужных настроек. Правда, сейчас у многих PaaS сервисов (например, Heroku, AppFog, CloudControl) уже реализована поддержка Logentries, и вам нужно её просто активировать в админке.

В общем, с серьёзными ограничениями вы столкнётесь только на shared хостинге. В этом случае у вас будет возможность отправлять сообщения из приложения, логи веб сервера отправить не получится.

Примечание. Подробнее почитать об отправке данных можно в статье Log Management 101 – Where Do Logs Come From?.

Рассмотрим подробно второй вариант – отправку с помощью rsyslog

Примеры настройки показаны для Debian 7, но для большинства linux дистрибутивов подход будет аналогичным.

Шаг 1. Регистрируемся в Logentries.

Это бесплатно

Шаг 2. Создаём логи.

 

Здесь я имею в виду, что нужно нажать кнопку «Add new log» в админке Logentries, а не создать log файл на сервере. Обычно каждому log файлу соответствует отдельный лог в админке, хотя можно данные из нескольких log файлов «слить» в один лог.

Шаг 3. Выбираем syslog

 

После этого появится инструкция по настройке rsyslog на вашем сервере.

 

В ней предлагается внести правки в /etc/rsyslog.conf, но, на мой взгляд, удобнее создать файл в директории /etc/rsyslog.d/. Я обычно создаю отдельные конфигурационные файлы под каждый лог, в этом случае они не содержат много настроек и с ними удобно работать.

Шаг 4. Создаём конфигурационный файл для лога Nginx.

sudo touch /etc/rsyslog.d/nginx_access.conf

и копируем в него настройки из инструкции. Обратите внимание, эти настройки уже содежрат token нового лога.

token определяет в какой лог будут попадать сообщения от вашего сервера. Т.е. если вы по каким-то причинам хотите чтобы данные из нескольких логов попадали в один лог Logentries, то нужно просто указать для этих файлов один и тот же token.

Шаг 5. Проверяем передачу данных

Для этого перезапускаем rsyslog и отправляем тестовое сообщение

sudo service rsyslog restart
logger -t test Hello there Logentries

Через некоторое время (обычно меньше минуты) страница (в админке Logentries) обновиться и вы попадёте на страницу просмотра логов.
Последним сообщением в логе будет «test: Hello there Logentries».

Теперь мы убедились, что rsyslog передаёт сообщения Logentries.

Примечание. Logentries автоматически формирует названия для логов. Их можно изменить на вкладке Settings.

 

Шаг 6. Выбираем лог файл.

В файле /etc/rsyslog.conf (перед подключением rsyslog.d) добавляем строку:

$Modload imfile

И заменяем содержимое /etc/rsyslog.conf/nginx_access.conf

$template NginxTemplate,"LOGENTRIES_ACCESS_LOG_TOKEN %HOSTNAME% %syslogtag%%msg%\n"
$InputFileName /var/log/nginx/access.log
$InputFileTag
$InputFileStateFile stat-nginx-access
$InputFileSeverity info
$InputFileFacility local4
$InputFilePollInterval 10
$InputRunFileMonitor
local4.* @@data.logentries.com:10000;NginxTemplate

Убедитесь, что лог файл находится именно в директории /var/log/nginx/.

Вместо LOGENTRIES_ACCESS_LOG_TOKEN нужно указать реальный token. Его всегда можно посмотреть в админке Logentries.

 

Перезапускаем rsyslog

sudo service rsyslog restart

И через некоторое время у вас должны появиться данные в админке Logentries.

Шаг 7. Подключаем error.log

Повторяем шаги 2-6. Только теперь в создаём конфиг файл для лога с ошибками /etc/rsyslog.conf/nginx_error.conf

$template NginxError,"LOGENTRIES_ERROR_LOG_TOKEN %HOSTNAME% %syslogtag%%msg%\n"
$InputFileName /var/log/nginx/error.log
$InputFileTag
$InputFileStateFile stat-nginx-error
$InputFileSeverity info
$InputFileFacility local6
$InputFilePollInterval 1
$InputRunFileMonitor
local6.* @@data.logentries.com:10000;NginxError

Не забываем перезапустить rsyslog

sudo service rsyslog restart

Примечание. Если у вас возникли проблемы с настройкой rsyslog, я очень рекомендую посмотреть официальную документацию. Возможно, в будущем разработчики Logentries сделают какие-то изменения.

Заключение

Как видите, использование rsyslog не зависит от типа логов, которые вы передаёте. Т.е. вы спокойно можете заменить логи nginx из данного примера на логи apache. Главное правильно укажите размещение файлов и token’ы.

Happy logging

The post Logentries, Debian и логи Nginx first appeared on SimpleCoding.org.

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

Для того, чтобы добавить правило нужно:

1) Вызвать функцию add_rewrite_rule и передать ей регулярное выражение для разбора параметров.

function add_my_rules() {
    add_rewrite_rule( 'my_param/(\d+)?$', 'index.php?my_param=$matches[1]', 'top' );
}

2) Добавить новую переменную в объект WP_Query. Для этого используется фильтр query_vars.

add_filter( 'query_vars', 'add_query_vars' );
function add_query_vars( $vars ) {
    $vars[] = 'my_param';
    return $vars;
}

В первом параметре функция add_query_vars получит массив со всеми переменными WP_Query и мы сможем добавить в этот массив имя нашего параметра (my_param).

После этого можно получить значение параметра с помощью get_query_var(). Например,

$my_param_value = get_query_var('my_param');
...

Т.е. мы сможем использовать полученное значение, например, при выборке постов (в обработчике события pre_get_posts) или прямо в шаблонах темы. Тут возможности ограничены только вашей фантазией и задачами.

Остаётся только один вопрос: «Когда вызывать add_my_rules?»

Если правила добавляются в плагине, то логично для этих целей использовать события активации и деактивации. Т.е. сделать что-то вроде:

register_activation_hook( __FILE__, 'my_plugin_setup' );
function my_plugin_setup() {
    add_my_rules();
    flush_rewrite_rules();
}

register_deactivation_hook( __FILE__, 'deactivate' );
function deactivate() {
    flush_rewrite_rules();
}

В результате всё будет работать, т.к. при активации плагина правила добавляются, а при деактивации — происходит перезапись правил, без вызова функции add_rewrite_rules, т.е. без новых правил.

Проблема в том, что любой вызов flush_rewrite_rules() будет отключать новые правила. Т.е., например, при входе на страницу настроек постоянных ссылок правила будут отключены.

Обратите внимание. Для повышения производительности WP кэширует правила. Поэтому для того, чтобы перезаписать правила обязательно нужно вызвать flush_rewrite_rules (сбрасывает кэш). При этом, flush_rewrite_rules может вызываться самим движком (например, при сохранении ЧПУ) и может вызываться другими плагинами.

Решение.

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

Изменим наш код следующим образом.

Убираем вызов add_my_rules из register_activation_hook и добавляем обработчик события generate_rewrite_rules

add_action( 'generate_rewrite_rules', 'add_my_rules' );

Теперь правила остаются активными при вызовах flush_rewrite_rules, но они не удаляются при деактивации плагина. Происходит это потому, что при каждом вызове flush_rewrite_rules, не зависимо от того кто этот вызов сделал, происходит добавление наших правил.

Исправить проблему можно следующим образом.

Добавляем переменную

$is_deactivating = false;

устанавливаем её равной true при вызове deactivate

function deactivate() {
    $this->is_deactivating = true;
    flush_rewrite_rules();
}

и добавляем проверку при установке правила

function add_my_rules() {
    if ($this->is_deactivating === false) {
        add_rewrite_rule( 'my_param/(\d+)?$', 'index.php?my_param=$matches[1]', 'top' );
    }
}

Теперь при деактивации плагина будет проверяться значение переменной $is_deactivating и если оно равно true, то наши правила добавляться не будут.

Как видите, решение довольно простое, но при условии, что вы понимаете, как работает движок. Помнить обо всех нюансах очень сложно, но есть общее правило – если вы используете встроенные возможности WP, в первую очередь ищите соответствующие события.

Успехов!

The post Управление созданием правил перезаписи URL в плагинах WordPress first appeared on SimpleCoding.org.

Рассмотрим в качестве примера работу с метаданными в WordPress. Допустим, у каждой статьи на сайте есть несколько атрибутов, например, рейтинг и количество проголосовавших посетителей. Нам нужно создать фильтры, которые позволят выбирать статьи по этим параметрам, т.е. что-то вроде рейтинг – от 3 до 5 и количество голосов – больше 100.

Такую информацию удобно хранить в таблице метаданных wp_postmeta. Это логичное решение, т.к. таблица wp_postmeta связана с wp_posts отношением «многие-к-одному». И мы можем для любой статьи хранить практически не ограниченное количество метаданных. Кроме того, для разных статей можно сохранять собственные наборы полей и это не приведёт к появлению пустых (NULL) значений в таблицах.

Примечание. Такой способ хранения данных очень распространён и используется в большинстве CMS. WordPress в качестве примера я взял только потому, что он широко распространён. Описанные ниже проблемы могут касаться любой системы.

Проблема возникает при поиске по значениям нескольких метаполей стандартными средствами WP. Такие запросы могут выполняться очень медленно. Давайте разберемся почему так происходит.

Таблица wp_postmeta и класс WP_Query

Таблица wp_postmeta содержит 4 поля:

1. meta_id – первичный ключ;
2. post_id – bigint, индексированное;
3. meta_key – varchar, индексированное;
4. meta_value – longtext, не индексированное.

Такая структура позволяет хранить практически любые значения метаданных, т.к. тип meta_value – longtext.

При этом поиск по ключу (meta_key) выполняется быстро, т.к. поле индексировано. Т.е. функция

get_post_meta( $post_id, $key, $single );

работает быстро, т.к. поиск выполняется по двум индексированным полям.

А вот поиск постов на основе значений этих полей – совсем другое дело.

В WordPress для выборки постов используется класс WP_Query, который поддерживает поиск по значениям метаданных.

Делается это следующим образом.

$args = array(
     ...
     'relation' => 'AND',
     'meta_query' => array(
          array(
               'key' => 'rating',
               'value' => array(3, 4),
               'type' => 'numeric',
               'compare' => 'BETWEEN',
          ),
          array(
               'key' => 'votes',
               'value' => 100,
               'type' => 'numeric',
               'compare' => '>=',
          )
     )
);
$query = new WP_Query($args);

Такой запрос вернёт все статьи у которых значение рейтинга находится в диапазоне от 3-х до 4-х, а число проголосовавших – больше или равно 100.

Обратите внимание, что мы задали тип полей numeric, т.е. мы хотим, чтобы значения, записанные в поле meta_value, считались числовыми, а не текстовыми.

В результате мы получим запрос вроде

SELECT SQL_CALC_FOUND_ROWS  wp_posts.ID FROM wp_posts
     INNER JOIN wp_postmeta ON (wp_posts.ID = wp_postmeta.post_id)
     INNER JOIN wp_postmeta AS mt1 ON (wp_posts.ID = mt1.post_id)
          WHERE 1=1
               AND wp_posts.post_type IN ('post', 'page')
               AND (wp_posts.post_status = 'publish')
               AND (
                    (wp_postmeta.meta_key = 'rating' AND CAST(wp_postmeta.meta_value AS SIGNED) BETWEEN '3' AND '4')
                    AND
                    (mt1.meta_key = 'votes' AND CAST(mt1.meta_value AS SIGNED) >= '100')
               )
     GROUP BY wp_posts.ID ORDER BY wp_posts.post_date DESC LIMIT 0, 10

Для каждого условия создается внутреннее объединение (INNER JOIN) с таблицей wp_postmeta. Кроме того, при фильтрации значений используется функция CAST, которая преобразует значения wp_postmeta.meta_value в числовой тип.

В реальном запросе будут еще дополнительные условия и объединения, например, с таблицей wp_term_relationships для того, чтобы выбрать посты, которые относятся к определённой категории.

В результате мы скорость выполнения запроса резко падает. И основная причина — INNER JOIN.

Конкретные значения времени выполнения запроса будут зависеть от размера БД (количества записей в таблицах wp_posts, wp_postmeta) и производительности сервера. Я сталкивался с ситуациями, когда время выполнения запроса с 4-мя такими условиями при 100к+ записях в таблице wp_postmeta (около 5000 постов с примерно 20-ю метаданными на пост) доходило до нескольких минут. Более мощное железо в какой-то степени улучшит ситуацию, но проблему не решит.

Дело в том, что MySQL должен перебрать все возможные сочетания метаданных, а их количество экспоненциально увеличивается с каждым объединением.

Варианты решения проблемы

1) Создать дополнительную таблицу с нужными полями и хранить данные в ней.

Тип связи новой таблицы с wp_posts – «один-к-одному». Как вариант, можно добавить дополнительные поля в таблицу wp_posts.

Выборка будет выполняться быстро, т.к. для полей можно указать числовой тип и будет только одно объединение, при этом количество записей в новой таблице будет меньше, чем в wp_postmeta.

Недостатки:

1. Если мы в будущем захотим использовать дополнительные метаданные, то нужно будет либо менять структуру новой таблицы, либо хранить их в wp_postmeta.
2. Работать с такой таблицей сложнее, т.к стандартные функции WP тут ничем не помогут.
3. Какая-то часть данных в такой таблице может иметь значение null. Например, если у вас для разных типов постов нужны разные метаполя.

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

2) Разбить запрос с объединениями на несколько.

1. Выполняем поиск в таблице wp_postmeta отдельно для каждого условия.
2. Получаем массивы, содержащие ID постов.
3. Находим пересечение (или объединение) этих массивов.
4. В основной запрос вместо условий поиска по метаданным, подставляем ID постов (WHERE ID IN (...)).

Количество запросов будет на один больше количества необходимых объединений. Но за счёт того, что выполняются они быстрее, получаем выигрыш в скорости.

Хоть скорость всё-равно остаётся довольно низкой из-за вызова CAST, время выполнения запроса значительно меньше, чем у запроса с объединениями. В одном из моих экспериментов, этим способом получилось уменьшить время с 27 до 0,3 сек.

3) Добавить индекс для поля meta_value

ALTER TABLE `wp_postmeta` ADD INDEX  USING BTREE (meta_value(255));

Этот совет я взял отсюда. Решение далеко не идеальное, автору той статьи тоже не нравится.

Эффект есть, но недостаточный. В моём случае время выполнения запроса уменьшилось примерно в 3,5 раза, но всё-равно это слишком медленно.

4) Для ограниченного набора дискретных значений использовать таксономии вместо метаданных.

Это не решение данной проблемы, просто иногда метаполя используются там, где нужны таксономии.

Для рейтинга или количества проголосовавших такое решение не подходит, но для таких параметров как цвет, размер (XL, XXL, …) и т.п. (т.е. любых данных которые имеют фиксированный набор значений) его можно использовать.

При поиске по терминам таксономий тоже используются объединения. Но он выполняется быстрее, чем по метаполям, т.к. в большинстве случаев таблица wp_terms содержит гораздо меньше значений, и вместо BETWEEN будет использоваться IN или =.

Заключение

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

Но если вы потратили некоторое время на изучение SQL и знаете как посмотреть запросы, которые формирует ваша библиотека, то сможете решить все проблемы

Happy querying!

The post WordPress: как получить медленный запрос с помощью метаданных и WP_Query first appeared on SimpleCoding.org.

Примечание. Ссылки на все предыдущие статьи вы найдёте в конце этой страницы.

Вообще создание многоязычного интерфейса – задача довольно тривиальная. В большинство фреймворков (и Yii здесь не исключение) входят соответствующие библиотеки. Но в нашем случае ситуация немного сложнее из-за того, что приложение состоит из клиентской и серверной частей. При этом для обоих фреймворков (Yii и AngularJS) есть собственные средства для работы с переводами.

В принципе, можно работать с двумя библиотеками. Но обычно удобнее, собрать все переводы в одном месте, либо на клиенте, либо на сервере. Т.к. передача данных от сервера клиенту (браузеру) проще, то мы будем использовать библиотеку Yii в качестве основной. А при формировании главной страницы приложения, передадим переводы AngularJS.

Напоминаю. Вы можете посмотреть исходный код приложения на GitHub и поэкспериментировать с демо-версией.

Интернационализация серверной части (Yii)

В официальном руководстве есть подробная статья на эту тему, повторять её я не буду, а остановлюсь только на тех моментах, которые относятся к нашему приложению.

Прежде всего, необходимо выбрать тип источника сообщений. Yii поддерживает три типа таких источников:

• обычные PHP массивы (CPhpMessageSource);
• файлы формата GNU Gettext (CGettextMessageSource);
• базу данных (CDbMessageSource).

Я остановился на первом варианте (PHP массивы), но принципиальной разницы нет.

Важно другое. Для передачи переводов клиентской части нам очень желательно передать сразу все переводы, иначе их придётся загружать AJAX запросами, а это занимает время и не лучшим образом скажется на внешнем виде приложения. Но класс CPhpMessageSource не позволяет получить все переводы сразу, точнее нужный нам метод loadMessages объявлен защищённым (protected).

Поэтому мы создадим компонент, который наследует CPhpMessageSource и будем использовать его в качестве источника сообщений.

protected/components/PhpMessageSource.php

class PhpMessageSource extends CPhpMessageSource {
    public function getAllMessages($category, $lang) {
        return $this->loadMessages($category, $lang);
    }
}

Мы объявили один метод getAllMessages, который просто вызывает loadMessages, т.е. возвращает массив переводов для указанного языка.

Подключаем наш компонент в config/main.php

return array(
	...
    'language'=>'ru',

	...
	// application components
	'components'=>array(
		...
        'messages'=>array(
            'class'=>'PhpMessageSource',
        ),
	),
	...
);

Файлы с переводами находятся в папке protected/messages.

messages/
	en/
		frontend.php
		...
	ru/
		frontend.php
		...

Сами переводы выглядят следующим образом:

return array(
    'CREATE_PLACE' => 'Create place',
    'UPDATE_PLACE' => 'Update place',
	...
);

return array(
    'CREATE_PLACE' => 'Создать объект',
    'UPDATE_PLACE' => 'Изменить объект',
	...
);

Интернационализация клиентской части (AngularJS)

Прежде всего, нам нужно передать переводы браузеру. Для этого в представление, которое создаёт главную страницу приложения (protected/views/places/index.php), добавим следующий код:

Yii::app()->clientScript->registerScriptFile(Yii::app()->baseUrl.'/js/angular-translate.min.js', CClientScript::POS_END);
Yii::app()->clientScript->registerScript(
    'langScript'
    , '
    var lang = "'.Yii::app()->getLanguage().'";
    var translations = '.CJSON::encode(Yii::app()->messages->getAllMessages('frontend', Yii::app()->getLanguage())).';'
    , CClientScript::POS_HEAD
);

В первой строке мы подключаем Angular translate. Это модуль, предназначенный для интернационализации приложений на Angular.

Затем мы создаём две JS переменные:

lang – содержит название языка;
translations – содержит массив с переводами.

Этих данных нам достаточно для того, чтобы настроить приложение public_html/js/app.js

Мы указываем модуль pascalprecht.translate в списке зависимостей приложения.

var app = angular.module('personalmaps', ['ui.bootstrap', 'pascalprecht.translate'])
    .value('lang', lang);

В результате через систему внедрения зависимостей (Dependency injection — DI) станет доступен сервис $translateProvider, которому мы передаём массив с переводами.

app.config(['$translateProvider', function($translateProvider) {
    // add translation table
    $translateProvider.translations(translations);
}]);

Также через DI будет доступна переменная lang. Вообще мы можем обойтись без неё, но я решил просто показать пример использования переменных. Т.е. получить к ней доступ можно, например, так:

app.controller('PlacesListController'
    , ['$scope', '$rootScope', 'Places', '$dialog', 'lang'
    , function($scope, $rootScope, Places, $dialog, lang) {

    $scope.curLang = lang;

	...
}]);

Возвращаемся к модулю Angular translate.

На официальном сайте предлагается загрузить все варианты переводов.

app.config(function ($translateProvider) {
  $translateProvider.translations('en', {
    TITLE: 'Hello',
	...
  });
  $translateProvider.translations('de', {
    TITLE: 'Hallo',
	...
  });
  $translateProvider.preferredLanguage('en');
});

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

$scope.changeLanguage = function (key) {
	$translate.uses(key);
};

Но в нашем приложении такая возможность не предусматривается. Язык приложения указывается в конфигурационном файле main.php, поэтому отправлять браузеру все переводы нет смысла. Мы просто один раз вызываем метод translations и передаём ему массив с переводами на выбранный язык.

$translateProvider.translations(translations);

Для использования переводов в модуль angular translate входит специальный фильтр – translate. Т.е. теперь в шаблонах мы можем написать что-то вроде (partials/list.html):

<span ng-show="isEmpty()">{{ 'NO_PLACES' | translate }}</span>

<div>
    <a href="places/index#/add" class="btn btn-success">{{ 'ADD_PLACE' | translate }}</a>
</div>

В фигурных скобках мы указываем имя сообщения (ключ в массиве translations) и через вертикальную черту – название фильтра. В результате мы получим значение из массива translations, т.е. сообщение на нужном языке.

Заключение

Этот цикл получился довольно объемным, и публикация растянулась на два месяца. Но мне кажется, что такой формат полезнее, чем отдельные статьи, потому что в них сложно рассмотреть взаимодействие нескольких технологий между собой. Даже в этом цикле многие вещи пришлось упростить, чтобы не перегружать код различными проверками и дополнительными функциями. Всё-таки основная цель заключалась в том, чтобы показать, как компоненты взаимодействуют между собой, а не создать приложение для продакшена (хотя приложение вполне можно использовать).

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

Успехов!

Содержание

The post Personal Maps: локализация и интернационализация. Часть 10 first appeared on SimpleCoding.org.

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

Предполагается, что каждый пользователь будет только со своими объектами, то нам будет достаточно двух уровней доступа:

• user – обычный пользователь, может работать только со своими объектами;
• admin – администратор, может работать со своими объектами, а также создавать, изменять и удалять других пользователей.

Т.е. администратор имеет те же самые права, что и обычный пользователь, плюс несколько дополнительных. Реализовать такую систему разграничения доступа удобнее всего с помощью RBAC (Role Based — Управление доступом на основе ролей).

Примечание. Исходный код приложения размещён на GitHub, также доступна демоверсия приложения.

Структура правил RBAC

В Yii фреймворк входит удобная библиотека для реализации такого управления доступом, которая поддерживает три элемента авторизации: операции (operations), задачи (tasks) и роли (roles). Роль может включать в себя несколько задач, а каждая задача – несколько операций.

Рассмотрим, как эти элементы авторизации связаны между собой в нашем приложении.

В первую очередь мы определяем операции пользователей (левая колонка на рисунке). Т.к. приложение у нас достаточно простое, операций немного. Фактически мы определили только CRUD операции для объектов типа Place и User.

Авторизация пользователей

Процедура авторизации предполагает проверку прав пользователя на доступ к запрошенному ресурсу или выполнение какой-то операции.

Эта проверка выполняется в методах контроллера (до того как мы что-либо отправили пользователю) с помощью метода checkAccess:

public function actionIndex() {
    if (Yii::app()->user->checkAccess('viewPlaces')) {
        $this->render('index');
    }
    else {
        $this->redirect(array('site/login'));
    }
}

Если текущий пользователь имеет соответствующие права, метод checkAccess вернёт true и будет показана главная страница приложения, если нет – произойдёт редирект на страницу с формой ввода логина и пароля.

Немного сложнее использование задач. В нашем приложении у пользователя не должно быть возможности удалить чужие объекты. Т.е. операция удаления должна быть ему доступна, но при этом нужно проверить принадлежит ли объект ему. Для этого используются задачи (tasks). При их создании мы определяем так называемое «бизнес правило». В нём мы должны сравнить id текущего пользователя со значением поля p_user_id выбранного объекта.

Т.е. бизнес правило будет выглядеть так:

return Yii::app()->user->id==$params["place"]->p_user_id;

При этом $params содержит данные, которые передаются во втором параметре checkAccess. В нашем случае это будет объект, который нужно удалить. Теперь рассмотрим метод удаления объекта.

public function actionDelete($id)
{
	$place = Places::model()->findByPk($id);
	if (null === $place) {
		$this->_sendResponse(404, CJSON::encode(array('message'=>'Could not find place with id = '.$id)));
		return;
	}
	if (!Yii::app()->user->checkAccess('deletePlace', array('place'=>$place))) {
		$this->_sendResponse(403);
		return;
	}
	if ($place->delete()) {
		$this->_sendResponse(200, CJSON::encode($place));
	}
	else {
		$this->_sendResponse(500, CJSON::encode(array(
			'message'=>'Could not delete place',
			'errors'=>$place->getErrors(),
		)));
	}
}

Запрос на удаление выглядит следующим образом

/api/places/id

В первую очередь мы ищем объект, который имеет указанный id. Если объект не найден, отправляем 404-ую ошибку.

Затем выполняем проверку прав пользователя. Обратите внимание, в методе checkAccess мы проверяем права на выполнение операции deletePlace, но при этом передаём во втором параметре массив с найденным объектом. Т.к. для операции deletePlace определена задача viewOwnPlace при проверке доступа будет использовано бизнес правило этой задачи. И если значение p_user_id не совпадает с id пользователя, метод вернёт false.

Создание правил RBAC

1. Правила, которые используются для проверок, должны где-то храниться. Это может быть как файл, так и база данных. Мы используем второй вариант.
2. Правила нужно создать. Для этого можно реализовать web интерфейс, который позволит редактировать правила для разных групп пользователей. Но т.к. у нас не предполагается возможность изменения связей между ролями, операциями и задачами, мы создадим их с помощью консольной команды.

Сначала создадим таблицы, в которых будут храниться правила. Их схема хранится в файле framework/web/auth/schema-mysql.sql. Просто импортируем его в базу и в результате у нас появятся три новые таблицы: authassignment, authitem и authitemchild.

Теперь нам нужно указать Yii, что мы хотим хранить правила в базе. Для этого в config/main.php настроим компонент authManager.

'components'=>array(
	...
	'authManager'=>array(
		'class'=>'CDbAuthManager',
		'connectionID'=>'db',
	),
	...
),

Напишем консольную команду.

Для этого создаём файл protected/commands/AccessCommand.php с двумя методами.

class AccessCommand extends CConsoleCommand
{
    public function actionAddRules() {
	...
    }

    public function actionAddAdminUser() {
	...
    }
}

Первый метод создаёт правила, второй – добавляет пользователя с правами администратора. Для того чтобы их вызвать нужно из консоли (из папки protected) выполнить команды

yiic access addRules
yiic access addAdminUser

Рассмотрим создание правил

public function actionAddRules() {
	$auth=Yii::app()->authManager;

	$auth->createOperation('addPlace','create place');
	$auth->createOperation('viewPlace','view place');
	$auth->createOperation('updatePlace','update place');
	$auth->createOperation('deletePlace','delete place');
	$auth->createOperation('viewPlaces','view places');

	$auth->createOperation('addUser','create user');
	$auth->createOperation('viewUser','view user');
	$auth->createOperation('updateUser','update user');
	$auth->createOperation('deleteUser','delete user');
	$auth->createOperation('viewUsers','view users');

	$bizRule='return Yii::app()->user->id==$params["place"]->p_user_id;';
	$task=$auth->createTask('viewOwnPlace', 'view own place', $bizRule);
	$task->addChild('viewPlace');
	$task=$auth->createTask('updateOwnPlace', 'edit own place', $bizRule);
	$task->addChild('updatePlace');
	$task=$auth->createTask('deleteOwnPlace', 'delete own place', $bizRule);
	$task->addChild('deletePlace');

	$role=$auth->createRole('user');
	$role->addChild('addPlace');
	$role->addChild('viewOwnPlace');
	$role->addChild('updateOwnPlace');
	$role->addChild('deleteOwnPlace');
	$role->addChild('viewPlaces');

	$role=$auth->createRole('admin');
	$role->addChild('user');
	$role->addChild('addUser');
	$role->addChild('viewUser');
	$role->addChild('updateUser');
	$role->addChild('deleteUser');
	$role->addChild('viewUsers');
}

Сначала мы получаем authManager с помощью которого выполняется создание операций, задач и ролей. Каждая операция создаётся с помощью метода createOperation, в первом параметре которого мы указываем имя операции, во втором — описание.

Затем с помощью createTask создаём задачи, для каждой из них указываем бизнес правило. И с помощью метода addChild «привязываем» операцию к задаче. Теперь при проверке прав доступа к операции будет использована соответствующая задача. Т.е. в первом параметре checkAccess мы в любом случае указываем название операции, а не задачи.

Для создания роли используется метод createRole. После этого к роли с помощью метода addChild «привязываем» операции, задачи и другие роли.

Обратите внимание. К роли admin мы не «привязываем» операции вроде viewPlace, т.к. у нас администратор должен получить все права пользователя мы «привязываем» роль user. На рисунке каждая стрелка соответствует вызову метода addChild, т.е. «привязке» одного объекта к другому. В результате получается иерархическое наследование прав.

Аутентификация пользователей

Процедура аутентификации предполагает проверку подлинности пользователя. В нашем случае она заключается в проверке логина и пароля.

Прежде всего, создадим класс UserIdentity с методом authenticate (protected/components/UserIdentity.php)

class UserIdentity extends CUserIdentity
{
	private $_id;

	public function authenticate()
	{
		$record = Users::model()->findByAttributes(array('u_name' => $this->username));
		if ($record === null) {
			$this->errorCode = self::ERROR_USERNAME_INVALID;
		} else if ($record->u_pass !== crypt($this->password, $record->u_pass)) {
			$this->errorCode = self::ERROR_PASSWORD_INVALID;
		} else {
			$this->_id = $record->id;
			$this->errorCode = self::ERROR_NONE;
		}
		return !$this->errorCode;
	}

	public function getId() {
		return $this->_id;
	}

	/**
	 * Generate a random salt in the crypt(3) standard Blowfish format.
	 *
	 * @param int $cost Cost parameter from 4 to 31.
	 *
	 * @throws Exception on invalid cost parameter.
	 * @return string A Blowfish hash salt for use in PHP's crypt()
	 */
	public static function blowfishSalt($cost = 13)
	{
		if (!is_numeric($cost) || $cost < 4 || $cost > 31) {
			throw new Exception("cost parameter must be between 4 and 31");
		}
		$rand = array();
		for ($i = 0; $i < 8; $i += 1) {
			$rand[] = pack('S', mt_rand(0, 0xffff));
		}
		$rand[] = substr(microtime(), 2, 6);
		$rand = sha1(implode('', $rand), true);
		$salt = '$2a$' . sprintf('%02d', $cost) . '$';
		$salt .= strtr(substr(base64_encode($rand), 0, 22), array('+' => '.'));
		return $salt;
	}
}

В методе authenticate (строка 10) мы проверяем пароль с помощью функции crypt. На сегодняшний день, использование md5 для хеширование паролей считается не надёжным, поэтому необходимо генерировать хеши на основе более сложных алгоритмов.

Функция crypt поддерживает несколько алгоритмов хеширования, в том числе blowfish, который мы используем в данном приложении. В первом параметре crypt передаётся пароль, а во втором – соль. При этом, формат соли определяет алгоритм хеширования. Функция вернет хеш пароля, который мы сравниваем с хешем, который хранится в базе данных.

Также в данный класс мы добавили метод blowfishSalt, который формирует хеш пароля в по алгоритму blowfish.

Важно! В Yii 1.1.14 появился класс CPasswordHelper, который можно использовать для выполнения этой же задачи. Алгоритмы будут использоваться те же самые, но ваш код будет короче. В частности, не придётся реализовывать метод blowfishSalt. Подробности вы можете почитать в статье Use crypt() for password storage. Кстати, код blowfishSalt я взял из старой версии этой статьи.

Теперь добавим команду, которая будет создавать аккаунт администратора.

class AccessCommand extends CConsoleCommand
{
	...

    public function actionAddAdminUser() {
        $auth=Yii::app()->authManager;

        $user = new Users();
        $user->u_name = 'admin';
        $user->u_pass = 'admin';
        $user->u_email = 'admin@site.loc';
        $user->u_role = 'admin';
        $user->save();
    }
}

Для того, чтобы эта команда правильно работала, нам нужно создать модель Users.

Контроллер и модель для работы с пользователями

Модель создаём с помощью gii и добавляем в неё два метода.

class Users extends CActiveRecord
{
	...
	
    public function beforeSave() {
        $this->u_pass = crypt($this->u_pass, UserIdentity::blowfishSalt());
        return parent::beforeSave();
    }

    public function afterSave() {
        $assignments = Yii::app()->authManager->getAuthAssignments($this->id);
        if (!empty($assignments)) {
            foreach ($assignments as $key => $assignment) {
                Yii::app()->authManager->revoke($key, $this->id);
            }
        }
        Yii::app()->authManager->assign($this->u_role, $this->id);
        return parent::afterSave();
    }
}

В методе beforeSave мы с помощью blowfishSalt хешируем пароль пользователя перед сохранением его в БД.

Метод afterSave используется для связей между пользователем и правами доступа. Это необходимо для того, чтобы администратор мог изменить права для уже созданных пользователей.

В первую очередь с помощью getAuthAssignments мы получаем массив всех связей между указанным пользователем и элементами авторизации RBAC. Далее удаляем все существующие связи и затем, с помощью метода assign, создаём новую связь. Новая связь устанавливается на основе значения поля u_role. Т.е. к конкретному пользователю мы привязываем роли, а не операции или задачи.

Обратите внимание. Пользователь с ролью администратор фактически имеет две роли: admin и user, т.к. роль admin наследует user. Поэтому мы храним «главную» роль пользователя в таблице pm_users. И именно к этой роли «привязываем» пользователя с помощью assign.

Контроллер и представления для модели Users мы также создаём с помощью gii.

Затем добавляем проверку прав пользователя в методы контроллера. Например,

public function actionView($id)
{
	if (Yii::app()->user->checkAccess('viewUser')) {
		$this->render('view', array(
			'model' => $this->loadModel($id),
		));
	}
	else {
		throw new CHttpException(403);
	}
}

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

Соответственно в файле views/layouts/yiistrap.php настроим меню таким образом, чтобы пункт «Пользователи» отображался только для администратора.

<?php $this->widget('zii.widgets.CMenu',array(
	'items'=>array(
		array('label'=>Yii::t('app', 'PLACES'), 'url'=>array('/places/index'), 'visible'=>!Yii::app()->user->isGuest),
		array('label'=>Yii::t('app', 'USERS'), 'url'=>array('/users/index'), 'visible'=>Yii::app()->user->checkAccess('viewUsers')),
		array('label'=>Yii::t('app', 'ABOUT'), 'url'=>array('/site/page', 'view'=>'about')),
		array('label'=>Yii::t('app', 'CONTACT'), 'url'=>array('/site/contact')),
		array('label'=>Yii::t('app', 'LOGIN'), 'url'=>array('/site/login'), 'visible'=>Yii::app()->user->isGuest),
		array('label'=>Yii::t('app', 'LOGOUT').' ('.Yii::app()->user->name.')', 'url'=>array('/site/logout'), 'visible'=>!Yii::app()->user->isGuest)
	),
	'activeCssClass'=>'active',
	'htmlOptions'=>array(
		'class'=>'nav',
	),
)); ?>

В строке 4 мы с помощью checkAccess проверяем, может ли данный пользователь просматривать список пользователей (/users/index).

И в качестве завершающего штриха немного исправим форму создания (редактирования) пользователя (файл views/users/_form.php)

<?php echo $form->errorSummary($model); ?>

		<?php echo $form->textFieldControlGroup($model,'u_name',array('span'=>5,'maxlength'=>255)); ?>

		<?php echo $form->textFieldControlGroup($model,'u_email',array('span'=>5,'maxlength'=>255)); ?>

		<?php echo $form->passwordFieldControlGroup($model,'u_pass',array('span'=>5,'maxlength'=>255,'value'=>'')); ?>

		<?php echo $form->passwordFieldControlGroup($model,'u_pass_repeat',array('span'=>5,'maxlength'=>255,'value'=>'')); ?>

		<?php echo $form->dropDownListControlGroup($model, 'u_role', array('user'=>'user', 'admin'=>'admin'), array('class' => 'span5')); ?>

	<div class="form-actions">
	<?php echo TbHtml::submitButton($model->isNewRecord ? Yii::t('app', 'SAVE') : Yii::t('app', 'UPDATE'), array(
		'color'=>TbHtml::BUTTON_COLOR_PRIMARY,
		'size'=>TbHtml::BUTTON_SIZE_LARGE,
	)); ?>
</div>

<?php $this->endWidget(); ?>

В частности, мы использовали метод dropDownListControlGroup для того, чтобы создать выпадающий список с ролями пользователей. Gii создаёт обычное текстовое поле.

Заключение

Использования RBAC особой сложности не представляет. Самое главное, изначально продумать систему ролей таким образом, чтобы её было легко и удобно расширять. И помнить, что проверять в контроллерах нужно операции, а роли «привязывать» к пользователям. Тогда вы сможете создавать новые роли с любым набором прав, и при этом не нужно будет изменять проверки в контроллерах и другие роли.

Также советую почитать статью RBAC Авторизация в YII и LDAP. В ней более подробно описывается использование RBAC в Yii без привязки к конкретному приложению.

Если есть вопросы или замечания, пишите.
Успехов!

Содержание

The post Personal Maps: авторизация и аутентификация (с использованием Yii RBAC). Часть 9. first appeared on SimpleCoding.org.

Форматы запросов клиентской части к серверу и его ответов у нас уже определены. Фактически мы это сделали когда тестировали сервис Places. Теперь нам нужно реализовать поддержку этих запросов серверной частью приложения.

Создание REST сервисов с помощью Yii фреймворка

Примечание. Если вы не знакомы с общими принципами создания REST сервисов, то рекомендую прочитать статью Create a REST API with PHP.

Также напоминаю, что исходный код приложения размещён на GitHub и доступна демоверсия приложения.

Source

Обычные web приложения работают с двумя типами HTTP запросов – GET и POST, т.к. вы не можете отправить другие типы запросов с помощью стандартной HTML формы. Но при использовании JavaScript ситуация изменяется. AngularJS, как и большинство других фреймворков, позволяет использовать дополнительные типы запросов, в нашем случае это PUT и DELETE.

Таким образом, для создания REST сервиса нам нужно:

• написать контроллер, который будет обрабатывать запросы;
• создать правила для роутера.

Контроллер REST сервиса

Прежде всего, давайте вспомним, какие запросы мы можем получить от клиентской части.

• GET api/places – в ответ мы должны вернуть массив, содержащий все объекты данного пользователя;
• GET api/places/id_объекта – ищем объект с данным id и возвращаем только его;
• POST api/places – этот запрос указывает, что необходимо создать новый объект, информация о нём передаётся в параметрах запроса;
• PUT api/places/id_объекта – изменение объекта с указанным id, как и в случае с POST информация об объекте будет отправлена в параметрах запроса;
• DELETE api/places/id_объекта – этот запрос говорит о том, что необходимо удалить объект с указанным id.

Т.е. мы можем создать обычный контроллер с методами, которые будут соответствовать этим запросам. Но, т.к. наш REST сервис должен отправлять ответы в json формате с правильными заголовками, то будет удобнее создать абстрактный базовый класс RestController и на его основе – контроллер сервиса.

В документации Yii есть хорошая статья о создании REST сервисов. Я использовал приведённый в ней пример в качестве основы для RestController, но немного его упростил с учётом особенностей данного приложения.

abstract class RestController extends Controller
{
    // Members
    /**
     * Default response format
     * either 'json' or 'xml'
     */
    private $format = 'json';
    /**
     * @return array action filters
     */
    public function filters()
    {
        return array();
    }

    // Actions
    abstract public function actionList();

    abstract public function actionView($id);

    abstract public function actionCreate();

    abstract public function actionUpdate($id);

    abstract public function actionDelete($id);

    protected function _sendResponse($status = 200, $body = '', $content_type = 'text/html')
    {
        // set the status
        $status_header = 'HTTP/1.1 ' . $status . ' ' . $this->_getStatusCodeMessage($status);
        header($status_header);
        // and the content type
        header('Content-type: ' . $content_type);

        // pages with body are easy
        if($body != '')
        {
            // send the body
            echo $body;
        }
        // we need to create the body if none is passed
        else
        {
            // create some body messages
            $message = '';

            // this is purely optional, but makes the pages a little nicer to read
            // for your users.  Since you won't likely send a lot of different status codes,
            // this also shouldn't be too ponderous to maintain
            switch($status)
            {
                case 401:
                    $message = 'You must be authorized to view this page.';
                    break;
                case 404:
                    $message = 'The requested URL ' . $_SERVER['REQUEST_URI'] . ' was not found.';
                    break;
                case 500:
                    $message = 'The server encountered an error processing your request.';
                    break;
                case 501:
                    $message = 'The requested method is not implemented.';
                    break;
            }

            // servers don't always have a signature turned on
            // (this is an apache directive "ServerSignature On")
            $signature = ($_SERVER['SERVER_SIGNATURE'] == '') ? $_SERVER['SERVER_SOFTWARE'] . ' Server at ' . $_SERVER['SERVER_NAME'] . ' Port ' . $_SERVER['SERVER_PORT'] : $_SERVER['SERVER_SIGNATURE'];

            // this should be templated in a real-world solution
            $body = '
<!doctype html>
<html lang="en-US">
<head>
    <meta charset="UTF-8">
    <title>' . $status . ' ' . $this->_getStatusCodeMessage($status) . '</title>
</head>
<body>
    <h1>' . $this->_getStatusCodeMessage($status) . '</h1>
    <p>' . $message . '</p>
    <hr />
    <address>' . $signature . '</address>
</body>
</html>';

            echo $body;
        }
        Yii::app()->end();
    }

    protected function _getStatusCodeMessage($status)
    {
        // these could be stored in a .ini file and loaded
        // via parse_ini_file()... however, this will suffice
        // for an example
        $codes = Array(
            200 => 'OK',
            400 => 'Bad Request',
            401 => 'Unauthorized',
            402 => 'Payment Required',
            403 => 'Forbidden',
            404 => 'Not Found',
            500 => 'Internal Server Error',
            501 => 'Not Implemented',
        );
        return (isset($codes[$status])) ? $codes[$status] : '';
    }
}

В строках 18-26 мы объявляем пять абстрактных методов, которые соответствуют всем нашим запросам. Т.е. класс, который будет наследовать RestController должен будет определить эти методы.

Также у нас есть два вспомогательных метода.

_getStatusCodeMessage – в нём просто определены описания HTTP статусов, которые будут отправляться в заголовках ответов.

_sendResponse – формирует ответ сервера, т.е. устанавливает HTTP заголовки и отправляет данные.

Теперь создадим PlacesController

class PlacesController extends RestController
{
    public function actionIndex() {
        if (Yii::app()->user->checkAccess('user')) {
            $this->render('index');
        }
        else {
            $this->redirect(array('site/login'));
        }
    }

    public function actionList()
    {
        if (!Yii::app()->user->checkAccess('user')) {
            $this->_sendResponse(403);
            return;
        }
        //searching only for current users places (defaultScope returns appropriate condition)
        $places = Places::model()->findAll();
        echo CJSON::encode($places);
    }

    public function actionView($id)
    {
    }

    public function actionCreate()
    {
        if (!Yii::app()->user->checkAccess('user')) {
            $this->_sendResponse(403);
            return;
        }
        $data = CJSON::decode(file_get_contents('php://input'));
        $place = new Places();
        $place->attributes = $data;
        if ($place->save()) {
            $this->_sendResponse(200, CJSON::encode($place));
        }
        else {
            $this->_sendResponse(500, CJSON::encode(array(
                'message'=>'Could not save place',
                'errors'=>$place->getErrors(),
            )));
        }
    }

    public function actionUpdate($id)
    {
        $data = CJSON::decode(file_get_contents('php://input'));
        $place = Places::model()->findByPk($id);
        if (!Yii::app()->user->checkAccess('user', array('place'=>$place))) {
            $this->_sendResponse(403);
            return;
        }
        if (null === $place) {
            $this->_sendResponse(404, CJSON::encode(array('message'=>'Could not find place with id = '.$id)));
        }
        $place->attributes = $data;
        if ($place->save()) {
            $this->_sendResponse(200, CJSON::encode($place));
        }
        else {
            $this->_sendResponse(500, CJSON::encode(array(
                'message'=>'Could not save place',
                'errors'=>$place->getErrors(),
            )));
        }
    }

    public function actionDelete($id)
    {
        $place = Places::model()->findByPk($id);
        if (null === $place) {
            $this->_sendResponse(404, CJSON::encode(array('message'=>'Could not find place with id = '.$id)));
            return;
        }
        if (!Yii::app()->user->checkAccess('user', array('place'=>$place))) {
            $this->_sendResponse(403);
            return;
        }
        if ($place->delete()) {
            $this->_sendResponse(200, CJSON::encode($place));
        }
        else {
            $this->_sendResponse(500, CJSON::encode(array(
                'message'=>'Could not delete place',
                'errors'=>$place->getErrors(),
            )));
        }
    }
}

Этот класс наследует RestController, т.е. в нём мы должны определить все абстрактные методы (actionList, actionView и т.д.). Во всех этих методах мы в первую очередь с помощью Yii::app()->user->checkAccess проверяем права текущего пользователя и если проверка не пройдена, отправляем 403 ошибку.

Примечание. Подробно систему разграничения доступа мы рассмотрим в следующий раз.

После этого, мы выполняем соответствующую операцию. Т.е. либо возвращаем список объектов (actionList), либо создаём, изменяем или удаляем указанную модель. Во всех методах id модели передаётся в первом параметре, т.к. его определяет роутер при разборе URL. Для получения остальных данных запроса используется функция file_get_contents.

$data = CJSON::decode(file_get_contents('php://input'));

Т.к. данные приходят в JSON формате, мы их декодируем с помощью класса CJSON.

Ещё одни момент касается обработки ошибок. Если у пользователя не достаточно прав для выполнения операции – отправляем 403-ю со стандартным сообщением (задано в методе _getStatusCodeMessage класса RestController).

Если модель не найдена (методы actionUpdate и actionDelete) – возвращаем 404-ю с собственным сообщением, т.к. по стандартному сложно понять, что именно не было найдено.

Наконец, если операцию выполнить не удалось, возвращаем 500-ую. В описание этих ошибок входят два параметра:
message – содержит название операции, которую не удалось выполнить;
errors – содержит массив с ошибками.

Проверить отправку этих ошибок вы можете следующим образом. Запустите приложение и дождитесь загрузки списка объектов. После этого остановите сервер базы данных и попробуйте изменить какой-нибудь объект. В форме вы увидите соответствующие ответы. И обратите внимание, что после того как вы снова запустите сервер базы, пользователь сможет продолжить работу без необходимости перезагружать страницу и не потеряет введённые данные.

Правила для роутера

Формат запросов к API отличается от стандартного формата запросов Yii (имя_контроллера/имя_метода), поэтому добавим в файл в файл config/main.php правила для каждого из наших запросов.

Обратите внимание, что для каждого правила, мы указываем параметр verb. Это необходимо, т.к. шаблоны для запросов на просмотр, удаление и обновление объекта не отличаются ничем кроме типа (GET, PUT, DELETE).

'components'=>array(
	...
	'urlManager'=>array(
		'urlFormat'=>'path',
		'rules'=>array(
			// REST patterns
			array('places/list', 'pattern'=>'api/places', 'verb'=>'GET'),
			array('places/view', 'pattern'=>'api/places/<id:\d+>', 'verb'=>'GET'),
			array('places/update', 'pattern'=>'api/places/<id:\d+>', 'verb'=>'PUT'),
			array('places/delete', 'pattern'=>'api/places/<id:\d+>', 'verb'=>'DELETE'),
			array('places/create', 'pattern'=>'api/places', 'verb'=>'POST'),
			// regular patterns
			'<controller:\w+>/<id:\d+>'=>'<controller>/view',
			'<controller:\w+>/<action:\w+>/<id:\d+>'=>'<controller>/<action>',
			'<controller:\w+>/<action:\w+>'=>'<controller>/<action>',
		),
		'showScriptName'=>false,
	),
	...
),

Важно помнить, что роутер разбирает правила сверху вниз и использует первое же правило, которое соответствует данному запросу. В данном случае если мы добавим новые правила в конец списка, то запросы вроде api/list будут обрабатываться стандартными правилами и Yii попытается найти класс ApiController и вызвать его метод actionList.

Как видите, создание REST API особой сложности не представляет. Естественно, этот пример очень простой и в реальном приложении у вас будет гораздо больше методов. Кроме того, может возникнуть необходимость одновременно поддерживать несколько версий API. В таких случаях контроллер и правила роутера станут сложнее, но общий принцип останется тем же.

В следующей части мы рассмотрим разграничение прав пользователей с помощью RBAC.

Если есть вопросы или замечания, пишите. Успехов!

Содержание

The post Personal maps: REST интерфейс. Часть 8. first appeared on SimpleCoding.org.

Директивы в AngularJS предназначены для работы с DOM (Document Object Model – объектная модель документа) и позволяют создавать новые компоненты или добавлять существующим новые свойства.

В Angular есть множество встроенных директив, часть из них мы уже использовали при создании представлений. Например, ngHide позволяет скрыть элемент в зависимости от значения модели, т.е. изменяет CSS стили элемента.

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

Естественно, создание собственных директив сложнее, чем использование стандартных. Нужно понимать, как решить задачу, и учитывать требования AngularJS к директивам. Но при правильном использовании директивы упрощают разработку приложения, особенно если оно сложное и содержит компоненты с похожим поведением.

Возвращаемся к нашей задаче.

Напомню. Исходный код приложения размещён на GitHub, также доступна демоверсия приложения.

На главной странице нашего приложения нужно показать карту с объектами, добавленными пользователем. Карта должна реагировать на работу пользователя со списком объектов. Например, клик по названию объекта в списке должен приводить к отображению подробного описания этого объекта на карте. Т.е. наша директива должна реагировать на события приложения. Рассмотрим их подробнее.

События, с которыми работает директива

• places:updated – это событие возникает когда сервис Places (описание в 4-ой части) получает обновлённый список объектов.
• place:updated – возникает когда изменяются данные (координаты, заголовок или описание) какого-нибудь объекта.
• place:added – возникает при создании нового объекта.
• place:show – возникает, когда пользователь выбирает объект в списке.
• place:deleted – возникает при удалении объекта.
• map:pointSelected – это событие отправляет директива, когда пользователь кликает по карте.

Обработчикам всех событий кроме places:updated передается информация об объекте.

Создание директивы

Прежде всего, создаём файл с кодом директивы – js/directives/pm-google-map.js

app.directive('pmGoogleMap', function factory($window, $rootScope, Places) {
    return {
    ...
    }
});

В первом параметре метода directive мы указываем название директивы. AngularJS использует специальное соглашение при формировании этих имён. При использовании названия директивы в HTML разметке, нужно преобразовать все заглавные буквы в прописные и поставить перед ними дефис. Т.е. добавить нашу директиву на страницу можно следующим образом:

<div class="span9 map" pm-google-map>

Если вы хотите чтобы HTML валидатор не показывал ошибок, можно использовать один из следующих вариантов:

<div class="span9 map" data-pm-google-map>

<div class="span9 map" x-pm-google-map>

Структура директивы

Во втором параметре метода directive передаётся функция, которая получает список зависимостей (это компоненты, которые будут доступны внутри директивы) и должна вернуть JS объект, создающий саму директиву. Подробное описание этого объекта вы найдёте в официальной документации, а сейчас мы рассмотрим только те параметры, которые нужны в данном случае.

app.directive('pmGoogleMap', function factory($window, $rootScope, Places) {
    return {
        restrict: 'A',
        link: function(scope, element, attrs) {
        ...
        }
    }
});

Параметр restrict указывает где именно можно использовать данную директиву. A означает attribute, т.е. атрибут любого элемента. Также можно использовать E (element), C (class) и M (comment). Например, если разрешить использование директивы в названии элемента

restrict: 'EA',

то можно будет подключить директиву следующим образом

<pm-google-map class="span9 map">

Для нашего приложения принципиальной разницы нет, но для директив вроде ngHide использование в качестве элемента смысла не имеет.

Параметр link получает функцию, которая выполняет работу с DOM и обработку событий. Эта функция автоматически вызывается при создании директивы. И в нашем случае весь код директивы находится именно в этой функции.

Полностью код директивы вы можете посмотреть на GitHub, а в этой статье мы будем разбирать его по частям.

Инициализация карты

Для данного приложения я выбрал Google Maps, но точно также можно было использовать и Яндекс.Карты. Кстати, если вы захотите подключить Яндекс.Карты, то заменить придётся только данную директиву. Все остальные компоненты приложения останутся без изменений.

Примечание. Существуют готовые директивы для подключения Google maps, например, эта. Но в данном случае, удобнее создать собственную директиву, которая будет реагировать на события данного приложения. Тем более, что API карт удобный.

Прежде всего, функция link должна инициализировать карту.

link: function(scope, element, attrs) {
	function setMapHeight() {
		var mapHeight = $window.innerHeight - $('header').height() - $('footer').height() - 20;
		element.css('height', mapHeight);
	}
	setMapHeight();

	scope.map = null;

	function initialize() {
		var defaults = {
			center: new google.maps.LatLng(-34.397, 150.644),
			zoom: 8,
			panControl: true,
			zoomControl: true,
			scaleControl: true,
			mapTypeId: google.maps.MapTypeId.ROADMAP
		};
		scope.map = new google.maps.Map(element[0], defaults);
	}
	if (scope.map === null) {
		initialize();
	}
	
	...
	
}

С помощью функции setMapHeight мы устанавливаем высоту карты. Здесь используется сервис $window, который является ссылкой на стандартный объект window. Но т.к. использование window вызовет проблемы при тестировании, использовать рекомендуется именно $window.

Затем с помощью initialize мы создаём карту. Код практически совпадает с примерами в документации к Google Maps API. Но обратите внимание на следующие моменты:

1. Для директивы автоматически создаётся собственный объект scope. Его назначение и использование мы рассматривали в предыдущей части. В данном случае мы используем его для хранения ссылок на карту и маркеры.
2. Во втором параметре функция link получает ссылку на объект, для которого установлена директива. Нам он нужен для того, чтобы установить высоту карты так, чтобы она занимала большую часть окна приложения.

Обработка событий

Рассмотрим обработку события places:updated

function getDescription(place) {
	return '<h4>' + place.p_title + '</h4>' + markdown.toHTML(place.p_description);
}

function setMarkerOnClickEvent(marker) {
	google.maps.event.addListener(marker, 'click', function(event) {
		var place = Places.get(marker.pid);
		var latlng = new google.maps.LatLng(place.p_lat, place.p_lng);
		infoBox.setContent(getDescription(place));
		infoBox.setPosition(latlng);
		infoBox.open(scope.map);
	});
}

scope.markers = [];
var infoBox = new google.maps.InfoWindow();

$rootScope.$on('places:updated', function() {
	scope.markers = [];
	infoBox.close();
	var bounds = new google.maps.LatLngBounds();
	angular.forEach(Places.getAll(), function(place) {
		var latlng = new google.maps.LatLng(place.p_lat, place.p_lng);
		bounds.extend(latlng);
		var marker = new google.maps.Marker({
			position: latlng,
			map: scope.map,
			title: place.p_title,
			pid: place.id
		});
		setMarkerOnClickEvent(marker);
		scope.markers.push(marker);
	});
	scope.map.fitBounds(bounds);
});

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

getDescription – формирует описание объекта. Наше приложение позволяет пользователям вводить описание объектов с использованием синтаксиса markdown. Для этих целей мы используем библиотеку markdown-js. Преобразование из markdown в HTML выполняется с помощью метода markdown.toHTML (строка 2).

setMarkerOnClickEvent – устанавливает обработчик события click для маркеров объектов. Клик по маркеру центрирует карту и открывает infoBox (google.maps.InfoWindow) в котором отображается название и описание объекта.

Появление события places:updated означает, что сервис Places получил новый список объектов, поэтому нам необходимо сформировать новый массив с маркерами и показать его на карте. Для этого, мы получаем с помощью Places.getAll() новый список объектов (строка 22), для каждого из них создаём маркер, устанавливаем для него обработчики событий и показываем их на карте (строки 23-32).

Затем позиционируем карту таким образом, чтобы были видны все маркеры (строка 34).

Принцип работы обработчиков событий place:updated, place:added и place:deleted очень похож. Все их обработчики во втором параметре получают информацию об объекте, для которого нужно выполнить соответствующую операцию (создать, удалить или изменить). Рассмотрим в качестве примера обработчик события place:updated.

$rootScope.$on('place:updated', function(event, place) {
	infoBox.close();
	angular.forEach(scope.markers, function(marker) {
		if (marker.pid == place.id) {
			var latlng = new google.maps.LatLng(place.p_lat, place.p_lng);
			marker.setTitle(place.p_title);
			marker.setPosition(latlng);
			scope.map.setCenter(latlng);
			infoBox.setContent(getDescription(place));
			infoBox.setPosition(latlng);
			infoBox.open(scope.map);
			return false;
		}
	});
});

Т.к. каждому объекту соответствует маркер на карте, мы в цикле перебираем все маркеры и ищем тот, у которого атрибут pid совпадает с id объекта. Если маркер найден, устанавливаем для него новые параметры и открываем infoBox.

Обработчики остальных методов вы найдете на GitHub.

Последний шаг в создании директивы – установка обработчика события click карты.

google.maps.event.addListener(scope.map, 'click', function(event) {
	scope.$apply(function() {
		$rootScope.$broadcast('map:pointSelected', {
			p_lat: Math.round(event.latLng.lat() * 100) / 100,
			p_lng: Math.round(event.latLng.lng() * 100) / 100
		});
	});
});

Этот обработчик выполняет только одну операцию – отправляет событие map:pointSelected с координатами точки, по которой кликнул пользователь. Т.к. вызов обработчика происходит вне контекста AngularJS, необходимо обернуть отправку события в вызов scope.$apply. Если с этим моментом возникают вопросы, советую почитать статью AngularJS and scope.$apply.

Тестирование директивы

Как вы, наверное, помните из предыдущих частей, непосредственно тестирование компонентов AngularJS достаточно простое. Основная проблема заключается в подготовке «окружения» перед выполнением теста.

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

Тесты для нашей директивы не должны зависеть от других компонентов приложения. Поэтому мы должны создать mock объект для сервиса Places.

beforeEach(module('personalmaps', function ($provide) {
	var Places = {
		'get': function() {},
		'getAll': function() {},
		'add': function() {},
		'update': function() {},
		'delete': function() {},
		'save': function() {}
	};
	spyOn(Places, 'getAll').andReturn([
		{
			id: 1,
			p_title: '111',
			p_description: 'test 1',
			p_lat: 0,
			p_lng: 0
		},
		{
			id: 2,
			p_title: '222',
			p_description: 'test 2',
			p_lat: 10,
			p_lng: 10
		}
	]);
	$provide.provider('Places', {
		$get: function() {
			return Places;
		}
	});
	$provide.value('lang', 'en_us');
}));

Этот объект содержит те же самые методы, что и настоящий сервис, но они ничего не выполняют (строки 3-8). Также с помощью функции spyOn мы настраиваем отслеживание вызова метода getAll и формируем массив с данными, которые он должен вернуть (строки 10-25).

Затем мы должны сделать так, чтобы наша директива подключила новый объект через механизм внедрения зависимостей (DI – dependency injection). Для этого используется сервис $provide. Мы вызываем метод provider и передаём ему название сервиса – Places, и объект, содержащий метод $get. Этот метод будет автоматически вызван сервисом $injector, который управляет внедрением зависимостей.

Т.к. в списке зависимостей директивы указан сервис Places, $injector найдёт соответствующий провайдер и попытается получить объект с помощью метода $get. В результате $injector получит наш объект.

У директив есть ещё одна особенность – они «привязаны» к разметке страницы. Во время выполнения теста страницы как таковой у нас нет, поэтому мы должны создать тег вручную и «привязать» нашу директиву к нему. Сделать это можно следующим образом:

beforeEach(inject(function($injector, $rootScope, $compile, Places) {

	spyOn($rootScope, '$broadcast');

	elm = angular.element(
		'<div class="span9 map" pm-google-map></div>'
	);

	scope = $rootScope;
	$compile(elm)(scope);
	scope.$digest();

	spyOn(scope.map, 'setCenter');
}));

Примечание. Функцию beforeEach можно использовать несколько раз.

Обратите внимание на строки 5-7. В них мы создаём точно такой же тег div, как и на странице приложения. Затем компилируем его и передаём в качестве аргумента scope (строка 10). Эти же самые операции выполняет AngularJS при инициализации приложения.

Ещё один момент. Мы отслеживаем вызов метода setCenter (строка 13). Именно по этой причине у нас карта присвоена свойству объекта scope. Если бы в функции link мы записали var map = ..., то отследить центрирование карты было бы невозможно.

Теперь в качестве примера рассмотрим один из тестов

it('should call map.setCenter on place:show', inject(function($compile, $rootScope) {
	$rootScope.$emit('place:show', {
		id: 1,
		p_title: '111',
		p_description: 'test',
		p_lat: 0,
		p_lng: 0
	});
	expect(scope.map.setCenter).toHaveBeenCalled();
}));

Здесь мы инициируем событие, которое при работе приложения отправляется, когда пользователь кликает на название объекта в списке. Мы проверяем, что при возникновении этого события директива отцентрирует карту.

Ещё один пример.

it('should remove marker from array on place:deleted', inject(function($compile, $rootScope) {
	$rootScope.$emit('places:updated');
	$rootScope.$emit('place:deleted', {id: 1});
	expect(scope.markers.length).toBe(1);
}));

Здесь мы проверяем, что событие place:deleted приводит к уменьшению количества маркеров. Естественно, перед тем как отправлять place:deleted нужно отправить places:updated, чтобы массив маркеров не был пустым.

Остальные тесты работают по такому же принципу, посмотреть вы их можете в файле pm-google-map.spec.js.

В следующей части цикла мы вернёмся к разработке серверной части приложения и рассмотрим создания REST API.

Содержание

The post Personal maps: создаём директиву для подключения Google Maps. Часть 7. first appeared on SimpleCoding.org.

Когда я начинал разрабатывать более-менее сложные приложения на JavaScript, создание этих компонентов было одним из самых сложных моментов. Проблема была в том, что при создании клиентской части я автоматически пытался применять подходы, которые используются на сервере, и из-за этого возникали проблемы. Сбивало то, что и PHP, и JavaScript фреймворки используют модели, представления и контроллеры (MVC архитектура), но архитектура всего приложения при этом отличается.

Когда серверный фреймворк обрабатывает запрос, он с помощью роутера находит нужный метод (action) контроллера и вызывает его. В этом методе мы обрабатываем данные с помощью модели и выводим результат с помощью представления. Для следующего запроса процесс повторяется.

Но JavaScript фреймворк не получает HTTP запросов. Приложение создаётся один раз и работает до тех пор, пока пользователь не перезагрузит страницу или не закроет браузер. Т.е. на странице могут одновременно работать несколько контроллеров, каждый из которых отвечает за свою часть страницы. При этом взаимодействие между ними может быть организовано как с помощью событий, так и напрямую (один контроллер вызывает методы другого). Естественно, последний способ использовать не желательно, т.к. он увеличивает количество зависимостей в приложении. И изменение одного из контроллеров потребует переписывания кода в других.

Кроме того, есть ещё специфика конкретного JS фреймворка. Если в большинстве PHP фреймворков создание контроллеров, моделей и представлений практически не отличается, то разница между созданием этих же компонентов, например, в Backbone и AngularJS очень заметна.

Поэтому, прежде чем переходить к коду нашего приложения, рассмотрим общий принцип создания MVC компонентов в AngularJS.

Примечание. Исходный код размещён на GitHub, также доступна демоверсия приложения.

Создание контроллеров в AngularJS

Фактически контроллером может быть любая JavaScript функция. Достаточно её объявить и указать её название в атрибуте ng-controller какого-нибудь тега.

function MyController() { ... }

<div ng-controller="MyController">...</div>

Эту форму записи не желательно использовать в реальных приложениях, но, тем не менее, она вполне рабочая. Ниже мы рассмотрим другой способ создания контроллера, а сейчас нам важно разобраться, что делает AngularJS.

Для каждого контроллера фреймворк создаёт так называемый Scope. Это объект, который ссылается на модель приложения. Контроллер нужен для того, чтобы инициализировать Scope и добавить ему «поведения» (например, обработчики событий).

Передача данных между контроллером, моделью и представлениями, в том числе и двунаправленное связывание данных, происходит именно с помощью объекта scope.

Модели в AngularJS

В AngularJS моделями являются любые данные, которые хранятся в свойствах объекта scope.

Т.к. scope сам по себе является JavaScript объектом, то его свойствам можно присвоить любые другие объекты любой сложности. Например,

$scope.hello = 'Привет';

или

$scope.delete = function(id) { ... };

Представления в AngularJS

Представлением в AngularJS является DOM (Document Object Model – объектная модель документа) или её часть. Когда мы подключаем контроллер, то указываем для какого-нибудь тега в разметке страницы атрибут ng-controller или ng-view. Этот тег и всё его содержимое и являются представлением для данного контроллера.

Представление может содержать выражения, заключённые в двойные фигурные скобки. AngularJS обрабатывает эти выражения, и показывает пользователю результат. Например,

<div>{{ hello }}</div>

будет преобразовано в

<div>Привет</div>

При этом в контроллере мы должны установить значение свойства hello для объекта $scope. Указывать $scope в представлении не нужно.

Таким образом, представление «знает» о контроллере за счёт атрибутов ng-controller или ng-view и может получать значение атрибутов объекта scope.

Роутер в AngularJS

Роутер является не обязательным компонентом. Он позволяет переключать контроллеры в зависимости от текущего значения URL, точнее той его части, которая идёт после символа #.

В нашем приложении центральная часть страницы разделена на две области. В левой находится карта, она должна отображаться постоянно. А в правой – либо список объектов, либо форма создания нового объекта.

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

Нам нужно, чтобы:

• для #/list отображался список объектов;
• для #/add отображалась форма создания нового объекта;
• а для #/edit/id отображалась форма редактирования объекта, который имеет указанный id.

Настроим роутер (файл app.js)

var app = angular.module('personalmaps', ['ui.bootstrap', 'pascalprecht.translate'])
    .value('lang', lang);

app.config(['$routeProvider', function($routeProvider) {
    $routeProvider.when('/list', {
        templateUrl: 'partials/list.html',
        controller: 'PlacesListController'
    });
    $routeProvider.when('/add', {
        templateUrl: 'partials/form.html',
        controller: 'PlacesFormController'
    });
    $routeProvider.when('/edit/:placeId', {
        templateUrl: 'partials/form.html',
        controller: 'PlacesFormController'
    });
    $routeProvider.otherwise({
        redirectTo: '/list'
    });
}]);

Как видите, после создания приложения (строка 1) мы вызываем метод config, которому передаём функцию, настраивающую роутер.

В первом параметре эта функция получает $routeProvider – объект, который используется для настройки сервиса $route (стандартный сервис AngularJS).

Для каждого варианта URL, который нам нужно обрабатывать, вызываем метод when, в котором передаём два параметра:

1. Шаблон URL. Если URL содержит параметры, то перед ними нужно поставить двоеточие. Для каждого параметра создаётся свойство в объекте $routeParams. Например, $routeParams.placeId.
2. Хеш с настройками. templateUrl содежрит URL шаблона, а controller – имя контроллера.

Метод $routeProvider.otherwise позволяет установить параметры для всех остальных вариантов URL.

Для того чтобы роутер заработал нам нужно выполнить ещё один шаг – указать область на странице, для которой будут устанавливаться контроллеры. Делается это с помощью директивы ng-view. В нашем случае разметка выглядит так:

<div class="row-fluid">
    <div class="span9 map" pm-google-map></div>

    <div class="span3" ng-view></div>
</div>

Роутер заменит ng-view на соответствующий контроллер и вставит шаблон внутрь данного тега. Например, для URL #/list мы получим что-то вроде:

<div class="span3" ng-controller="PlacesListController">… содержимое шаблона partials/list.html …</div>

Теперь нам нужно написать контроллеры для списка и формы.

Контроллер списка

Файл js/controllers/list.js

app.controller('PlacesListController'
    , ['$scope', '$rootScope', 'Places', '$dialog', 'lang'
    , function($scope, $rootScope, Places, $dialog, lang) {

    $scope.curLang = lang;

    $scope.places = Places.getAll();

    $rootScope.$on('places:updated', function() {
        $scope.places = Places.getAll();
    });

    $scope.isEmpty = function() {
        if ($scope.places.length === 0) {
            return true;
        }
        return false;
    }

    $scope.confirm = function(place) {
        var title = 'Confirm';
        var msg = 'Do you really want to delete this place?';
        var btns = [{result:'no', label: 'No'}, {result:'yes', label: 'Yes', cssClass: 'btn-danger'}];

        $dialog.messageBox(title, msg, btns)
            .open()
            .then(function(result){
                if (result === 'yes') {
                    $scope.delete(place);
                }
            });
    }

    $scope.delete = function(place) {
        Places.delete(place);
    }

    $scope.show = function(place) {
        $rootScope.$broadcast('place:show', place);
    }
}]);

Здесь для создания контроллера используется метод controller, который получает название контроллера, список зависимостей и функцию, которая и создаёт контроллер. Т.е. контроллер в любом случае создаётся с помощью JS функции, но в отличие от первого варианта, показанного в начале статьи, данный контроллер находится внутри модуля приложения и не «засоряет» глобальное пространство имён.

В списке зависимостей мы указали:

• Сервис Places, который создали в 4-ой части. Напомню, этот сервис выполняет всю работу по взаимодействию с серверной частью приложения. И с помощью его методом мы можем прочитать, изменить или создать объект.
• Объект $scope – его автоматически создаёт AngularJS и через него осуществляется передача данных в представление.
• $rootScope – глобальный scope, который мы используем для отправки и получения событий.
• $dialog – сторонний компонент, который мы используем для создания модального окна. Используется для подтверждения удаления объекта.
• lang – содержит название текущего языка.

Т.к. контроллер отвечает за отображение списка объектов, то мы читаем их с помощью метода Places.getAll() и присваиваем свойству $scope.places (чтобы к ним могло получить доступ представление).

Когда список объектов изменяется, сервис Places инициирует событие places:updated. Поэтому мы добавляем соответствующий обработчик – строки 9-11.

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

• $scope.isEmpty – проверяет, является ли список объектов пустым.
• $scope.confirm – открывает диалог с просьбой подтвердить удаление объекта. И если подтверждение получено, вызывает метод $scope.delete.
• $scope.delete – вызывает Places.delete для удаления объекта.
• $scope.show – отправляет событие place:show, уведомляющее другие компоненты о том, что пользователь кликнул на объекте.

Теперь рассмотрим шаблон partials/list.html

<div id="placesList">

    <ul>
        <li ng-repeat="place in places">
            <a href="" ng-click="show(place)">{{ place.p_title }}</a>
            <a href="" ng-click="confirm(place)" class="pull-right" rel="tooltip" title="{{ 'DELETE' | translate }}"><i class="icon-trash"></i></a>
            <a href="places/index#/edit/{{place.id}}" class="pull-right" rel="tooltip" title="{{ 'UPDATE' | translate }}"><i class="icon-pencil"></i></a>
        </li>
    </ul>

    <span ng-show="isEmpty()">{{ 'NO_PLACES' | translate }}</span>

    <div>
        <a href="places/index#/add" class="btn btn-success">{{ 'ADD_PLACE' | translate }}</a>
    </div>
</div>

Для вывода списка объектов используем директиву ng-repeat (аналог foreach цикла). В качестве её значения указываем place in places. Значение places – это массив, который мы сохранили в $scope при инициализации контроллера.

Сразу после старта приложения $scope.places будет пуст, т.к. сервис Places вряд ли успеет получить от сервера ответ. Поэтому список будет пустым, и мы увидим соответствующее сообщение (строка 11). Обратите внимание на директиву ng-show. Она устанавливает CSS правило display в зависимости от результата, который возвращает функция isEmpty.

Как только сервис Places получит ответ сервера, он инициирует событие places:updated. Наш контроллер «слушает» это событие и как только оно появляется, ещё раз вызывает метод getAll сервиса. Т.е. в $scope.places будет сохранён массив с объектами. Напомню, $scope.places является моделью и AngularJS отслеживает изменения в её состоянии. Когда $scope.places изменяется, автоматически запускается рендеринг представления, связанного с данным контроллером. В результате будет сформирован список объектов с кнопками «Изменить» и «Удалить».

Обратите внимание на то, как формируется ссылка «Изменить» (строка 7). В атрибуте href мы указываем places/index#/edit/{{place.id}}, где place.id – id текущего объекта. В результате, клик по этой ссылке приведёт к срабатыванию роутера, который загрузит PlacesFormController с соответствующим шаблоном. Аналогично работает и клик по кнопке «Создать объект».

Контроллер формы

app.controller('PlacesFormController'
    , ['$scope', '$rootScope', 'Places', '$routeParams', '$location'
    , function($scope, $rootScope, Places, $routeParams, $location) {

    $scope.place = {};
    $scope.isNew = true;
    $scope.saving = false;

    $scope.showErrors = false;
    $scope.errors = [];

    if ($routeParams.placeId !== undefined) {
        $scope.place = Places.get($routeParams.placeId);
        if (undefined === $scope.place || null === $scope.place) {
            //place with this id not found
            $location.path('/add').replace();
        }
        $scope.isNew = false;
    }

    $scope.save = function() {
        Places.save($scope.place);
        $scope.saving = true;
        $scope.showErrors = false;
    }

    $rootScope.$on('place:updated', function() {
        $scope.saving = false;
    });

    $rootScope.$on('place:added', function(event, data) {
        $scope.saving = false;
        $location.path('/list').replace();
    });

    $rootScope.$on('place:error', function(event, data) {
        $scope.showErrors = true;
        $scope.errors = [];
        angular.forEach(data.errors, function(error) {
            if (typeof error == 'object') {
                angular.forEach(error, function(err) {
                    $scope.errors.push(err);
                });
            }
            else {
                $scope.errors.push(error);
            }
        });
        $scope.saving = false;
    });

    $rootScope.$on('map:pointSelected', function(event, data) {
        $scope.place.p_lat = data.p_lat;
        $scope.place.p_lng = data.p_lng;
    });
}]);

Форма может использоваться как для создания нового объекта, так и для редактирования существующего. Модель объекта храниться в $scope.place. Во время инициализации контроллер проверяет, указан ли id объекта и пытается его получить (строки 12-19). Если объект найден, $scope.isNew будет равен false.

Процесс сохранения объекта. Когда пользователь нажимает кнопку «Создать», приложение (сервис Places) отправляет асинхронный запрос с данными объекта. Ответ на этот запрос придёт через некоторое время, поэтом нам важно исключить возможность повторного нажатия на кнопку «Создать». Кроме того, пользователь должен видеть, что процесс сохранения запущен.

Для этого в методе $scope.save мы устанавливаем $scope.saving = true; (строка 23). Также устанавили обработчики событий place:updated и place:added (строки 27-34). Эти события инициирует сервис Places, когда получает сообщения об успешном обновлении или создании объекта. Обработчики устанавливают $scope.saving = false. Теперь в шаблоне формы мы можем использовать $scope.saving для того, чтобы показать пользователю, например, картинку с загрузчиком.

<span ng-show="saving"><img ng-src="images/ajax-loader.gif" alt="loader"></span>

Во время сохранения может произойти какая-нибудь ошибка. Информацию о ней мы должны показать пользователю. Для этого устанавливаем обработчик place:error. Это также событие сервиса Places, вместе с которым передаются описания ошибок. Описания мы сохраняем в массиве $scope.errors. Таким образом, мы сможем отобразить их в шаблоне.

Обработчик события map:pointSelected (строки 52-55) предназначен для установки координат. Это событие инициирует директива (её мы рассмотрим в следующей части) когда пользователь кликает по карте. Обработчик просто сохраняет соответствующие свойства объекта $scope.place.

Шаблон формы

Файл partials/form.html

<form name="placeForm" novalidate>

    <h4 ng-show="isNew">{{ 'CREATE_PLACE' | translate }}</h4>
    <h4 ng-hide="isNew">{{ 'UPDATE_PLACE' | translate }}</h4>

    <label>{{ 'TITLE' | translate }} *:<br><input type="text" ng-model="place.p_title" name="pTitle" required class="span12">
    <span class="text-error" ng-show="placeForm.$dirty && placeForm.pTitle.$error.required">{{ 'FIELD_NOT_EMPTY' | translate }}.</span></label>

    <label>{{ 'DESCRIPTION' | translate }} (<a href="http://daringfireball.net/projects/markdown/" target="_blank">Markdown</a> {{ 'ENABLED' | translate }}):<br>
        <textarea ng-model="place.p_description" class="span12"></textarea>
    </label>

    <label for="placeLat">{{ 'LATITUDE' | translate }}:</label>
    <div class="input-append">
        <input type="text" id="placeLat" ng-model="place.p_lat" placeholder="{{ 'CLICK_ON_THE_MAP' | translate }}" disabled>
        <span class="add-on">&deg;</span>
    </div>

    <label for="placeLng">{{ 'LONGITUDE' | translate }}:</label>
    <div class="input-append" class="span12">
        <input type="text" id="placeLng" ng-model="place.p_lng" placeholder="{{ 'CLICK_ON_THE_MAP' | translate }}" disabled>
        <span class="add-on">&deg;</span>
    </div>

    <div class="alert alert-error" ng-show="showErrors">
        <button type="button" class="close" data-dismiss="alert">&times;</button>
        <h4>{{ 'ERRORS' | translate }}:</h4>
        <ul>
            <li ng-repeat="error in errors">{{ error }}</li>
        </ul>
    </div>

    <button type="submit" ng-disabled="placeForm.$invalid || saving" ng-click="save()" class="btn btn-primary">
        <span ng-show="isNew">{{ 'CREATE' | translate }}</span>
        <span ng-hide="isNew">{{ 'UPDATE' | translate }}</span>
        <span ng-show="saving"><img ng-src="images/ajax-loader.gif" alt="loader"></span>
    </button>

    <a href="places/index#/list" class="btn">{{ 'CANCEL' | translate }}</a>

</form>

Заголовков формы у нас два (Создать или Изменить форму). Мы выбираем нужный с помощью директив ng-show и ng-hide (строки 3, 4). Эти директивы можно рассматривать как аналог условий.

Разметка формы достаточно стандартная. Используются классы Twitter Bootstrap. Значения поля формы получают напрямую из моделей с помощью директив ng-model. В значении директивы нужно указать модель или её свойство. Например, модель place ($scope.place) является объектом, поэтому для поля с заголовком объекта мы указываем ng-model="place.p_title".

Использование ng-model автоматически подключает двунаправленное связывание данных. Т.е. если пользователь изменит значение в поле, оно будет сразу же записано в $scope.place. И наоборот, любое изменение $scope.place или его атрибутов будет отображаться в соответствующем поле. Таким образом, в явном виде задавать атрибут value для тегов input не нужно.

Отображение ошибок формы

Мы уже рассмотрели контроллер формы и знаем, что он обрабатывает сообщение place:error. Но это сообщение передаёт список ошибок сервера, т.е. пользователь увидит его только после того, как попытается сохранить форму. Но мы можем выполнить проверку с помощью JavaScript, и AngularJS предоставляет довольно удобный механизм для этих целей.

Для каждой формы автоматически создаётся объект с названием, совпадающим со значением атрибута name формы. Этот объект хранит информацию о состоянии формы и наличии ошибок в её полях.

Состояний всего пять:

• $pristine – пользователь не работал с формой;
• $dirty – пользователь вводил какую-то информацию;
• $valid – принимает значение true, если валидация прошла без ошибок для всех полей;
• $invalid – true если хотя бы одно из полей не валидно;
• $error – хеш, содержащий ссылки на все не валидные поля.

В стандартном варианте AngularJS поддерживает проверку большинства распространённых полей (text, number, url, email, radio, checkbox), а для установки правил проверки используются атрибуты – required, pattern, minlength, maxlength, min, max.

Рассмотрим в качестве примера поле с названием объекта.

<input type="text" ng-model="place.p_title" name="pTitle" required>
<span ng-show="placeForm.$dirty && placeForm.pTitle.$error.required">{{ 'FIELD_NOT_EMPTY' | translate }}.</span>

Для поля мы установили атрибут required, т.е. поле является обязательным. А тег span будет отображаться, если пользователь работал с формой placeForm.$dirty == true и оставил название пустым placeForm.pTitle.$error.required == true. Без placeForm.$dirty сообщение об ошибке отображалось бы ещё до того, как пользователь начал ввод данных.

Тестирование контроллеров

В прошлой части мы рассматривали тестирование сервисов с помощью фреймворка Jasmine. Принцип тестирования контроллеров очень похож, но есть нюансы. Рассмотрим их на примере тестов для списка объектов (файл test/unit/js/controllers/list.spec.js).

describe('Places List controller', function() {
    var scope, rootScope, dialog, routeParams, controller, places;

    beforeEach(function() {
        module('personalmaps', function($provide) {
            $provide.value('lang', '');
        });

        inject(function($rootScope, $controller, $routeParams, $dialog, lang) {
            rootScope = $rootScope;
            scope = $rootScope.$new();
            dialog = $dialog;
            routeParams = $routeParams;
            controller = $controller;

            dialog = {
                messageBox: function() {}
            }
            spyOn(dialog, 'messageBox').andReturn({
                open: function() {
                    return {
                        then: function() {}
                    }
                }
            });

            places = jasmine.createSpyObj('Places', ['getAll', 'get', 'add', 'update', 'delete', 'save']);
        });
    });

    it('should call getAll', function() {
        controller('PlacesListController', {$scope: scope, $rootScope: rootScope, 'Places': places, $routeParams: routeParams, $dialog: dialog});
        expect(places.getAll).toHaveBeenCalled();
    });

    it('should call getAll on places:updated event', function() {
        controller('PlacesListController', {$scope: scope, $rootScope: rootScope, 'Places': places, $routeParams: routeParams, $dialog: dialog});
        rootScope.$emit('places:updated');
        expect(places.getAll.calls.length).toEqual(2);
    });

    it('should open dialog on confirm call', function() {
        controller('PlacesListController', {$scope: scope, $rootScope: rootScope, 'Places': places, $routeParams: routeParams, $dialog: dialog});
        scope.confirm();
        expect(dialog.messageBox).toHaveBeenCalled();
    });
});

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

Для этого мы используем функцию beforeEach.

В первую очередь создаём модуль приложения (строки 5-7). Затем с помощью inject (строки 9-29) подключаем зависимости. Здесь есть нюансы. Подключение стандартных компонентов AngularJS (вроде $rootScope) мы рассматривали в прошлой части. Но сейчас мы тестируем контроллер и для него нам нужно создать scope. В самом приложении это происходит автоматически, когда Angular обрабатывает директиву ng-controller или ng-view, но при тестировании это нужно сделать вручную:

scope = $rootScope.$new();

Кроме того, в нашем контроллере используется $dialog (создаёт окно с просьбой подтвердить удаление). Наш контроллер вызывает методы этого компонента и нам нужно протестировать, что эти методы вызываются правильно. Но использовать настоящий $dialog не желательно, т.к. нам нужно зафиксировать только факт вызова метода, работа компонента нас сейчас не интересует. Поэтому мы создаём mock объект, который содержит функцию messageBox

dialog = {
    messageBox: function() {}
}

и с помощью функции spyOn указываем Jasmine, что нужно отслеживать вызовы messageBox

spyOn(dialog, 'messageBox').andReturn({
	open: function() {
		return {
			then: function() {}
		}
	}
});

Тут же указываем, какой объект должен вернуть вызов messageBox. Это тоже заглушка, содержащая функции open и then. Она необходима, потому что в контроллере (list.js, строки 25-31) мы эти функции вызываем.

Также нам нужно отследить, как контроллер вызывает методы сервиса Places. Реальный сервис мы не используем (для него у нас тесты написаны), а создаём mock объект.

places = jasmine.createSpyObj('Places', ['getAll', 'get', 'add', 'update', 'delete', 'save']);

В первом параметре функции createSpyObj указываем имя сервиса, во втором – массив с именами методов.

Теперь можно написать тесты (строки 31-46).

В каждом тесте мы сначала создаём контроллер

controller('PlacesListController', {$scope: scope, $rootScope: rootScope, 'Places': places, $routeParams: routeParams, $dialog: dialog});

и затем имитируем поведение пользователя. Например, вызываем метод confirm и проверяем, что в ответ контроллер вызвал метод dialog.messageBox.

scope.confirm();
expect(dialog.messageBox).toHaveBeenCalled();

Точно также проверяем реакцию на события.

rootScope.$emit('places:updated');
expect(places.getAll.calls.length).toEqual(2);

Метод getAll вызывался дважды, т.к. в первый раз он был вызван при создании контроллера, а во второй – при получении события places:updated.

Тесты для формы я описывать не буду, т.к. они аналогичны и вы можете посмотреть их на GitHub.

В следующей части мы рассмотрим создание директивы для подключения Google Map.

Если есть вопросы или замечания, пишите.

Содержание

The post Personal Maps: контроллеры и представления в AngularJS. Часть 6. first appeared on SimpleCoding.org.

Наш сервис использует несколько встроенных компонентов Angular ($rootScope и $http) и не зависит от остальных компонентов приложения. С дугой стороны, остальные компоненты (контроллеры, директивы) используют методы сервиса. Любые изменения в названиях или количестве аргументов этих методов приведут к тому, что придется изменять все компоненты, которые их используют. Таким образом, полезно протестировать работу сервиса перед разработкой остальной части приложения. Этот подход можно использовать не только по отношению к сервисам – сначала разрабатываем и тестируем компоненты с наименьшим числом зависимостей, а затем собираем из них всё приложение.

Примечание. Исходный код размещён на GitHub, также доступна демоверсия приложения.

Прежде чем переходить к написанию тестов, давайте определим общие требования к тестированию.

Написание тестов занимает время. И полностью автоматизировать этот процесс нельзя, но его можно сократить за счёт использования библиотек и автоматизации запуска тестов. Также очень полезно иметь возможность запуска тестов из консоли, особенно если вы используете какой-нибудь CI (Continuous Integration) сервер.

Для решения всех перечисленных задач мы используем:

• Фреймворк Jasmine. В принципе, его можно заменить на какой-нибудь другой, но в примерах в документации AngularJS используется именно он. Кроме того, Jasmine в любом случае является одним из самых популярных.
• Утилиту для запуска тестов Karma test runner. Она позволяет запускать тесты из консоли, следит за изменениями файлов и перезапускает тесты при их изменениях.
• PhantomJS – так называемый headless браузер, т.е. без графического интерфейса. Работает на движке webkit. Пока вы разрабатываете локально, вам не принципиально, какой браузер использовать, но на linux-сервере без иксов обычные браузеры просто не запустятся.

Установка и настройка окружения

В Yii фреймворке тесты находятся в папке protected/tests. Нас это размещение вполне устраивает.

Т.е. структура папок будет такой:

protected/
	tests/
		libs/
			//дополнительные JS библиотеки
		unit/
			js/
				controllers/
				services/
				directives/
		karma.conf.js //файл конфигурации Karma

Установка Karma test runner

Для работы Karma необходим Node.JS. Скачайте инсталлятор для вашей операционной системы и просто следуйте инструкциям. Если вы устанавливаете Node из исходников, то вам потребуется добавить в переменную PATH путь к исполняемым файлам.

Karma устанавливается с помощью команды:

npm install -g karma

npm скачает все необходимые файлы, и вы сможете выполнять из консоли команды вроде

karma start

После этого, необходимо создать переменные окружения, в которых будет указано размещение браузеров, которые должна использовать Karma. Например, для Google Chrome и PhantomJS нужно создать следующие переменные.

CHROME_BIN="полный_путь\chrome.exe"
PHANTOMJS_BIN="полный_путь\phantomjs.exe"

Настраиваем Karma test runner

Технически Karma запускает свой web сервер, который по-умолчанию использует порт 9876. Это даёт возможность разместить файлы тестов вне DOCUMENT_ROOT сервера, который используется для приложения.

Создадим конфигурационный файл karma.conf.js с помощью следующей команды

karma init karma.conf.js

Эту команду необходимо выполнить из папки protected/tests. В результате будет создан файл с настройками по-умолчанию. Нам нужно их немного изменить для того, чтобы утилита знала, где находятся файлы проекта и файлы тестов.

// base path, that will be used to resolve files and exclude
basePath = '';

// list of files / patterns to load in the browser
files = [
  JASMINE,
  JASMINE_ADAPTER,
  'http://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js',
  'http://maps.googleapis.com/maps/api/js?sensor=false',
  '../../js/markdown.js',
  'http://ajax.googleapis.com/ajax/libs/angularjs/1.0.7/angular.min.js',
  'libs/angular-mocks.js',
  '../../js/ui-bootstrap-tpls-0.4.0.min.js',
  '../../js/angular-translate.min.js',
  'unit/js/bootstrap.js',
  '../../js/app.js',
  '../../js/controllers/*.js',
  '../../js/services/*.js',
  '../../js/directives/*.js',
  'unit/js/controllers/*.spec.js',
  'unit/js/services/*.spec.js',
  'unit/js/directives/*.spec.js'
];

// list of files to exclude
exclude = [];

// test results reporter to use
// possible values: 'dots', 'progress', 'junit'
reporters = ['progress'];

// web server port
port = 9876;

// cli runner port
runnerPort = 9100;

// enable / disable colors in the output (reporters and logs)
colors = true;

// level of logging
// possible values: LOG_DISABLE || LOG_ERROR || LOG_WARN || LOG_INFO || LOG_DEBUG
logLevel = LOG_DEBUG;

// enable / disable watching file and executing tests whenever any file changes
autoWatch = true;

// Start these browsers, currently available:
// - Chrome
// - ChromeCanary
// - Firefox
// - Opera
// - Safari (only Mac)
// - PhantomJS
// - IE (only Windows)
browsers = ['Chrome'];

// If browser does not capture in given timeout [ms], kill it
captureTimeout = 60000;

// Continuous Integration mode
// if true, it capture browsers, run tests and exit
singleRun = false;

Прежде всего, указываем размещение файлов проекта в массиве files (строки 5-23).
JASMINE и JASMINE_ADAPTER подключают фреймворк Jasmine вместе с адаптером для Karma (необходимые файлы входят в дистрибутив Karma).
Затем мы подключаем все сторонние библиотеки, которые используются приложением. Их порядок должен соответствовать последовательности их подключения на странице приложения.

Кроме того, нам понадобиться библиотека angular-mocks.js (строка 12, найти эту библиотеку можно здесь), которая содержит mock-объекты для встроенных сервисов AngularJS. С их помощью мы, например, сможем тестировать работу сервиса $http, не отправляя реальных запросов на сервер (об этом чуть ниже).

Также подключаем скрипт tests/unit/js/bootstrap.js. В нём мы создадим JS объекты, которые при работе приложения устанавливаются с помощью PHP кода. Например, язык приложения указывается в конфигурационном файле Yii main.php. При формировании страницы приложения, значение этого параметра присваивается JS переменной lang. Это позволяет указать языковые настройки только один раз, а не отдельно для серверной и клиентской части. Но в результате, переменная lang оказывается недоступной для тестов, т.к. Karma формирует страницу самостоятельно, без использования нашего PHP кода.

Наконец, мы подключаем JavaScript файлы приложения и тесты (строки 17-22). Обратите внимание, мы можем использовать * для того, чтобы подключить все файлы в папке.

Из остальных параметров мы установим для уровня логгирования значение LOG_DEBUG (строка 43) и укажем, какой браузер Karma должна использовать (строка 56). Вообще, LOG_DEBUG использовать не обязательно. Просто в этом режиме в консоль выводятся сообщения о подключении JS файлов, и если вы допустите ошибку при формировании массива files, то так будет проще её найти.

Параметр singleRun = false (строка 63) означает, что после запуска Karma будет отслеживать изменения и автоматически перезапускать тесты.

Запуск Karma выполняется с помощью команды

karma start

или

karma start karma.conf.js

После её выполнения запустится браузер, а в консоли вы увидите результаты выполнения тестов.

Karma test runner мы настроили. Теперь напишем тесты.

Тестирование сервиса Places

Создадим файл tests/unit/js/services/places.spec.js

describe('Places service', function() {
	...
});

Функция describe описывает набор тестов. В первом параметре указывается название набора, а во втором – функция, содержащая тесты.

Тест состоит из набора спецификаций (создаются с помощью функции

it

), которые содержат «ожидания» (вызовы функции expect). Например, простой тест может выглядеть так:

describe('Places service', function() {
    it('returns particular place', function() {
        expect(true).toEqual(true);
    });
});

Но в нашем случае ситуация сложнее. Нам необходимо тестировать код, который отправляет AJAX запросы. Если тест будет отправлять реальные запросы, то возникнет ряд проблем:

• Время выполнения теста увеличится, т.к. он будет ждать ответы сервера.
• Результаты сервера могут зависеть от состояния базы данных. Можно, конечно, создать специальную базу с тестовыми данными, но процесс тестирования в любом случае станет сложнее.
• Серверная часть может оказаться в нерабочем состоянии, например, потому что она просто не полностью написана и сама содержит ошибки.

Поэтому нам важно запускать тесты автономно. И в этом нам поможет библиотека angular-mocks.js. Она содержит mock-объект $httpBackend, который эмулирует работу сервиса $http. Рассмотрим, как его подключить и использовать.

describe('Places service', function() {
    var $httpBackend, injector;

    var response = [
        {
            'id': 1,
            'p_title': 'title 1',
            'p_description': 'desc 1',
            "p_lng": 50.4,
            "p_lat": 30.76,
            'p_user': 1
        },
		...
    ];

    var newPlace = {
        'id': '3',
        'p_title': 'title 3',
        'p_description': 'desc 3',
        'p_lng': '50.4',
        'p_lat': '30.76',
        'p_user': 1
    };

    beforeEach(function() {
        module('personalmaps', function($provide) {
            $provide.value('lang', '');
        });

        inject(function($injector, lang) {
            injector = $injector;
            $httpBackend = $injector.get('$httpBackend');
            $httpBackend.when('GET', 'api/places').respond(response);
            $httpBackend.when('POST', 'api/places').respond(newPlace);
            $httpBackend.when('PUT', 'api/places/2').respond(response[1]);
            $httpBackend.when('PUT', 'api/places/5').respond(response[1]);
            $httpBackend.when('DELETE', 'api/places/2').respond('');
            $httpBackend.when('GET', 'foo/bar.json?lang=en').respond('[]');
        });
    });

    afterEach(function() {
        $httpBackend.verifyNoOutstandingExpectation();
        $httpBackend.verifyNoOutstandingRequest();
    });

    it('calls api/places', function() {
        $httpBackend.expectGET('api/places');
        injector.get('Places');
        $httpBackend.flush();
    });

	...
});

Перед запуском тестов мы создаём массивы с тестовыми данными, которые будет возвращать $httpBackend (строки 4-23). Формат этих данных должен совпадать с форматом ответа реального сервера.

Затем с помощью функции beforeEach настроим $httpBackend. Эта функция вызывается перед каждым вызовом it.

Тут есть несколько важных моментов. При создании приложения AngularJS выполняет довольно много работы, которую в случае использования тестов мы должны выполнить самостоятельно. Перед каждым тестом мы создаём модуль (строки 26-28) и вызываем функцию inject, которая определена в файле angular-mocks.js. Она создаёт объект $injector, с помощью которого можно использовать механизм внедрения зависимостей (Dependency injection).

При создании компонентов AngularJS мы указываем списки зависимостей. Например, при создании нашего сервиса мы так подключили $http и $rootScope. Но наш тест ничего не знает о том, что нам нужен $httpBackend и сам сервис Places. $injector как раз и позволяет подключить их, т.е. «внедрить» в наш тест.

Посмотрите, в строке 32 мы использовали метод $injector.get для того, чтобы получить $httpBackend, а в строке 49 мы с помощью injector подключили сервис Places.

После того, как $httpBackend подключён, его нужно настроить. Т.е. указать какие запросы он будет обрабатывать, и какие ответы отправлять.

Например,

$httpBackend.when('GET', 'api/places').respond(response);

означает, что если где-нибудь в приложении будет выполнен вызов

$http({method: 'GET', url: 'api/places'})

то $httpBackend его перехватит и вернёт значение response.

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

Теперь взгляните на код теста (строки 47-51). Он проверяет, что сразу после создания приложения сервис Places отправляет запрос к api/places, который должен вернуть полный список объектов.

Мы вызываем

$httpBackend.expectGET('api/places');

т.е. указываем, что ожидаем отправки AJAX-запроса. Затем подключаем сервис

injector.get('Places');

в результате AngularJS выполнит функцию сервиса Places (файл public_html/js/services/places.js), которая отправит запрос. Т.к. мы хотим получить результат сразу, то вызываем

$httpBackend.flush();

Напомню, AJAX запросы являются асинхронными, поэтому ответ может прийти в любой момент времени. При вызове flush все отправленные запросы будут завершены и вернут ответ. Таким образом, ответ на запрос к api/places будет получен во время выполнения теста и «ожидание» (expectGET) будет успешным.

После завершения теста Jasmine автоматически вызовет функцию afterEach (строки 42-45). В ней мы с помощью методов verifyNoOutstandingExpectation и verifyNoOutstandingRequest закрываем все «ожидания» и запросы. Если мы этого не сделаем, то выполнение одного из тестов может повлиять на работу остальных, а этого допускать нельзя.

Как видите, тестирование асинхронного JavaScript кода довольно не тривиальная задача, даже с использованием фреймворков. Но, по-сути, вам нужно научиться использовать несколько дополнительных объектов, и хотя бы в общих чертах разобраться в принципе подключения объектов в Angular (это желательно сделать не только ради тестов). После этого вы увидите, что все тесты используют очень похожий код. Например, рассмотрим следующий тест.

it('returns null for unknown places', function() {
	var places = injector.get('Places');
	$httpBackend.flush();
	expect(places.get('43534535')).toBe(null);
});

Он проверяет, что метод Places.get возвращает null если объект с заданным id не найден. Мы подключаем сервис Places. Сервис выполняет запрос и в ответ получает массив response. Посмотрите, в этом массиве нет объекта с id равным 43534535. Затем вызываем $httpBackend.flush(), т.е. обеспечиваем получение ответа до того, как будет выполнена следующая строка. И с помощью метода places.get ищем объект с id == 43534535. Т.к. такого объекта нет, то мы ожидаем, что метод вернёт null.

Остальные тесты работают аналогично, вы можете посмотреть их на GitHub.

На этом, мы завершаем работу с сервисом и в следующий раз рассмотрим контроллер и представления.

Если есть вопросы или замечания, пишите.
Успехов!

Содержание

The post Personal Maps: тестирование AngularJS сервиса с помощью Jasmine и Karma. Часть 5. first appeared on SimpleCoding.org.