Библиотека обработки HTML-текста из PHP-скриптов.
 

Представленная библиотека представляет собой очередную попытку отделить содержание от оформления. Основная идея не нова - использовать специальное оформление внутри статического HTML-текста, что позволит при обработке этого текста заменить специально оформленные разделы на динамически формируемые данные из PHP-скрипта. Другими словами, мы создаем свой собственный "стиль разметки" HTML-текста, а затем этот специально подготовленный HTML-текст обрабатывается из PHP-скрипта. Простейший пример: требуется показывать на сайте текущую дату. Естественно, что сами данные (день, месяц, год, время) будут меняться, поскольку формируются динамически, однако их оформление, скорей всего, будет одним и тем же (предположим, большая синяя надпись в красной рамке). Самым удобным решением - каким-то образом "подсказать" PHP-скрипту, где именно нужно вывести данные, не касаясь стиля их оформления. Для этого в представленной библиотеки используются как простые замены (специальные последовательности символов), так и специальные HTML-теги.

Подключение библиотеки

Наверх

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

// путь к файлам библиотеки из исполняемого PHP-скрипта define('INCLUDE_DIR', 'parse/'); // инициализация библиотеки require_once(INCLUDE_DIR.'init.inc.php'); 

Принципы работы и основные функции-обработчики

Наверх

Библиотека работает так же, как и все остальные библиотеки, занимающиеся парсингом HTML-текста, с добавлением в этот текст данных, полученных из PHP-скрипта :

  • Функция "parseStr" - ищет в исходной строке все вхождения вида
    <#имя_переменной#>
    и заменяет их переменными или константами из PHP-скрипта с совпадающими именами (имена переменных и констант case-sensitive).
    Например, если в PHP-скрипте существует такая запись:
    $var = '1234';
    то при вызове в этом PHP-скрипте функции "parseStr", все вхождения вида <#var#> в исходной строке будут заменены на значение переменной $var:
    // инициализация переменной $var $var = '1234'; 	 // вызов функции "parseStr" echo parseStr('Variable $var has value <#var#>'); // результат работы функции "parseStr" Variable $var has value 1234 
    Аналогичным образом подставляются значения констант:
    // инициализация константы MY_CONST define('MY_CONST', 1234); 	 // вызов функции "parseStr" echo parseStr('Constant MY_CONST has value <#MY_CONST#>'); // результат работы функции "parseStr" Constant MY_CONST has value 1234 
    ПРИМЕЧАНИЕ: Символы начала переменной/константы ( <# ) и символы окончания переменной/константы ( #> ) могут быть изменены двумя способами:
    • изменить значения соответствующих констант в файле "const.inc.php":
      // новые параметры начала и окончания переменных/констант в PHP-скрипте define('DEFAULT_VARNAME_START', '{'); define('DEFAULT_VARNAME_END', '}');
    • изменить правила парсинга, вызвав функцию "init":
      // новые параметры начала и окончания переменных/констант в PHP-скрипте $new_pars = array('varstart' => '{', 'varend' => '}'); // изменить правила парсинга $GlobalParser->init($new_pars);
  • Функция "parseFile" - считывает содержимое файла в строку, после чего эта строка передается на обработку функции "parseStr", и
  • Функция "parseTag" - обрабатывает теги специального вида. Мы будем называть эти теги "callback-тегами".

Callback-теги

Наверх

Мы будем использовать термин "callback-теги", когда будем говорить о специальных тегах, используемых в библиотеке, поскольку их назначение близко к вызову callback функций. Использование callback-тегов позволяет вызывать PHP-функции во время парсинга. Callback-тег - это парный тег, который определяет сам разработчик. Имя callback-тега хранится в настройках библиотеки. Самый простой callback-тег выглядит так:

<callback name=имя_функции>содержимое_тега</callback>

Как это работает? Каждый раз, когда функция "parseTag" встречает callback-тег в процессе парсинга, она вызывает PHP-функцию с указанным именем (имя функции хранится в аттрибуте "name"). Вызываемая функция должна принимать один параметр - в качестве этого параметра в функцию передается "содержимое_тега". Если функция принимает больше, чем один параметр, то все параметры, начиная со второго должны иметь значения по умолчанию. Результатом вызываемой функции должна быть строка или число. Этот результат будет подставлен вместо callback-тега.

Пример вызова стандартной PHP-функции "strtoupper" :

<? /* тестовый PHP-скрипт : test1.php */ // путь к файлам библиотеки, define('INCLUDE_DIR', 'parse/'); // инициализация библиотеки require_once(INCLUDE_DIR.'init.inc.php'); // инициализация исходной строки $str = '<callback name=strtoupper>this is a test</callback>'; // вызов функции "parseTag" echo parseTag($str); ?>
Результат работы функции "parseTag" :


THIS IS A TEST
 

Пример использования функции "MyFunc", определенной разработчиком :

<? /* тестовый PHP-скрипт : test2.php */ // путь к файлам библиотеки, define('INCLUDE_DIR', 'parse/'); // инициализация библиотеки require_once(INCLUDE_DIR.'init.inc.php'); // определение функции, принимающей 1 параметр function MyFunc($format){ 	return date($format); } // инициализация исходной строки $str = ' Today is : <callback name=MyFunc>F j, Y, g:i a</callback><BR> Today is : <callback name=MyFunc>D M j G:i:s</callback> '; // вызов функции "parseTag" echo parseTag($str); ?>
Результат работы функции "parseTag" :


Today is : September 23, 2002, 1:08 pm
Today is : Mon Sep 23 13:08:08

 

Библиотека может обрабатывать и более сложные callback-теги. Общий вид callback-тега:

<callback {атрибуты_тега} name=имя_функции {атрибуты_тега}> содержимое_тега </callback>
Единственным обязательным атрибутом является атрибут "name", остальные атрибуты необязательны и зависят от определения самой функции. Стандартными функциями-обработчиками считаются функции "parseStr", "parseFile" и "parseTag". Это означает, что допускается использование тегов вида :
<callback name=parseStr> содержимое_тега </callback> <callback name=parseFile> содержимое_тега </callback> <callback name=parseTag> содержимое_тега </callback>

Изменить название callback-тега можно двумя способами:

  • изменить значения соответствующей константы в файле "const.inc.php":
    // новое название callback-тега define('DEFAULT_TAGNAME', 'mytag');
  • изменить правила парсинга, вызвав функцию "init":
    // новое название callback-тега $new_pars = array('tagorigin' => 'mytag'); // изменить правила парсинга $GlobalParser->init($new_pars);
Теперь библиотека будет обрабатывать callback-теги вида :
<mytag {другие атрибуты} name=имя_функции {другие атрибуты}> содержимое_тега </mytag>
ПРИМЕЧАНИЕ. Название тега - case-insensitive, имена и значения атрибутов тега - case-sensitive.

Дополнительные функции-обработчики

Наверх

Разработчик может самостоятельно определить дополнительные функции-обработчики и соответствующие им теги.

В библиотеке уже определены несколько дополнительных функций-обработчиков, которые охватывают наиболее часто встречающиеся ситуации:

  • "fileInclude" - возвращает содержимое файла, считанное в строку по заданному имени файла;
  • "makeRepeat" - применяет заданную функцию к каждому элементу заданного массива; результат работы функции поэлементно накапливается и возвращается в виде строки после обработки последнего элемента массива;
  • "makeBool" - в зависимости от заданной переменной возвращает один из двух возможных результатов.
Чтобы воспользоваться этими функциями, необходимо подключить их в качестве дополнительных функций-обработчиков :
// список дополнительных функций-обработчиков $new_pars = array('makeBool', 'makeRepeat', 'fileInclude'); // добавить дополнительные функции-обработчики $GlobalParser->init($new_pars);
ПРИМЕЧАНИЕ: По умолчанию все эти уже функции подключены в файле "init.inc.php".

Каждой из описанных функций соответствует свой предопределенный callback-тег.
Рассмотрим каждую из них более подробно.

Функция "fileInclude" обрабатывает callback-тег вида (в квадратных скобках указаны необязательные атрибуты):

<callback 	 	name=fileInclude 		[ save=имя_глобальной_переменной ] 		[ func=имя_функции ] 		[ ffunc=имя_дополнительной_функции ]> имя_файла </callback>
где содержимое тега определяет имя заданного файла, а атрибуты могут задавать дополнительные параметры обработки:
  • save=имя_глобальной_переменной
    если этот атрибут указан, то в $GLOBALS [ имя_глобальной_переменной ] будет записан результат работы функции "fileInclude";
  • func=имя_функции
    если этот атрибут указан, то к строке, в которую предварительно считано содержимое заданного файла, будет применена заданная этим атрибутом функция;
  • ffunc=имя_дополнительной_функции
    если этот атрибут указан, то прежде чем начать работу с файлом, к имени файла будет применена заданная этим атрибутом функция.
Пример вызова функции "fileInclude" :
<!-- главный обрабатываемый файл "main_file.html" --> This is the demo how to call "fileInclude" function by "callback"-tag:<BR><BR> <callback name=fileInclude func=parseTag>included_file.html</callback> <!-- подключаемый файл "included_file.html" --> We came here by calling "fileInclude" function <BR> Today date is <em><callback name=date>F j, Y, g:i a</callback></em> <? /* тестовый PHP-скрипт : test3.php */ // путь к файлам библиотеки, define('INCLUDE_DIR', 'parse/'); // инициализация библиотеки require_once(INCLUDE_DIR.'init.inc.php'); // инициализация исходной строки с помощью функции "parseFile" $str = parseFile('main_file.html'); // вызов функции-обработчика "parseTag" в PHP-скрипте echo parseTag($str); ?>
Результат работы функции "parseTag" :


This is the demo how to call "fileInclude" function by "callback"-tag:

We came here by calling "fileInclude" function
Today date is September 22, 2002, 11:53 pm

 

Как это работает?
С помощью функции "parseFile" мы считываем содержимое файла "main_file.html" в строку и сохраняем эту строку в переменной $str. Затем начинаем обрабатывать полученную строку с помощью фукнции "parseTag".
Как только функция "parseTag" встречает в тексте callback-тег

<callback name=fileInclude func=parseTag>included_file.html</callback> 
тут же вызывается функция "fileInclude", где
  • included_file.html - имя заданного файла;
  • parseTag - функция, которая будет применена к содержимому файла "included_file.html".
С помощью функции "fileInclude" содержимое файла "included_file.html" считывается в строку, и к этой строке применяется функция "parseTag". Строка, полученная в результате, подставляется вместо callback-тега.


Функция "makeRepeat" обрабатывает callback-тег вида (в квадратных скобках указаны необязательные атрибуты):

<callback 		name=makeRepeat 		var=имя_переменной 		[ save=имя_глобальной_переменной ] 		[ func=имя_функции ] 		[ ffunc=имя_дополнительной_функции ]> содержимое_тега </callback>
где содержимое тега определяет исходную строку, которая будет передаваться в качестве первого параметра в функцию, вызываемую для каждого элемента заданного массива, а атрибуты задают имя переменной, хранящей обрабатываемый массив и некоторые дополнительные параметры обработки:
  • var=имя_переменной (обязательный атрибут)
    имя переменной-массива, который обрабатывается поэлементно;
  • save=имя_глобальной_переменной
    если этот атрибут указан, то в $GLOBALS [ имя_глобальной_переменной ] будет записан результат работы функции "makeRepeat";
  • func=имя_функции
    если этот атрибут указан, то к содержимому_тега будет применена функция, заданная этим атрибутом, столько раз, сколько элементов содержит массив;
  • ffunc=имя_дополнительной_функции
    если этот атрибут указан, то по окончании обработки элементов массива к результирующей строке, в которую накапливались результаты обработки содержимого_тега, будет применена заданная этим атрибутом функция.
Пример вызова функции "makeRepeat" :
<!-- главный обрабатываемый файл "testrepeat_file.html" --> This is the demo how to call "makeRepeat" function by "callback"-tag:<BR><BR> <table border=0> <callback name=makeRepeat var=colors func=parseStr ffunc=parseTag> <tr><td>This is color <span style="color:<#elem#>"><em><#idx#></em></span></td></tr> </callback> </table> <? /* тестовый PHP-скрипт : test4.php */ // путь к файлам библиотеки, define('INCLUDE_DIR', 'parse/'); // инициализация библиотеки require_once(INCLUDE_DIR.'init.inc.php'); // инициализация массива $colors = array('red' => 'red', 'green' => 'green', 'blue' => 'blue', 'yellow' => '#ffdd00'); // инициализация исходной строки $str = join('', file('testrepeat_file.html')); // вызов функции-обработчика "parseTag" в PHP-скрипте echo parseTag($str); ?>
Результат работы функции "parseTag" :


This is the demo how to call "makeRepeat" function by "callback"-tag:

This color is red
This color is green
This color is blue
This color is yellow

 

Как это работает? Как только функция "parseTag" встречает в тексте callback-тег

<callback name=makeRepeat var=colors func=parseStr ffunc=parseTag> <tr><td>This is color <span style="color:<#elem#>"><em><#idx#></em></span></td></tr> </callback>
тут же вызывается функция "makeRepeat", где
  • $colors - имя заданного массива;
  • parseStr - функция, которая будет применяться к строке
    <tr><td>This is color <span style="color:<#elem#>"><em><#idx#></em></span></td></tr>
    столько раз, сколько элементов в массиве $colors; причем при каждом вызове функции "parseStr" в переменной $idx будет храниться индекс текущего обрабатываемого элемента массива, а в переменной $elem будет храниться значение текущего обрабатываемого элемента массива, и обе эти переменных можно использовать для замен <#elem#> или <#idx#> в обрабатываемом файле "testrepeat_file.html" (что, собственно, и происходит).
    В начале функции "makeRepeat" определяется переменная возврата $res, которая сначала равна пустой строке, но на каждой итерации в эту переменную добавляется результат работы функции "parseStr" для текущего обработанного элемента массива.
  • parseTag - функция, которая будет применена переменной возврата $res по окончании обработки массива.
Строка, полученная из переменной возврата $res, подставляется вместо callback-тега.

ПРИМЕЧАНИЕ. С помощью функции "makeRepeat" можно также обрабатывать двумерные массивы, как ассоциативные, так и нумерованные.

Функция "makeBool" обрабатывает callback-тег вида (в квадратных скобках указаны необязательные атрибуты):

<callback 		name=makeBool 		var=имя_переменной 		[ delim=разделитель ] 		[ type=invert ] 		[ save=имя_глобальной_переменной ] 		[ func=имя_функции ]> true-часть [ разделитель ] [ false-часть ] </callback>
где содержимое тега представляет собой сложную конструкцию, состояющую из трех частей (в квадратных скобках указаны необязательные части), а атрибуты задают имя переменной, которая будет проверена на непустоту, и некоторые дополнительные параметры обработки:
  • var=имя_переменной (обязательный атрибут)
    имя переменной, которая будет проверена на непустоту;
    true-часть и false-часть - это две альтернативы; только одна из них будет обработана, в зависимости от того, установлен ли атрибут "type", и пуста ли заданная переменная;
    true-часть обрабатывается, если:
    • заданная переменная имеет ненулевое (непустое) значение и атрибут "type" не установлен;
    • заданная переменная пуста, но type=invert;
    в противном случае обрабатывается false-часть;
  • delim=разделитель
    если этот атрибут указан, то он должен содержать в качестве разделителя строку; эта строка будет использоваться в качестве разделителя между true- и false-частью; если этот атрибут не установлен, будет использоваться разделитель по умолчанию ( );
  • type=invert
    если этот атрибут указан и равен "invert", то вместо проверки на непустоту заданная переменная проверяется на пустоту.
  • save=имя_глобальной_переменной
    если этот атрибут указан, то в $GLOBALS [ имя_глобальной_переменной ] будет записан результат работы функции "makeBool";
  • func=имя_функции
    если этот атрибут указан, то к обрабатываемой части будет применена функция, заданная этим атрибутом.
ПРИМЕЧАНИЕ: Если разделитель не встречается внутри содержимого тега, то всё содержимое тега считается true-частью, а в качестве false-части принимается пустая строка.

Пример вызова функции "makeBool" :

<!-- главный обрабатываемый файл "testbool_file.html" --> This is the demo how to call "makeBool" function by "callback"-tag:<BR><BR> The color of the string below depends on $color value. <BR> If $color is empty, then the string below is <em><strong>black</strong></em>.<BR> Otherwise, the string has the same color that $color value. <BR> <span style="color:<callback 				name=makeBool 				var=color 				func=parseStr><#color#> black</callback>"> <strong>Test the color</strong> </span> <? /* тестовый PHP-скрипт : test5.php */ // путь к файлам библиотеки, define('INCLUDE_DIR', 'parse/'); // инициализация библиотеки require_once(INCLUDE_DIR.'init.inc.php'); // инициализация переменной $color // попробуйте поменять значения этой переменной, // чтобы увидеть, как изменится цвет тестовой строки $color = 'magenta'; // инициализация исходной строки $str = join('', file('testbool_file.html')); // вызов функции-обработчика "parseTag" в PHP-скрипте echo parseTag($str); ?>
Результат работы функции "parseTag" :


This is the demo how to call "makeBool" function by "callback"-tag:

The color of the string below depends on $color value.
If $color is empty, then the string below is black.
Otherwise, the string has the same color that $color value.
Test the color

 

Как это работает? Как только функция "parseTag" встречает в тексте callback-тег

<callback 	name=makeBool 	var=color 	func=parseStr><#color#> black</callback>
тут же вызывается функция "makeBool", где
  • $color - имя проверяемой переменной;
  • <#color#> - true-часть;
  • - разделитель;
  • black - false-часть;
  • parseStr - функция, которая будет применяться к выбранной части;
    Поскольку в данном примере переменная $color непуста и атрибут "type" не установлен, то будет использоваться true-часть.
      Строка, полученная в результате обработки true-части с помощью функции "parseStr", подставляется вместо callback-тега.

    Описание файлов библиотеки

    Наверх

    Библиотека разбита на 7 файлов.

    Основные (обязательные) файлы библиотеки:
    init.inc.php поскольку инициализация библиотеки нетривиальна, то для облегчения ее использования создан специальный файл - "init.inc.php", который выполняет все необходимые инициализации и подключает все необходимые файлы; в нем же создается глобальная переменная-экземпляр класса, содержащая правила парсинга (подробней о самом классе - см. файл "settings.inc.php").
    В библиотеке существует имя глобальной переменной "по умолчанию" - его можно переопределить в файле "const.inc.php". Все функции-обработчики требуют этот параметр, а в случае, если он не указан, используется имя default-ной глобальной переменной.
    Если использовать файл "init.inc.php" без изменений, в нем ВСЕГДА создается default-ная глобальная переменная, которая содержит правила парсинга "по умолчанию". Переопределить эти правила можно в файле "const.inc.php".
    Если требуется определить несколько переменных, содержащих различные правила парсинга - лучше всего делать это именно в "init.inc.php".
    const.inc.php в этом файле определены основные константы, используемые "по умолчанию", такие как правила парсинга "по умолчанию", и др., а также подключается файл "misc.inc.php"
    main.inc.php в этом файле определены функции-обработчики, составляющие "ядро" библиотеки; только эти функции вызываются напрямую в PHP-скриптах. Все остальные функции библиотеки определены в других файлах и вызываются в процессе парсинга.
    Основная функциональность заложена в трех функциях:
    • "parseStr" - обработка строки,
    • "parseFile" - обработка файла, и
    • "parseTag" - обработка тегов специального вида.
    settings.inc.php настройки, используемые при парсинге, например, допустимые символы в имени переменных, допустимые пути к подключаемым файлам, и т.д., вынесены в отдельный класс для увеличения скорости работы библиотеки; этот класс называется "parseRules" и инициализируется при создании значениями "по умолчанию". Обычно это происходит в файле "init.inc.php".
    Настройки парсинга, вынесенные в отдельный класс, не только способствуют увеличению скорости работы библиотеки, но также позволяют создавать внутри одного скрипта несколько переменных-экземпляров этого класса с различными правилами парсинга, и использовать их одновременно.
    misc.inc.php все вспомогательные функции собраны в этом файле

    Дополнительные (необязательные) файлы библиотеки:
    adv.inc.php в этом файле находятся дополнительные функции-обработчики, которые охватывают наиболее часто встречающиеся ситуации:
    • "fileInclude" - возвращает содержимое файла, считанное в строку по заданному имени файла;
    • "makeRepeat" - применяет заданную функцию к каждому элементу заданного массива; результат работы функции поэлементно накапливается и возвращается в виде строки после обработки последнего элемента массива;
    • "makeBool" - в зависимости от заданной переменной возвращает один из двух возможных результатов.
    userfunc.inc.php в этом файле могут быть размещены функции, определенные пользователем, и используемые в специальных тегах во время парсинга (описание специальных тегов см. в разделе "Callback-теги").

     
    Автор: Felenka
     
    Оригинал статьи: http://www.woweb.ru/publ/59-1-0-366