Использование WordPress Heartbeat API

Автор: Pippin Williamson.
Оригинал: Using the WordPress Heartbeat API.

Замечание: перевод вольный, некоторые высказывания заменены на более понятные (на мой взгляд), и добавлены примечания. Все примечания опираются на WP 4.2.2.

— Г.К.

В WordPress 3.6 был введён новый API, называемый «WordPress Heartbeat». На нём основано множество сделанных в этой версии изменений, включая более развитую систему отслеживания ревизий, улучшенное управление пользовательскими сессиями и многое другое. Я собираюсь показать краткий пример использования этого API.

Что такое Heartbeat API?

Heartbeat API очень точно назван (heartbeat — сердцебиение). Его можно сравнить с сердцем: точно как человеческое сердце, бьющееся и вызывающее пульсацию в сосудах, Heartbeat API издаёт «пульсации» (технически называемые «тиками» — tick), которые затем улавливаются и обрабатываются с целью периодического выполнения каких-либо действий.

Одной из положительных сторон Heartbeat API является то, что он почти полностью реализован на JavaScript — это позволяет действовать не только на стороне сервера, но и на просматриваемой пользователем странице. Например, используя Heartbeat API можно синхронизировать информацию, отображённую браузером, со значениями в базе данных, иногда меняющимися. Реализация подобных вещей состоит из двух частей:

1. обработки события «send» — начала пульса — при которой отправляемая серверу информация снабжается к.-л. данными (возможно, прежде полученными из БД);
2. обработки события «tick» — для получения данных и модификации отображаемой страницы (и/или других действий) силами JavaScript.

В качестве реального работающего примера можно привести плагин Easy Digital Downloads, где мы в реальном времени обновляем виджет админской консоли, отображающий информацию по продажам. После каждой новой сделки информация в БД меняется, а отображаемая в виджете статистика автоматически обновляется через некоторое время.

Примечание: интервал обновления варьируется от 15 до 120 сек., по умолчанию — 60.

Процесс обновления статистики выглядит примерно так:

1. обработчик события 'heartbeat-send', возникающего при отправке «пульса», добавляет в отправляемые данные определённый ключ, заставляющий сервер включить в ответ информацию по продажам;
2. обработчик события 'heartbeat-tick', происходящего при получении от сервера ответного «пульса», разбирает полученные данные и, если запрошенная в п.1 информация имеется, переходит к п.3;
3. новые значения извлекаются из пришедших данных и вносятся в содержимое виджета статистики, включается индикация изменений.

Взглянем на реализующий эти пункты код.

Во-первых, мы должны подключить JS-скрипт с Heartbeat API:

PHP

<?php // загрузка JS-скрипта с Heartbeat API function edd_heartbeat_enqueue( $hook_suffix ) { // включаем в вывод страницы скрипт с браузерной частью Heartbeat API wp_enqueue_script( 'heartbeat' ); add_action( 'admin_print_footer_scripts', 'edd_heartbeat_footer_js', 20 ); } add_action( 'admin_enqueue_scripts', 'edd_heartbeat_enqueue' );

1 2 3 4 5 6 7 8

<?php // загрузка JS-скрипта с Heartbeat API function edd_heartbeat_enqueue( $hook_suffix ) {     // включаем в вывод страницы скрипт с браузерной частью Heartbeat API     wp_enqueue_script( 'heartbeat' );     add_action( 'admin_print_footer_scripts', 'edd_heartbeat_footer_js', 20 ); } add_action( 'admin_enqueue_scripts', 'edd_heartbeat_enqueue' );

Функция выдачи нашего скрипта, использующего Heartbeat API, повешена на хук 'admin_print_footer_scripts' — скрипт будет выведен в футере консоли администрирования. Происходит это следующим образом:

PHP

<?php // Встраиваем наш скрипт в футер консоли администрирования WordPress function edd_heartbeat_footer_js() { global $pagenow; // только если находимся на самой консоли if( 'index.php' != $pagenow ) return; ?> <script> (function($){ // обрабатываем отправку пульса: $(document).on('heartbeat-send', function(e, data) { data['edd_heartbeat'] = 'dashboard_summary'; }); // ловим событие "heartbeat-tick" на элементе $(document): $(document).on( 'heartbeat-tick', function(e, data) { // продолжаем, только если ответ содержит требуемые данные if ( ! data['edd-payment-count'] ) return; // убедимся, что всё работает, заглянув в консоль console.log( data['edd-payment-count'] ); // обновим информацию по продажам и выделим её жирным шрифтом $('.edd_dashboard_widget .b.b-sales') .text( data['edd-payment-count'] ) .css( 'font-weight', 'bold' ); // удаляем выделение через 2 секунды setTimeout(function(){ $('.edd_dashboard_widget .b.b-sales') .css( 'font-weight', 'normal' ); }, 2000); }); }(jQuery)); </script> <?php }

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43

<?php // Встраиваем наш скрипт в футер консоли администрирования WordPress function edd_heartbeat_footer_js() {     global $pagenow;       // только если находимся на самой консоли     if( 'index.php' != $pagenow )         return; ?>     <script>     (function($){           // обрабатываем отправку пульса:         $(document).on('heartbeat-send', function(e, data) {             data['edd_heartbeat'] = 'dashboard_summary';         });           // ловим событие "heartbeat-tick" на элементе $(document):         $(document).on( 'heartbeat-tick', function(e, data) {               // продолжаем, только если ответ содержит требуемые данные             if ( ! data['edd-payment-count'] )                 return;               // убедимся, что всё работает, заглянув в консоль             console.log( data['edd-payment-count'] );               // обновим информацию по продажам и выделим её жирным шрифтом             $('.edd_dashboard_widget .b.b-sales')                 .text( data['edd-payment-count'] )                 .css( 'font-weight', 'bold' );               // удаляем выделение через 2 секунды             setTimeout(function(){                 $('.edd_dashboard_widget .b.b-sales')                     .css( 'font-weight', 'normal' );             }, 2000);           });     }(jQuery));     </script> <?php }

Почти вся «магия» происходит здесь. В строках 13-16 мы добавляем ключ 'edd_heartbeat' и устанавливаем его значение в 'dashboard_summary', определяя тем самым данные, которые требуются нам от сервера (код формирования ответа сервера — чуть ниже).

Обработчик ответа сервера (тика) находится в строках 18-39. С каждым тиком приходит массив данных, в котором мы отыскиваем нужную нам информацию. В этом случае data['edd-payment-count'] просто содержит целое, являющееся общим количеством продаж в системе. Мы можем взять это целое и внести изменения в текст виджета. Для удобства добавлена смена стилей, заставляющая количество продаж «пульсировать» при каждом обновлении.

PHP

<?php // фильтр данных, отправляемых в ответ на heartbeat-tick function edd_heartbeat_received( $response, $data ) { // отправляем только запрашиваемые данные if( $data['edd_heartbeat'] == 'dashboard_summary' ) { // получаем счётчик платежей $payments = edd_count_payments(); // отправляем количество выполненных платежей $response['edd-payment-count'] = number_format_i18n( $payments->publish ); } return $response; } add_filter( 'heartbeat_received', 'edd_heartbeat_received', 10, 2 );

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

<?php // фильтр данных, отправляемых в ответ на heartbeat-tick function edd_heartbeat_received( $response, $data ) {       // отправляем только запрашиваемые данные     if( $data['edd_heartbeat'] == 'dashboard_summary' ) {           // получаем счётчик платежей         $payments = edd_count_payments();           // отправляем количество выполненных платежей         $response['edd-payment-count'] = number_format_i18n( $payments->publish );       }     return $response; } add_filter( 'heartbeat_received', 'edd_heartbeat_received', 10, 2 );

Заметьте, что первым делом проверяется ключ edd_heartbeat, а данные дополняются при его значении 'dashboard_summary'. Это обеспечивает отправку данных только при необходимости.

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

Вот и всё: это и есть WordPress Heartbeat API.

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

Примечание: чтобы посмотреть на работу плагина с тестом, следует прежде установить и активировать плагин Easy Digital Downloads (легко отыскивается по имени штатным установщиком плагинов /wp-admin/plugin-install.php).

Ещё примечание: по умолчанию обновление происходит раз в минуту, поэтому ждать двухсекундного изменения жирности нулей продаж обременительно долго. Чтобы установить интервал в минимум — 15 секунд — следует добавить в тестовый плагин такой код:

function edd_heartbeat_settings( $settings ) { $settings['interval'] = 15; return $settings; } add_filter( 'heartbeat_settings', 'edd_heartbeat_settings' );

1 2 3 4 5

function edd_heartbeat_settings( $settings ) {     $settings['interval'] = 15;     return $settings; } add_filter( 'heartbeat_settings', 'edd_heartbeat_settings' );