BlogBot Plugin API

Схема взаимодействия плагинов с BlogBot

Схему взаимодействия плагинов с BlogBot можно описать следующим образом:

  1. Ежеминутно cron запускает на выполнение файл blogbotd.php, который в свою очередь запускает по очереди все активированные плагины.
  2. Плагины могут выполнять любые действия над существующим контентом, собирать/генерировать новый контент.

База данных BlogBot

blogs таблица с информацией о блогах
blogs_categories тематики блогов
blogs_params параметры блога
categories категории контента
links таблица посещенных и планируемых к посещению ссылок пауком
pings информация о пингах
plugins информация о плагинах
posts таблица контента
publication таблица содержит идентификаторы постов, которые были опубликованы
search_queries поисковые запросы
shedule информация о заданиях расписания

Структура таблиц базы данных BlogBot

Blogs

id int(10) unsigned Идентификатор блога
name varchar(200) Название блога
category int(10) unsigned Идентификатор тематики блога
type varchar(15) Тип блога: wp – wordpress, i – абстрактный блог
title varchar(200) Заголовок блога
options text Опции блога
url varchar(200) URL блога
theme varchar(100) Название шаблона блога/изображение (только для WP), например: mystick/sceenshot.png

Blogs_categories

id int(10) unsigned Идентификатор тематики
title varchar(50) Заголовок тематики

Blogs_params

blog_id int(11) Идентификатор блога
blog_param varchar(30) Название параметра блога
blog_value text Значение параметра
blog_data varchar(30) Дополнительные данные

Сategories

id int(10) unsigned Идентификатор категории
category varchar(100) Заголовок категории
keywords text Ключевые слова (разделитель – перенос на новую строку “\n”)
required text Обязательные слова (не используется, начиная с версии 3.0)
stopwords text Стоп слова (разделитель – перенос на новую строку “\n”)
tags text Тэги (разделитель – перенос на новую строку “\n”)
subcat int(10) unsigned Идентификатор тематики блога, к которой привязывается данная категория
mnemo_blog int(10) unsigned Идентификатор блога, к которому привязывается данная категория
options text Опции категории (сериализованный массив)

Links

id bigint(20) unsigned Идентификатор ссылки
url text URL ссылки
query int(10) unsigned Идентификатор запроса
category int(10) unsigned Идентификатор категории контента
task int(10) unsigned Идентификатор задания в Расписании
visited datetime Дата посещения ссылки

Pings

id bigint(20) unsigned Идентификатор пинга
blogname varchar(100) Заголовок блога
bloghome varchar(100) URL блога
changeurl varchar(256)
rss varchar(100) URL rss-ленты блога
time datetime Дата пинга

Plugins

<

id int(10) unsigned Идентификатор плагина
name varchar(50) Имя плагина
class varchar(50) Название php-класса плагина
version varchar(10) Текущая версия плагина
author varchar(50) Автор плагина
author_email varchar(50) Email автора
description text Описание
enabled enum(‘yes’,'no’) Состояние плагина (активированный или нет)
options longtext Опции (сериализованный массив)

Posts

id bigint(20) Идентификатор поста
category int(11) Идентификатор категории контента
title text Оригинальный заголовок поста
title_s text Синонимизированный заголовок поста
title_r text Рерайченный заголовок поста
title_sr text Синонимизированный и рерайченный заголвок поста
content longtext Оригинальный контент
content_s longtext Синонимизированный контент
content_r longtext Рерайченный контент
content_sr longtext Синонимизированный и рерайченный контент
images text Имена изображений (каждое с новой строчки, например, dixjfd76fd.jpg)
categories text Категории поста (каждая с новой строки, если указаны категории в данном поле, то на конечном блоге именно из этих категорий будут сформированы рубрики)
tags text Тэги поста (каждый с новой строки)
url text URL источника статьи

Publication

blog int(10) unsigned Идентификатор блога
post bigint(20) unsigned Идентификатор поста

Search_queries

id int(10) unsigned Идентификатор запроса
url text URL выдачи
category int(11) Идентификатор категории контента
task int(11) Идентификатор задания в Расписании
used int(10) unsigned Кол-во обращений к данному запросу
success int(10) unsigned Кол-во успешных обращений к страницам результата
requests int(10) unsigned Кол-во запросов к страницам результата

Shedule

id int(10) Идентификатор задания
category int(10) Идентификатор категории
blog int(10) Идентификатор блога
type char(10) Тип задания
options text Опции задания (сериализованный массив)
prior int(11) Приоритет
lastRun datetime Дата последнего запуска
interval int(11) Период запуска в минутах

Спецификация

Все плагины хранятся в папке /plugins/ и имеют следующую структуру:

  • /plugins/PluginName.php – файл, который будет подключатся к BlogBot;
  • /plugins/PluginName/PluginName.code.php – основной код плагина;
  • /plugins/PluginName/*.* – вспомогательные файлы, которые необходимы для работы плагина.

Обратите внимание, что файлы PluginName.php и PluginName.code.php должны содержать название плагина, регистр тоже должен совпадать.

В файле PluginName.php должен быть описан плагин и подключаться основной код плагина:

<?
/*
Plugin: PluginName
Version: YourPluginVersion
Author: YourName
Author email: YourEmail
Description: YourPluginDescription
*/
require_once 'PluginName/PluginName.code.php';

Код плагина оформляется в виде класса с одноименным названием. Опять же, обратите внимание, что регистр символов везде должен совпадать.

Скачать базовый класс-каркас для написания собственных плагинов.

Описание методов класса API

getDb

Доступ к Mysql (работа с Zend_Db http://framework.zend.com/manual/en/zend.db.html)

protected $_db = null;
public function getDb()
{
	if (null == $this->_db) {
		$this->_db = Zend_Registry::get('db');
	}
	return $this->_db;
}

interfaceInstall()

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

public function interfaceInstall()
{
	//Здесь также можно проверить версию Blogbot, хотя это можно сделать и в interfaceActivate
	if (! function_exists('getVersion') || version_compare(getVersion(), '2.0.7', '<')) {
		return 'Требуется версия BlogBot 2.0.7 или выше';
	}
}

interfaceUninstall()

Функция удаления плагина. Если функция возвращает строку, строка интерпретируется как сообщение об ошибке

public function interfaceUninstall()
{
}

interfaceIsInstalled()

Функция проверки установки плагина. Вы добавить код проверки, если это необходимо. Должна возвращать true – если плагин установлен, false – если требуется установка.

public function interfaceIsInstalled()
{
}

interfaceDeactivate()

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

public function interfaceDeactivate()
{
}

interfaceActivate()

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

public function interfaceActivate()
{
}

interfaceConfigure()

Функция конфигурирования плагина. Перед запуском плагина, настройки плагина будут переданы в переменной $cfg.

public function interfaceConfigure($cfg)
{
}

interfaceRun()

Функция запуска плагина. Эта функция будет вызываться при запуске заданий по крону. Если этой функции не будет, плагин будет работать только в интерактивном (ручной запуск) режиме.

public function interfaceRun()
{
}

interfaceMenu()

Создание меню плагина. Должна возвращать ассоциативный массив, в котором ключи – название обработчиков действий, значения – названия разделов. Ниже представлен пример – меню с 2 пунктами и 2 обработчиками.

public function interfaceMenu()
{
	return array(
		'index' => 'Hello Page',
		'another' => 'Another page'
	);
}

actionIndex()

Обработчик по умолчанию всегда называется actionIndex. При переходе на страницу плагина сработает именно этот обработчик, то есть в этой функции генерируется html-код для главной страницы плагина.

public function actionIndex()
{
	return 'Hello! I\'m your plugin!' . (isset($_GET['x']) ?  You follow link! : '');
	//Если вернуть массив, он будет интерпретирован, как новые настройки плагина, которые будут сохранены в базу данных.
}

actionAnother()

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

public function actionAnother()
{
	return 'This is another page. <a href=' . $this->_url('index', array('x'=>1)) . '>Return</a> to main.';
	//Если вернуть массив, он будет интерпретирован, как новые настройки плагина, которые будут сохранены в базу данных.
}

_sql_unprepared()

Используйте эту функцию для создания/удаления таблиц.

protected function _sql_unprepared($sql)
{
	$connection = $this->getDb()->getConnection();
	if ($connection instanceof mysqli) { //если исползуется драйвер mysqli
		return $connection->query($sql);
	} elseif ($connection instanceof PDO) { //если исползуется драйвер PDO
		return $connection->exec($sql);
	}
	throw new Exception('Unsupported mysql driver');
}

_url()

Используйте эту функцию для построения ссылок. Если название плагина не совпадает с названием класса, что крайне нежелательно, подставьте имя плагина вместо get_class($this).

protected function _url($action, $params=array())
{
	return 'bbplugin.php?plugin=' . get_class($this) . '&action=' . $action . '&' . http_build_query($params);
}

Описание общих функций API

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

Работа с контентом

addContent()

Добавление статьи в контент.

function addContent($title, $body, $categories, $tags, $images, $url, $category)
/*
string $title - заголовок
string $body - тело
array $categories - категории статьи
array $tags - теги статьи
array $images - список изображений (без путей, только basename, сами изображения должны нахоиться в папке images)
string $url - источник
int $category - ID категории в BlogBot
*/

editContent()

Редактирование статьи в контенте.

function editContent($postId, $title, $body, $categories, $tags, $images, $url, $category)
/*
int $postId - ID поста
string $title - заголовок
string $body - тело
array $categories - категории статьи
array $tags - теги статьи
array $images - список изображений (без путей, только basename, сами изображения должны нахоиться в папке images)
string $url - источник
int $category - ID категории в BlogBot
*/

deleteContent()

Удаление постов из базы.

deleteContent($ids)
/*
array | int $ids - ID постов
*/

deleteContentByFilter()

Удаление постов по категории или тематике.

deleteContentByFilter($category, $subcat)
/*
int $category - ID категории
int $subcat - ID тематики
*/

getContent()

Получить список постов.

getContent($page, $limit, $category=null, $subcat=null)
/*
int $page - страница
int $limit - кол-во постов на страницу
int $category - ID категории, если нужны посты определенной категории
int $subcat - ID тематики, если нужны посты определенной тематики
*/

getPost()

Получить информацию о посте.

getPost($id)
/*
int $id - ID поста
*/

moveContent()

Перемещение контента в новую категорию

moveContent($ids, $to)
/*
array | int $ids - ID постов
int $to - ID новой категории
*/

moveContentByFilter()

Перемещение контента в новую категорию

moveContentByFilter($category, $subcat, $to)
/*
int $category - ID категории
int $subcat - ID тематики
int $to - ID новой категории
*/

publishContent()

Публикация постов на установленные на том же хостинги блоги.

function publishContent($ids, $blogId, &$failed=null, $ping=true, $use_syn=false, $use_rew=false)
/*
array $ids - массив ID постов,
int $blogId - ID блога
array &$failed - ссылка на переменную, после выполнения функции может содержать массив ID постов, которые не опубликовались,
bool $ping - использовать пинг
bool $use_syn - использовать синонимайзер (пост уже должен иметь синонимизированную версию)
bool use_rew - использовать рерайтер (пост уже должен иметь рерайченную версию)
*/

countContent()

Получение количества постов в базе.

countContent($category=null, $subcat=null)
/*
int $category - ID категории, если нужны посты определенной категории
int $subcat - ID тематики, если нужны посты определенной тематики
*/

Работа с блогами

addBlogsCategory()

Cоздание тематики.

function addBlogsCategory($name)
/*
string $name - название
return int - ID новой тематики
*/

deleteBlogCategory()

Удаление тематики.

deleteBlogCategory($id)
/*
int $id - ID тематики
*/

getBlog()

Получение информации о блоге.

getBlog($id)
/*
int $id - ID блога
*/

getBlogs()

Получение списка блогов.

getBlogs($category=null, $type=null, $minus_type=null)
/*
int $category - ID категоии
string $type - тип блога (wp, i)
string $minus_type - тип блога, который не будет выбран (wp, i)
*/

getBlogsCategories()

Получить список тематик.

getBlogsCategories()

getBlogsCategoriesList()

Получить список тематик в виде массива, где ключ ID, значение – название тематики.

getBlogsCategoriesList

getBlogsCategory()

Получить информацию о тематике.

getBlogsCategory($id)
/*
int $id - ID тематики
*/

getBlogsList()

Получение списка блогов в виде массива, где ключ ID, значение – название блога.

getBlogsList($type=null, $minus_type=null)
/*
int $category - ID категоии
string $type - тип блога (wp, i)
string $minus_type - тип блога, который не будет выбран (wp, i)
*/

Работа с категориями

addCategory()

Создание новой категории.

function addCategory($name, $keywords, $required, $stopwords, $tags, $subcat, $mnemo_blog, $opts)
/*
string $name - название
string $keywords - ключевые слова, разделены \n
string $required - обязательные слова, разделены \n
string $stopwords - стоп-слова, разделены \n
string $tags - теги, разделены \n
int $subcat - ID тематики (0 - без тематики)
int $mnemo_blog - ID блога, с которым она будет связана (0 - без привязки)
array $opts
return int - ID новой категории
*/

editCategory()

Редактирование категории

function editCategory($id, $name, $keywords, $required, $stopwords, $tags, $subcat, $mnemo_blog, $opts)
/*
int $id - ID категории
string $name - название
string $keywords - ключевые слова, разделены \n
string $required - обязательные слова, разделены \n
string $stopwords - стоп-слова, разделены \n
string $tags - теги, разделены \n
int $subcat - ID тематики (0 - без тематики)
int $mnemo_blog - ID блога, с которым она будет связана (0 - без привязки)
array $opts
*/

deleteCategory()

Удаление категорий из базы.

deleteCategory($id)
/*
array | int $ids - ID категорий
*/

getCategories()

Получить список категорий.

getCategories($subcat=null, $mnemoblog=null)
/*
int $subcat - ID тематики
int $mnemoblog - ID блога, с которым связана тематика
*/

getCategoriesList()

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

getCategoriesList($subcat=null, $mneno_blog=null)
/*
int $subcat - ID тематики
int $mnemoblog - ID блога, с которым связана тематика
*/

getCategory()

Получить информацию о категории.

getCategory($id)
/*
int $id - ID категории
*/

Вспомогательные функции

hasSynonymizer()

Функция возвращает true|false в зависимости от наличия или отсутсвия встроенного синонимайзера.

function hasSynonymizer()

hasRewriter()

Функция возвращает true|false в зависимости от наличия или отсутсвия встроенного рерайтера.

function hasRewriter()

buildChecks()

Вывод html-тегов input типа checkbox.

buildChecks($name, $list, $checked)
/*
string $name - имя элемента
array $list - ассоциативный массив ключей-значений
string $checked - выбранное значение
*/

buildOptions()

Вывод html-тегов option, нужно использовать внутри тега select.

function buildOptions($opts, $value)
/*
array $opts - ассоциативный массив ключей-значений
string $value - выбранное значение
*/

buildMultiOptions()

То же, что и buildOptions, но для множественного выбора (не забудьте про атрибут multiple="multiple" для select).

buildMultiOptions($opts, $vals)
/*
array $opts - ассоциативный массив ключей-значений
array $values - выбранные значение
*/

buildRadio()

Аналог buildChecks, только вместо checkboxradio.

buildRadio($name, $list, $value)
/*
string $name - имя элемента
array $list - ассоциативный массив ключей-значений
string $checked - выбранное значение
*/

getPaginator()

Вывод разбивки на страницы.

getPaginator($count, $perpage=50)
/*
int $count - общее кол-во элементов
int $perpage - кол-во элементов на странице
*/

makeSlug()

Транслитерация.

makeSlug($word)
/*
string $word - слово
*/