= sfStatistics plugin = `sfStatisticsPlugin` является удобным инструментом для построения отчетов на базе модели проекта с использованием Google Chart API. Плагин содержит: - один модуль - одну вспомогательную библиотеку == Screenshot == [[Image(sfStatistics.png)]] == Limitations == На данный момент модуль работает только с MySQL при группировке данных по дате, т.к. используются встроенные в MySQL функции работы с датой. В дальнейшем планируется включение функционала работы с другими БД. == Installation == Установка в sf 1.1 {{{ $ php symfony plugin:install sfStatisticsPlugin --release=0.1.5 }}} Установка в sf 1.0 {{{ $ php symfony plugin-install http://plugins.symfony-project.com/sfStatisticsPlugin }}} В случае отсутствия PEAR, вы можете скачать последнюю версию плагина в сжатом виде, прикрепленной к wiki-странице плагина и распаковать ее в папку `plugins/` вашего проекта. Сделайте доступным новый модуль в вашем проекте, отредактировав файл `settings.yml`. {{{ // в myproject/apps/frontend/config/settings.yml all: .settings: enabled_modules: [default, sfStatistics] }}} Очистите кэш, чтобы сделать новые классы доступными для автозагрузки: {{{ $ php symfony cc }}} Теперь модуль будет доступен по адресу: {{{ http://myproject/frontend_dev.php/sfStatistics }}} == Взаимодействие с модулем `sfStatistics` == Сразу после установки модуль плагина не отображает никаких отчетов. Вы должны сконфигурировать ваш проект, чтобы отобразить статистику на базе ваших данных. Модуль позволяет группировать данные по дате и по значению. Для описания возможностей плагина возьмем следующую модель, хранящую информацию о пользователях и автомобилях, побывавших в нескольких городах: {{{ propel: city: id: title: varchar(255) user: id: name: varchar(255) age: integer city_id: { type: integer, foreignTable: city, foreignReference: id, onDelete: setnull } created_at: car: id: model: varchar(255) car_city: car_id: { type: integer, foreignTable: car, foreignReference: id, onDelete: cascade, primaryKey: true } city_id: { type: integer, foreignTable: city, foreignReference: id, onDelete: cascade, primaryKey: true } created_at: }}} == Группировка данных по дате == Рассмотрим конфигурирование плагина на примере. Внесем в файл app.yml следующие данные: {{{ all: sfStatistics: categories: users: name: Пользователи items: users_registration_by_day: name: Статистика регистраций пользователей по дням model_parameters: class_y: user column_y: id column_x: created_at type: date increment: day aggregation_method: count period_column: created_at chart_parameters: type: line size: 600x300 bg: ffffff label_length: 20 }}} Данная конфигурация создает группу отчетов с названием "Пользователи", содержащую один отчет — "Статистика регистраций пользователей по дням". В разделе model_parameters указываются параметры выборки данных для отчета. Параметр class_y определяет таблицу, из которой производится выборка, column_y — выбираемое поле, column_x определяет поле, по которому производится группировка с шагом increment. В поле aggregation_method указывается функция для группировки. В качестве значения можно указывать любые функции MySQL работы с числами (count, sum, max, avg и т.д.). Параметром period_column определяется поле, фиксирующее в таблице дату занесения записей, по которому будет проводится ограничение выбираемых записей по дате. В результате данные параметры интерпретируются в следующий запрос: {{{ SELECT count(user.id), LEFT(user.created_at, 10) as dte from user group by dte; }}} Поле increment может принимать следующие значения: day, weekday (с пн по вс), week, month, year. В разделе chart_parameters указываются параметры внешнего вида графика. Поле type указывает его тип: line — линейный, pie — круговая диаграмма, bar — столбцевая. В поле size указывается размер графика. Оптимальное соотношение ширины и высоты — 2:1. Помните, что для круговой диаграммы область графика должна быть горизонтально вытянутой в силу особенностей ее построения, поэтому для нее подойдет соотношение 3:1. Поле bg определяет фоновый цвет, а label_length — максимально допустимую длину надписей, если длина надписи больше, то она обрезается до допустимой, а в конце ставится многоточие. == Группировка данных по значению == Для создания отчетов с группировкой по значению в поле type раздела model_parameters должно быть указано value. Дополним файл app.yml информацией об отчетах с группировкой по значению: {{{ all: sfStatistics: categories: users: name: Пользователи items: users_registration_by_day: name: Статистика регистраций пользователей по дням model_parameters: class_y: user column_y: id column_x: created_at type: date increment: day aggregation_method: count period_column: created_at chart_parameters: type: line size: 600x300 bg: ffffff label_length: 20 users_age_by_city: name: Средний возраст пользователя по городам model_parameters: class_y: user column_y: age column_y_measure: годы class_x: city column_x: city_id column_x_foreign: id column_x_title: title type: value aggregation_method: avg chart_parameters: type: bar size: 600x300 bg: ffffff label_length: 20 approximation_factor: 0.1 cars_by_city: name: Статистика машин по городам model_parameters: class_y: car_city column_y: car_id class_x: city column_x: city_id column_x_foreign: id column_x_title: title type: value aggregation_method: count chart_parameters: type: pie size: 600x250 bg: ffffff label_length: 20 approximation_factor: 0.1 }}} В отчетах users_age_by_city и cars_by_city показано использование связи один-ко-многим, в поле class_x указывается связываемая таблица, в параметре column_x_foreign — поле в связываемой таблице, с помощью которого производится присоединение, а параметре column_x_title - поле в связываемой таблице, значения из которого используются в качестве надписей. В параметре column_y_measure можно указать единицы измерения значений, если в этом есть необходимость. Все значения в данных отчетах, которые меньше доли, равной approximation_factor от максимального значения, суммируются и отображаются в графике с надписью "Другие". В результате использования настроек для второго и третьего отчетов сформируются следующие запросы к БД: {{{ SELECT avg(user.age), user.city_id as dte, city.title from user, city where user.city_id = city.id group by dte; SELECT count(car_city.car_id), car_city.city_id as dte, city.title from car_city, city where car_city.city_id = city.id group by dte; }}} Если необходимо добавить дополнительное условие, присоединить таблицу или что-либо еще, вы можете указать метод в параметре criteria раздела model_parameters, который должен возвращать объект класса Criteria с нужными вам условиями: {{{ all: sfStatistics: categories: users: name: Пользователи items: users_registration_by_day: name: Статистика регистраций пользователей по дням model_parameters: class_y: user column_y: id column_x: created_at type: date increment: day aggregation_method: count criteria: UserPeer::getCriteriaForRegistrationChart period_column: created_at chart_parameters: type: line size: 600x300 bg: ffffff label_length: 20 ... }}} В разделе default вы можете определить значения по-умолчанию для параметров внешнего вида графика. В этом же разделе вы можете указать выводимый по-умолчанию отчет: {{{ all: sfStatistics: default: item: users_registration_by_day chart_parameters: type: line bg: ffffff label_length: 20 size: 600x300 approximation_factor: 0.1 categories: users: name: Пользователи items: users_registration_by_day: name: Статистика регистраций пользователей по дням model_parameters: class_y: user column_y: id column_x: created_at type: date increment: day aggregation_method: count period_column: created_at criteria: UserPeer::getCriteriaForRegistrationChart users_age_by_city: name: Средний возраст пользователя по городам model_parameters: class_y: user column_y: age column_y_measure: годы class_x: city column_x: city_id column_x_foreign: id column_x_title: title type: value aggregation_method: avg chart_parameters: type: bar cars_by_city: name: Статистика машин по городам model_parameters: class_y: car_city column_y: car_id class_x: city column_x: city_id column_x_foreign: id column_x_title: title type: value aggregation_method: count chart_parameters: type: pie size: 600x250 }}} Для многих параметров уже заданы значения по умолчанию, которые, вполне возможно, вам подойдут, ниже они указаны: {{{ Раздел chart_parameters: type: line bg: ffffff label_length: 26 size: для line - 700x350, для pie - 700x230, для bar - 700x350 approximation_factor: 0.1 Раздел model_parameters: column_y: id column_x: <>_id #при указании class_x column_x_foreign: id #при указании class_x column_x_title: title type: value aggregation_method: count increment: day period_column: created_at }}} С учетом значений по-умолчанию конфигурация в app.yml станет такой: {{{ all: sfStatistics: default: item: users_registration_by_day chart_parameters: label_length: 20 size: 600x300 categories: users: name: Пользователи items: users_registration_by_day: name: Статистика регистраций пользователей по дням model_parameters: class_y: user column_x: created_at type: date criteria: UserPeer::getCriteriaForRegistrationChart users_age_by_city: name: Средний возраст пользователя по городам model_parameters: class_y: user column_y: age column_y_measure: годы class_x: city aggregation_method: avg chart_parameters: type: bar cars_by_city: name: Статистика машин по городам model_parameters: class_y: car_city column_y: car_id class_x: city type: value chart_parameters: type: pie size: 600x250 }}} Стоит отметить, что в качестве параметров column_y, column_x, column_x_title, column_x_foreign можно указывать название полей, указанных в схеме (created_at, id), константы (UserPeer::CREATED_AT, CarCityPeer::CAR_ID) и строковые вставки ('user.id', 'now() - user.age'). Это также позволяет указывать поля других таблиц, которые только остается присоединить в методе, указываемом в параметре criteria. Плагин полностью поддерживает i18n и содержит на данный момент английский и русский переводы. == TODO == * Доступны 3 вида графика: линейный, круговая и столбовая диаграммы * 2 типа группировки: по дате и по значению * Возможность разбиения отчетов по группам * Настройка группировки значений с относительно малой долей в блок "Другие" * Возможность настройки внешнего вида графика: фоновый цвет, размер, длина надписей * Полная поддержка i18n == Changelog == === 2008-09-08 | 0.1.5 Beta === * salikhov: Создание плагина