Как сделать свой bbcode

У меня периодически появляется потребность в использовании «интерпретатора» BBCode в своих проектах (написанного на PHP), и постоянно нет времени искать какое-то более-менее удобоваримое решение, что bbcode в итоге выливается в использование или создание «костылей» для каждого конкретного случая.
Но вот, похоже, получилось найти то, что хотелось.

Моя претензия к подобным готовым решениям обычно в первую очередь заключается в неспособности этих библиотек правильно обрабатывать абзацы. Фактически они обычно вообще не используют абзацы (тэг P), вместо этого в результате своей работы они просто вставляют тег <br />, заменяя обычные символы переноса строки. Я считаю такой метод эмулирования абзацев в 98 процентах, мягко говоря, не уместным. Но так как перенос строк по средствам <br /> намного легче реализовать вместо «человеческих» <p>, так большинство и делает 🙁 Некоторые даже придумывают оправдания, что мол с br даже правильнее, отчасти, из-за подобной лени разработчиков различных готовых библиотек, другая часть людей думает, что тэг P является устаревшим (ведь даже во многих готовых продуктах и сайтах абзацы формируются путем использования <br />) 🙂

Приступим

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

Для начала нужно скачать библиотеку (на момент написания статьи версия библиотеки была 0.3.3). В скачанном архиве в папке src вы обнаружите два нужных нам файла: stringparser.class.php и stringparser_bbcode.class.php.

Для примера предположим, что у нас есть пустой файл «index.php» и рядом с ним мы создадим папку «/bbcode/», содержащую в себе два упомянутых выше файла.
Для примера минимальное содержимое файла «index.php» должно быть таким (запустив этот пример можно как сделать свой bbcode будет сразу увидеть, работает ли библиотека):

<?php //Вставляем файл библиотеки require_once 'bbcode/stringparser_bbcode.class.php'; //Создаем объект класса StringParser_BBCode $bbcode = new StringParser_BBCode (); //Добавляем объекту класса понятие о тэге [b] //(в итоге только этот тэг и будет //обрабатываться этим классом) $bbcode->addCode ('b', 'simple_replace', null, array ('start_tag' => '<b>', 'end_tag' => '</b>'), 'inline', array ('block', 'inline'), array ()); //Обрабатываем тестовую строку и выводим ее в браузер echo $bbcode->parse ('Тестовый текст, это слово должно быть [b]жирным[/b]');?>

Функция addCode

Наибольший интерес в этом коде может вызвать, пожалуй, функция addCode у объекта класса StringParser_BBCode, вот ее прототип и список описание параметров:

void addCode (string $code, string $type, string $callback, string $params, string $content_type, array $allowed_in, array $not_allowed_in);

Эта функция добавляет понятие о тех или иных кодах (bb-кодах) для объекта класса, чтоб он мог потом обнаружить эти коды в тексте и соответствующим образом обработать их. Т.е. можно сказать, что изначально объект класса StringParser_BBCode вообще ничего не знает о стандартных bb-кодах и не способен обработать как-либо их. Поэтому этот объект нужно будет после каждой инициализации «обучать» всем разновидностям bb-кодов.

$code (в примере имеет значение ‘b’) Код, который нужно искать в тексте для обработки. Т.е. если указать код test, то потом в обрабатываемом тексте будет искаться тэг [test] и обрабатываться в соответствии с указаниями в других параметрах рассматриваемой функции. $type (в примере имеет значение ‘simple_replace’) Указание того, как тэг должен обрабатываться (какого он типа). Есть различные предопределенные типы тэгов, которые будут описаны ниже. В нашем же примере указан тип ‘simple_replace’ который указывает на то, что тэг будет парным (открывающийся тэг [b] и закрывающийся [/b]) и что эти тэги будут заменены на указанные ниже html тэги. $callback (в примере имеет значение null) Позволяет указать имя функции, которая должна будет вызваться при обработке найденного тэга в тексте. В случае с типом тэга ‘simple_replace’ такая функция не вызывается, и, соответственно, в этом параметре можно указать null. $params (в примере имеет значение array(‘start_tag’ => ‘‘, ‘end_tag’ => ‘‘)) В этом параметре в основном указывается, какой нужно вставлять html тэг взамен bb тэга. Наименование параметров напрямую зависит от того, какой тип тэга мы указали в параметре $type. $content_type (в примере имеет значение ‘inline’) Тип внутреннего содержимого тега. Может принимать значения: ‘inline’, ‘block’, ‘link’, ‘image’. Если я не ошибаюсь, можно прописывать и свои типы чтобы потом можно было указывать для этого содержимого свои индивидуальные фильтры (пример использования фильтров смотрите ниже). $allowed_in (в примере имеет значение array (‘block’, ‘inline’)) В этом параметре можно указать, внутри каких типов объектов может находиться создаваемый bb-код (его обработка будет просто игнорироваться в ином случае). В нашем примере мы указали, что элемент может находиться как внутри блочных элементов, так и внутри линейных. $not_allowed_in (в примере имеет значение array ()) Имеет назначение, противоположное по смыслу предыдущему параметру.

Виды обработки тэгов

Описание вариантов значения параметра $type в функции addCode.

‘simple_replace’ Описывает простой парный тэг. При использовании этого типа обработки тэга в параметре функции ‘params’ должны обязательно присутствовать две ячейки: $params[‘start_tag’] и $params[‘end_tag’]. ‘start_tag’ должен в себе содержать аналог открывающегося тэга в хтмл, а ‘end_tag’ – закрывающегося тэга соответственно. ‘simple_replace_single’ То же самое, что ‘simple_replace’, но используется только лишь для одинарных тэгов, которые, собственно говоря, не имеют содержимого (типа br, hr и т.п.). Требует наличия только параметра $params[‘start_tag’]. ‘callback_replace’ При этом типе вы перекладываете на себя обработку по найденным совпадениям (с помощью своей callback функции) для парного тэга. ‘callback_replace_single’ То же самое, что и ‘callback_replace’, но только для одинарных тэгов. ‘usecontent’ То же самое что и ‘callback_replace’, только в содержимом такого тэга другие тэги не будут обрабатываться, например, это удобно для тэга code. ‘usecontent?’ Этот тип может себя вести как ‘usecontent’ или же как ‘callback_replace’ в зависимости от ситуации. Актуальность того или иного варианта определяется за счет присутствия заранее предполагаемого атрибута в bb тэге. Если атрибут найден, то будет использоваться обработка ‘callback_replace’, в другом случае тэг будет обрабатываться как ‘usecontent’. Имя атрибута для поиска указывается через параметр $params[‘usecontent_param’]. Если указано имя default, то подразумевается значение атрибута, присвоенное непосредственно тэгу, например, [url=http://link], значением атрибута default будет текст «http://link». Этот прием часто используется, например, для тэга [URL]. Этот тэг может использоваться в двух формах: [url]http://www.example.com/[/url] и [url=http://www.example.com/]Текст ссылки, а так же [b]жирный[/b] текст[/url]. В первом случае будет использоваться тип ‘usecontent’, т.к. текст ссылки должен выводиться без какого-либо форматирования (и, собственно, сама ссылка будет некорректна, если в ней будут посторонние символы). В другом случае должен быть использован тип ‘callback_replace’, т.к. сама ссылка передается отдельным параметром, а текст, обрамленный в ссылку, вполне может содержать в себе какое-то форматирование.
Примечание: Можно указать несколько параметров для их поиска, для чего в $params[‘usecontent_param’] нужно передать не строку, а массив, содержащий строки. Например: $bbcode->addCode (…, array(‘usecontent_param’ => array (‘parameter1’, ‘parameter2’)), …);. ‘callback_replace?’ Является противоположным вариантом типа ‘usecontent?’. Если один из атрибутов, указанных в usecontent_param, встречается в тэге, он будет обработан как ‘usecontent’, в противном случае как ‘callback_replace’.

Пример кода из «боевых» условий

Вот пример файла index.php с более расширенной конфигурацией класса для обрабатывания большего числа тэгов, в нем же и можно понять, как работают callback функции и т.п.:

<?php //Вставляем файл библиотеки require_once 'bbcode/stringparser_bbcode.class.php'; //Приводит разнообразные переводы строк //разных операционных систем в единый формат (\n) function convertlinebreaks ($text) { return preg_replace ("/52|5|2/", "\n", $text); } //Удалить все символы, кроме переводов строк function bbcode_stripcontents ($text) { return preg_replace ("/[^\n]/", '', $text); } //Функция для обработки ссылок function do_bbcode_url ($action, $attributes, $content, $params, $node_object) { if (!isset ($attributes['default'])) { $url = $content; $text = htmlspecialchars ($content); } else { $url = $attributes['default']; $text = $content; } //Часть функции, которая занимается //только валидацией данных тэга if ($action == 'validate') { if (substr ($url, 0, 5) == 'data:' || substr ($url, 0, 5) == 'file:' || substr ($url, 0, 11) == 'javascript:' || substr ($url, 0, 4) == 'jar:') { return false; } return true; } //Непосредственное преобразование тэга в //html вариант с возвращением результата return '<a href="'.htmlspecialchars ($url).'">'.$text.''; } // Функция для вставки изображений function do_bbcode_img ($action, $attributes, $content, $params, $node_object) { //Часть функции, которая занимается //только валидацией данных тэга if ($action == 'validate') { if (substr ($content, 0, 5) == 'data:' || substr ($content, 0, 5) == 'file:' || substr ($content, 0, 11) == 'javascript:' || substr ($content, 0, 4) == 'jar:') { return false; } return true; } //Непосредственное преобразование тэга в //html вариант с возвращением результата return '<img src="'.htmlspecialchars($content).'" alt=""/>'; } //Создаем объект класса StringParser_BBCode $bbcode = new StringParser_BBCode(); //Добавляем фильтр (подробнее см. офф. документацию), //задействуя нашу функцию convertlinebreaks, которая будет //преобразовывать переводы строки в тексте к единому $bbcode->addFilter (STRINGPARSER_FILTER_PRE, 'convertlinebreaks'); //Добавляем свои парсеры для разных типов объектов //(подробнее см. офф. документацию) //Мы указываем, через какую функцию должно пройти //содержимое этих тэгов, например, через функцию //htmlspecialchars для предотвращения XSS и т.д. $bbcode->addParser (array ('block', 'inline', 'link', 'listitem'), 'htmlspecialchars'); $bbcode->addParser (array ('block', 'inline', 'link', 'listitem'), 'nl2br'); $bbcode->addParser ('list', 'bbcode_stripcontents'); //Добавляем bb-код [h1], используемый в виде: //[h1]Текст заголовка первого уровня[/h1] $bbcode->addCode ('h1', 'simple_replace', null, array ('start_tag' => '<h1>', 'end_tag' => '</h1>'), 'block', array ('listitem', 'block', 'link'), array ()); //Добавляем bb-код [h2], используемый в виде: //[h2]Текст заголовка второго уровня[/h2] $bbcode->addCode ('h2', 'simple_replace', null, array ('start_tag' => '<h2>', 'end_tag' => '</h2>'), 'block', array ('listitem', 'block', 'link'), array ()); //Добавляем bb-код [h3], используемый в виде: //[h3]Текст заголовка третьего уровня[/h3] $bbcode->addCode ('h3', 'simple_replace', null, array ('start_tag' => '<h3>', 'end_tag' => '</h3>'), 'block', array ('listitem', 'block', 'link'), array ()); //Добавляем bb-код [h4], используемый в виде: //[h4]Текст заголовка четвертого уровня[/h4] $bbcode->addCode ('h4', 'simple_replace', null, array ('start_tag' => '<h4>', 'end_tag' => '</h4>'), 'block', array ('listitem', 'block', 'link'), array ()); //Добавляем bb-код [h5], используемый в виде: //[h5]Текст заголовка пятого уровня[/h5] $bbcode->addCode ('h5', 'simple_replace', null, array ('start_tag' => '<h5>', 'end_tag' => '</h5>'), 'block', array ('listitem', 'block', 'link'), array ()); //Добавляем bb-код [h6], используемый в виде: //[h6]Текст заголовка шестого уровня[/h6] $bbcode->addCode ('h6', 'simple_replace', null, array ('start_tag' => '<h6>', 'end_tag' => '</h6>'), 'block', array ('listitem', 'block', 'link'), array ()); //Устанавливаем флаги для bb-кодов с h1 до h6, //указывая, что они являются блочными элементами, //что будет в дальнейшем благотворно влиять на умную //генерацию html кода. Такой элемент, к примеру, не сможет //находиться внутри других блочных элементов $bbcode->setCodeFlag('h1', 'paragraph_type', BBCODE_PARAGRAPH_BLOCK_ELEMENT); $bbcode->setCodeFlag('h2', 'paragraph_type', BBCODE_PARAGRAPH_BLOCK_ELEMENT); $bbcode->setCodeFlag('h3', 'paragraph_type', BBCODE_PARAGRAPH_BLOCK_ELEMENT); $bbcode->setCodeFlag('h4', 'paragraph_type', BBCODE_PARAGRAPH_BLOCK_ELEMENT); $bbcode->setCodeFlag('h5', 'paragraph_type', BBCODE_PARAGRAPH_BLOCK_ELEMENT); $bbcode->setCodeFlag('h6', 'paragraph_type', BBCODE_PARAGRAPH_BLOCK_ELEMENT); //Добавляем bb-код [b], используемый в виде: //[b]выделенный текст[/b] $bbcode->addCode ('b', 'simple_replace', null, array ('start_tag' => '<b>', 'end_tag' => '</b>'), 'inline', array ('listitem', 'block', 'inline', 'link'), array ()); //Добавляем bb-код [i], используемый в виде: //[i]наклонный текст[/i] $bbcode->addCode ('i', 'simple_replace', null, array ('start_tag' => '<i>', 'end_tag' => '</i>'), 'inline', array ('listitem', 'block', 'inline', 'link'), array ()); //Добавляем bb-код [url], используемый в виде: //[url]http://www.needsite.domain[/url] и //[url=http://www.needsite.domain]Текст ссылки[/url] $bbcode->addCode ('url', 'usecontent?', 'do_bbcode_url', array ('usecontent_param' => 'default'), 'link', array ('listitem', 'block', 'inline'), array ('link')); //Добавляем bb-код [link], используемый в виде: //[link]http://www.needsite.domain[/link] $bbcode->addCode ('link', 'callback_replace_single', 'do_bbcode_url', array (), 'link', array ('listitem', 'block', 'inline'), array ('link')); //Добавляем bb-код [img], используемый в виде: //[img]http://www.needsite.domain/img.jpg[/img] $bbcode->addCode ('img', 'usecontent', 'do_bbcode_img', array (), 'image', array ('listitem', 'block', 'inline', 'link'), array ()); //Добавляем bb-код [bild] (по смыслу то же самое, //что и [img]), используемый в виде: //[bild]http://www.needsite.domain/img.jpg[/bild] $bbcode->addCode ('bild', 'usecontent', 'do_bbcode_img', array (), 'image', array ('listitem', 'block', 'inline', 'link'), array ()); //Создаем группу image из bb-кодов img и bild //для последующей возможности задания //неких правил для этих групп $bbcode->setOccurrenceType ('img', 'image'); $bbcode->setOccurrenceType ('bild', 'image'); //Указываем, что тэги из группы image //могут встречаться (обрабатываться) в тексте не более //двух раз. В нашем случае это нужно для того, //чтобы пользователь не мог вставить более двух //картинок в текст сообщения $bbcode->setMaxOccurrences ('image', 2); //Добавляем bb-код [list] $bbcode->addCode ('list', 'simple_replace', null, array ('start_tag' => '<ul>', 'end_tag' => '</ul>'), 'list', array ('block', 'listitem'), array ()); //Добавляем bb-код [], указывая, что этот тэг //может использоваться только внутри тэга //с типом list (этот тип мы присвоили выше тэгу [list]) $bbcode->addCode ('', 'simple_replace', null, array ('start_tag' => '<li>', 'end_tag' => '</li>'), 'listitem', array ('list'), array ()); //Устанавливаем флаги для тэгов [list] и [] //Указываем, что для кода [] закрывающийся тэг //не обязателен, таким образом, возможна будет //следующая конструкция: //[list] //[] Item //[] Item //[/list] //Закрывающий тэг будет добавляться автоматически //в процессе формирования html кода $bbcode->setCodeFlag ('', 'closetag', BBCODE_CLOSETAG_OPTIONAL); //Как я понял, этот флаг обозначает, что тэг [] //всегда может быть использован только //в начале новой строки $bbcode->setCodeFlag ('', 'paragraphs', true); //[list] является блочным элементом $bbcode->setCodeFlag ('list', 'paragraph_type', BBCODE_PARAGRAPH_BLOCK_ELEMENT); //Перед открывающимся тэгом [list] //символ строки будет устранен $bbcode->setCodeFlag ('list', 'opentag.before.newline', BBCODE_NEWLINE_DROP); //Перед закрывающимся тэгом [list] //символ строки будет устранен $bbcode->setCodeFlag ('list', 'closetag.before.newline', BBCODE_NEWLINE_DROP); //В итоге мы можем использовать списки в bb-коде, //используя вместе теги list и : //[list] //[] Элемент списка //[] Элемент списка //[] и т.д. //[/list] //Активируем обработку параграфов $bbcode->setRootParagraphHandling (true); //Как я понял, таким образом указывается, //какими символами нужно заменять встреченный //перенос строки внутри абзаца //(по сути, как обрабатывать пустые абзацы). $bbcode->setParagraphHandlingParameters ("\n", '<p>', '</p>'); $res_text = "Тестовый текст [b]для проверки[/b] работы класса"; //На всякий случай удаляем все оставшиеся //символы переноса строки в виде "\r", //если такие остались в тексте $res_text = str_replace("\r", '', $res_text); //Вуаля! echo $bbcode->parse($res_text);

Послесловие

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

Эту библиотеку также не составляет труда внедрить в какой-либо php фреймворк, я, к примеру, с успехом проделывал это для cackePHP.

Если вы тоже встречали подобные библиотеки (корректно работающие с абзацам! 🙂 ), интересно было бы узнать о них.


Источник: http://ezoterik.name/php-i-bbcode/

Закрыть ... [X]

Прочие опции BBCode a - Форум phpBB - Официальная русская Как сделать чтоб мальчики влюбились в меня

Как сделать свой bbcode BBCode (текст, картинки, видео и др.) - Форум - Элдария
Как сделать свой bbcode Как сделать свои bbcode кнопки в ml? : DLE FAQ
Как сделать свой bbcode WysiBB WYSIWYG BBCode редактор / Хабрахабр
Как сделать свой bbcode PHP и BBCode Заметки разработчика
Как сделать свой bbcode XBB: Как создать тег BBCode spoiler
Как сделать свой bbcode BBCode Википедия
Как сделать свой bbcode 20 красивых и простых причесок на средние волосы - m
Как сделать свой bbcode Бытовка своими руками: как построить
ВОЗБУЖДЕНИЕ УГОЛОВНОГО ДЕЛА Вязаное платье - 100 модных фото Гигантские цветы из бумаги / цветочки из бумаги Как сделать Windows 8 похожей на Windows 7 Как сделать ваших клиентов постоянными?