Парсер pdoTools — быстрая обработка чанков и тегов в MODX

Парсер pdoTools представляет собой отдельный класс который прописывается в системных настройках MODX и перехватывает обработку тегов на странице. Начиная с версии 2.1.1-pl компонент включается по умолчанию при установке и значительно ускоряет работу сайта за счет оптимизированной обработки плейсхолдеров и чанков. Основная задача pdoParser — быстро разбирать теги модекса без создания лишних объектов в памяти, что делает его существенно производительнее стандартного modParser.

​Если по каким-то причинам вам нужно отключить парсер, достаточно удалить две системные настройки: parser_class (имя класса парсера) и parser_class_path (путь к классу парсера). По умолчанию в MODX Revolution эти настройки отсутствуют, они создаются только для подключения стороннего парсера.

​Принцип работы парсера

Парсер pdoTools может быть использован в двух основных случаях работы с контентом.

​Рендер чанков сниппетом

Это происходит всегда и во всех сниппетах использующих библиотеку pdoTools, независимо от системных настроек модекса. Каждый раз когда сниппет из пакета PdoTools обрабатывает чанк, автоматически задействуется оптимизированный парсер для максимальной производительности.

Рендер всей страницы

Работает только если парсер включен в настройках системы через параметры parser_class и parser_class_path. В этом режиме pdoParser обрабатывает не только чанки, но и весь контент страницы включая шаблоны и ресурсы.

При использовании этого парсера все чанки и дополнения MODX обрабатываются немного быстрее, потому что он не создает лишних объектов modElement. Парсер берет на себя только простые теги типа [[+id]] и [[~15]], оставляя условия и фильтры стандартному modParser.

Обработка чанков

В классе pdoTools для обработки чанков предусмотрены два метода, очень похожих на методы класса modX.

Метод getChunk

Объявление метода выглядит следующим образом:

getChunk(string $chunkName, array $properties, bool $fastMode = false)

Третий параметр $fastMode вырезает все оставшиеся необработанные плейсхолдеры чтобы не было лишних тегов на странице. Если этого не сделать, парсер будет пытаться рекурсивно разобрать эти теги до 10 итераций по умолчанию, что может привести к замедлению работы.

Рекурсивный парсер — это одно из достоинств MODX Revolution и специально оставленные теги очень часто встречаются в логике работы сниппетов системы. Поэтому fastMode отключен по умолчанию и использовать его нужно только если вы уверены в том что делаете.

Парсер pdoTools не будет вызывать системный парсер если смог самостоятельно разобрать все плейсхолдеры. Если же в чанке остались какие-то вызовы фильтров или сниппетов, то работа передается в modParser что требует дополнительное время на обработку.

Метод parseChunk

Этот метод объявлен с такой сигнатурой:

parseChunk(string $name, array $properties, string $prefix = '[[+', string $suffix = ']]')

Основная особенность работы обоих методов заключается в том что для загрузки чанка используется защищенный метод _loadChunk, который может не только загружать чанк из базы данных но и превращать в него произвольные строки.

Варианты вызова чанков

Оба метода pdoTools поддерживают несколько видов имен чанков с использованием специальных префиксов.

Инлайн-чанки (@INLINE или @CODE)

Один из самых популярных вариантов — указание тела чанка прямо на странице. Это очень удобно для небольших шаблонов которые не хочется выносить в отдельные файлы или записи базы данных.

В таком указании есть важная особенность о которой многие разработчики не задумываются — все плейсхолдеры внутри чанка будут обработаны парсером до вызова сниппета. Если в памяти системы выставлены плейсхолдеры [[+id]] или [[+pagetitle]], то в сниппет придет уже обработанный чанк и вы получите одинаковые строки на странице.

Именно поэтому в примерах используются необычные плейсхолдеры {{+}} вместо [[+]]. Системный парсер их не трогает, а pdoTools заменяет их на нормальные во время работы. Вы можете использовать фигурные скобки в качестве обрамления плейсхолдеров во всех чанках pdoTools — он сам превратит их в [[+]] при загрузке.

По этой же причине у вас никогда не будут работать вызовы сниппетов и фильтров в INLINE чанках если используется стандартный синтаксис. Вот так работать не будет:

А вот так — без проблем с использованием фигурных скобок:

Помните об этом нюансе при использовании INLINE чанков в проектах на MODX Revolution.

Файловые чанки (@FILE)

Многие разработчики считают недостатком MODX то что он не умеет хранить чанки в файлах и вынуждает работать с базой данных. Это неудобно для систем контроля версий типа Git и может быть медленнее при большом количестве элементов.

PdoTools открывает возможность работы с файловыми чанками при указании префикса @FILE:

В целях безопасности использовать можно только файлы с расширением html и tpl, и только из определенной заранее заданной директории в настройке pdotools_elements_path. По умолчанию это директория {core_path}elements/ но вы можете изменить ее в системных настройках.

Вы можете указать свою собственную директорию для файлов через параметр &elementsPath непосредственно в вызове сниппета:

Файл будет загружен из /core/elements/resources/mychunk.tpl относительно корня сайта. Этот способ особенно удобен при работе с системами контроля версий, так как все изменения автоматически отслеживаются.

Шаблоны ресурсов (@TEMPLATE)

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

Если указан пустой шаблон и в выбранных записях есть поле template с идентификатором или именем шаблона, то запись будет обернута в этот шаблон:

Это аналог сниппета renderResources для модекса. При выводе шаблона можно указывать и набор параметров как у сниппетов:

Тогда значения из этого набора свойств будут вставлены в шаблон и доступны как плейсхолдеры.

Обычные чанки (@CHUNK)

Это режим по умолчанию который загружает чанк из базы данных MODX Revolution:

Точно так же поддерживаются и наборы параметров через символ @:

Префикс @CHUNK можно использовать явно, он оставлен для совместимости со сторонними сниппетами:

Эти способы загрузки чанков работают во всех родных сниппетах pdoTools и во всех других компонентах которые используют методы pdoTools getChunk и parseChunk.​

Теги fastField для быстрого доступа

В конце 2012 года был представлен небольшой плагин с добавлением новых тегов парсеру MODX который затем вырос в компонент fastField. Он добавляет в систему обработку дополнительных плейсхолдеров типа [[#15.pagetitle]] для быстрого доступа к данным других ресурсов.

С разрешения автора этот функционал включен в pdoParser и даже немного расширен. Все теги fastField начинаются с символа # и дальше содержат или идентификатор нужного ресурса, или название глобального массива.

Вывод полей ресурсов

Обычные поля документов выводятся через идентификатор и название поля:

TV параметры ресурсов доступны по такому же принципу:

Поля товаров miniShop2 также можно выводить через fastField:

Работа с массивами данных

Массивы ресурсов и товаров доступны через точечную нотацию:

Если вы не знаете какие значения находятся внутри массива — просто укажите его и он будет распечатан полностью:

Суперглобальные массивы PHP

Парсер pdoTools позволяет получать данные из суперглобальных массивов PHP прямо в шаблонах:

Можно указывать любые поля в массивах используя точку как разделитель:

Комбинация с тегами MODX

Теги fastField можно сочетать с обычными тегами MODX Revolution для создания динамических конструкций:

Это позволяет создавать гибкие шаблоны которые автоматически подстраиваются под структуру сайта. Все эти теги pdoTools обрабатывает без создания объектов modElement, поэтому работает заметно быстрее чем родные методы модекса.

Шаблонизатор Fenom в pdoParser

Поддержка шаблонизатора Fenom появилась в pdoTools с версии 2.0, после чего компонент стал требовать PHP версии 5.3 и выше. Он работает гораздо быстрее чем родной modParser, и если вы перепишете свой чанк так что в нем не будет ни одного тега MODX, то modParser вовсе не будет запускаться.

При этом одновременная работа и старых тегов и новых в одном чанке допускается — parserMODX обработает свои теги, а Fenom свои. На обработку через шаблонизатор влияют несколько системных настроек:

• pdotools_fenom_default — включает обработку через Fenom чанков pdoTools, включено по умолчанию
• pdotools_fenom_parser — включает обработку шаблонизатором всех страниц сайта включая контент и шаблоны
• pdotools_fenom_cache — кеширование скомпилированных шаблонов для повышения производительности

По умолчанию Fenom включен для работы только в чанках которые проходят через pdoTools. Это вполне безопасно и менеджеры системы не получают никаких дополнительных возможностей кроме более удобного синтаксиса и высокой скорости работы.

Включение параметра pdotools_fenom_parser позволяет использовать синтаксис Fenom прямо в контенте документов и шаблонах страниц. Важная особенность — условия в Fenom выполняются до парсинга, что означает более эффективную работу:

В этом примере в зависимости от $_GET['test'] на странице будет запущен или один сниппет или другой. Парсер MODX Revolution же запустил бы оба и результат выполнения одного неподходящего просто не показал.

Преимущества pdoParser

Использование парсера pdoTools дает несколько существенных преимуществ перед стандартным парсером MODX Revolution.

Производительность. Основное преимущество — скорость работы за счет отсутствия создания объектов modElement для простых операций. Парсер обрабатывает простые плейсхолдеры напрямую используя регулярные выражения и замену строк, что работает в разы быстрее полноценного парсинга.

​Гибкость работы с чанками. Возможность использования разных типов чанков (@INLINE, @FILE, @TEMPLATE) без изменения кода сниппетов. Это позволяет выбирать оптимальный способ хранения шаблонов для каждого конкретного проекта.

​Теги fastField. Встроенная поддержка быстрого доступа к данным других ресурсов и глобальных массивов без создания дополнительных объектов. Это особенно удобно когда нужно вывести одно-два поля из другого документа без вызова полноценного сниппета.

​Интеграция с Fenom. Возможность использования современного шаблонизатора с условиями циклами и фильтрами прямо в чанках. При этом сохраняется полная совместимость со старым синтаксисом MODX Revolution.

​

Парсер pdoTools представляет собой отдельный класс который прописывается в системных настройках MODX и перехватывает обработку тегов на странице. Начиная с версии 2.1.1-pl компонент включается по умолчанию при установке и значительно ускоряет работу сайта за счет оптимизированной обработки плейсхолдеров и чанков. Основная задача pdoParser — быстро разбирать теги модекса без создания лишних объектов в памяти, что делает его существенно производительнее стандартного modParser.
Если по каким-то причинам вам нужно отключить парсер, достаточно удалить две системные настройки: parser_class (имя класса парсера) и parser_class_path (путь к классу парсера). По умолчанию в MODX Revolution эти настройки отсутствуют, они создаются только для подключения стороннего парсера.

Принцип работы парсера

Парсер pdoTools может быть использован в двух основных случаях работы с контентом.

Рендер чанков сниппетом

Это происходит всегда и во всех сниппетах использующих библиотеку pdoTools, независимо от системных настроек модекса. Каждый раз когда сниппет из пакета PdoTools обрабатывает чанк, автоматически задействуется оптимизированный парсер для максимальной производительности.

Рендер всей страницы

Работает только если парсер включен в настройках системы через параметры parser_class и parser_class_path. В этом режиме pdoParser обрабатывает не только чанки, но и весь контент страницы включая шаблоны и ресурсы.
При использовании этого парсера все чанки и дополнения MODX обрабатываются немного быстрее, потому что он не создает лишних объектов modElement. Парсер берет на себя только простые теги типа [[+id]] и [[~15]], оставляя условия и фильтры стандартному modParser.

Обработка чанков

В классе pdoTools для обработки чанков предусмотрены два метода, очень похожих на методы класса modX.

Метод getChunk

Объявление метода выглядит следующим образом:

getChunk(string $chunkName, array $properties, bool $fastMode = false)

Метод загружает указанный чанк (следуя указанию @BINDING если есть) и полностью обрабатывает его, заменяя все плейсхолдеры на переданные значения из параметра $properties. Это основной способ работы с шаблонами в pdoTools, рассчитанный на максимальную производительность и функциональность.
Третий параметр $fastMode вырезает все оставшиеся необработанные плейсхолдеры чтобы не было лишних тегов на странице. Если этого не сделать, парсер будет пытаться рекурсивно разобрать эти теги до 10 итераций по умолчанию, что может привести к замедлению работы.
Рекурсивный парсер — это одно из достоинств MODX Revolution и специально оставленные теги очень часто встречаются в логике работы сниппетов системы. Поэтому fastMode отключен по умолчанию и использовать его нужно только если вы уверены в том что делаете.
Парсер pdoTools не будет вызывать системный парсер если смог самостоятельно разобрать все плейсхолдеры. Если же в чанке остались какие-то вызовы фильтров или сниппетов, то работа передается в modParser что требует дополнительное время на обработку.

Метод parseChunk

Этот метод объявлен с такой сигнатурой:

parseChunk(string $name, array $properties, string $prefix = '[[+', string $suffix = ']]')

Он также создает чанк из указанного имени, разбирая @BINDING если есть, а потом просто заменяет плейсхолдеры на значения без особых обработок. Это самый простой и быстрый способ оформления данных в чанки, когда не требуется запуск дополнительных сниппетов или фильтров.
Основная особенность работы обоих методов заключается в том что для загрузки чанка используется защищенный метод _loadChunk, который может не только загружать чанк из базы данных но и превращать в него произвольные строки.

Варианты вызова чанков

Оба метода pdoTools поддерживают несколько видов имен чанков с использованием специальных префиксов.

Инлайн-чанки (@INLINE или @CODE)

Один из самых популярных вариантов — указание тела чанка прямо на странице. Это очень удобно для небольших шаблонов которые не хочется выносить в отдельные файлы или записи базы данных.
[[!pdoResources? &parents=`0` &tpl=`@INLINE <p>[[+id]] - [[+pagetitle]]</p>` ]]
В таком указании есть важная особенность о которой многие разработчики не задумываются — все плейсхолдеры внутри чанка будут обработаны парсером до вызова сниппета. Если в памяти системы выставлены плейсхолдеры [[+id]] или [[+pagetitle]], то в сниппет придет уже обработанный чанк и вы получите одинаковые строки на странице.
Именно поэтому в примерах используются необычные плейсхолдеры {{+}} вместо [[+]]. Системный парсер их не трогает, а pdoTools заменяет их на нормальные во время работы. Вы можете использовать фигурные скобки в качестве обрамления плейсхолдеров во всех чанках pdoTools — он сам превратит их в [[+]] при загрузке.
[[!pdoResources? &parents=`0` &tpl=`@INLINE <p>{{+id}} - {{+pagetitle}}</p>` ]]
По этой же причине у вас никогда не будут работать вызовы сниппетов и фильтров в INLINE чанках если используется стандартный синтаксис. Вот так работать не будет:
[[!pdoResources? &parents=`0` &tpl=`@INLINE <p>[[+id]] - [[+pagetitle:default=`название страницы`]]</p>` ]]
А вот так — без проблем с использованием фигурных скобок:
[[!pdoResources? &parents=`0` &tpl=`@INLINE <p>{{+id}} - {{+pagetitle:default=`название страницы`}}</p>` ]]
Помните об этом нюансе при использовании INLINE чанков в проектах на MODX Revolution.

Файловые чанки (@FILE)

Многие разработчики считают недостатком MODX то что он не умеет хранить чанки в файлах и вынуждает работать с базой данных. Это неудобно для систем контроля версий типа Git и может быть медленнее при большом количестве элементов.
PdoTools открывает возможность работы с файловыми чанками при указании префикса @FILE:
[[!pdoResources? &parents=`0` &tpl=`@FILE resources/mychunk.tpl` ]]
В целях безопасности использовать можно только файлы с расширением html и tpl, и только из определенной заранее заданной директории в настройке pdotools_elements_path. По умолчанию это директория {core_path}elements/ но вы можете изменить ее в системных настройках.
Вы можете указать свою собственную директорию для файлов через параметр &elementsPath непосредственно в вызове сниппета:
[[!pdoResources? &parents=`0` &tpl=`@FILE resources/mychunk.tpl` &elementsPath=`/core/elements` ]]
Файл будет загружен из /core/elements/resources/mychunk.tpl относительно корня сайта. Этот способ особенно удобен при работе с системами контроля версий, так как все изменения автоматически отслеживаются.

Шаблоны ресурсов (@TEMPLATE)

Этот тип чанка позволяет использовать шаблоны системы (объекты modTemplate) для оформления вывода. Это удобно когда нужно обернуть данные в полноценный шаблон страницы.
[[!pdoResources? &parents=`0` &tpl=`@TEMPLATE Base Template` ]]
Если указан пустой шаблон и в выбранных записях есть поле template с идентификатором или именем шаблона, то запись будет обернута в этот шаблон:
[[!pdoResources? &parents=`0` &tpl=`@TEMPLATE` ]]
Это аналог сниппета renderResources для модекса. При выводе шаблона можно указывать и набор параметров как у сниппетов:
[[!pdoResources? &parents=`0` &tpl=`@TEMPLATE Base Template@MyPropertySet` ]]
Тогда значения из этого набора свойств будут вставлены в шаблон и доступны как плейсхолдеры.

Обычные чанки (@CHUNK)

Это режим по умолчанию который загружает чанк из базы данных MODX Revolution:
[[!pdoResources? &parents=`0` &tpl=`MyChunk` ]]
Точно так же поддерживаются и наборы параметров через символ @:
[[!pdoResources? &parents=`0` &tpl=`MyChunk@MyPropertySet` ]]
Префикс @CHUNK можно использовать явно, он оставлен для совместимости со сторонними сниппетами:
[[!pdoResources? &parents=`0` &tpl=`@CHUNK tpl.Resource.row` ]]
Эти способы загрузки чанков работают во всех родных сниппетах pdoTools и во всех других компонентах которые используют методы pdoTools getChunk и parseChunk.

Теги fastField для быстрого доступа

В конце 2012 года был представлен небольшой плагин с добавлением новых тегов парсеру MODX который затем вырос в компонент fastField. Он добавляет в систему обработку дополнительных плейсхолдеров типа [[#15.pagetitle]] для быстрого доступа к данным других ресурсов.
С разрешения автора этот функционал включен в pdoParser и даже немного расширен. Все теги fastField начинаются с символа # и дальше содержат или идентификатор нужного ресурса, или название глобального массива.

Вывод полей ресурсов

Обычные поля документов выводятся через идентификатор и название поля:
[[#15.pagetitle]] [[#20.content]] [[#123.longtitle]]
TV параметры ресурсов доступны по такому же принципу:
[[#15.date]] [[#20.some_tv]] [[#25.image]]
Поля товаров miniShop2 также можно выводить через fastField:
[[#21.price]] [[#22.article]] [[#30.vendor]]

Работа с массивами данных

Массивы ресурсов и товаров доступны через точечную нотацию:
[[#12.properties.somefield]] [[#15.size.1]] [[#20.colors.2]]
Если вы не знаете какие значения находятся внутри массива — просто укажите его и он будет распечатан полностью:
[[#GET]] [[#15.colors]] [[#12.properties]]

Суперглобальные массивы PHP

Парсер pdoTools позволяет получать данные из суперглобальных массивов PHP прямо в шаблонах:
[[#POST.key]] [[#SESSION.another_key]] [[#GET.key3]] [[#REQUEST.key]] [[#SERVER.key]] [[#FILES.key]] [[#COOKIE.some_key]]
Можно указывать любые поля в массивах используя точку как разделитель:
[[#15.properties.key1.key2]] [[#GET.filters.category]]

Комбинация с тегами MODX

Теги fastField можно сочетать с обычными тегами MODX Revolution для создания динамических конструкций:
[[#[[++site_start]].pagetitle]] [[#[[*parent]].longtitle]] [[#[[++site_start]]]]
Это позволяет создавать гибкие шаблоны которые автоматически подстраиваются под структуру сайта. Все эти теги pdoTools обрабатывает без создания объектов modElement, поэтому работает заметно быстрее чем родные методы модекса.

Шаблонизатор Fenom в pdoParser

Поддержка шаблонизатора Fenom появилась в pdoTools с версии 2.0, после чего компонент стал требовать PHP версии 5.3 и выше. Он работает гораздо быстрее чем родной modParser, и если вы перепишете свой чанк так что в нем не будет ни одного тега MODX, то modParser вовсе не будет запускаться.
При этом одновременная работа и старых тегов и новых в одном чанке допускается — parserMODX обработает свои теги, а Fenom свои. На обработку через шаблонизатор влияют несколько системных настроек:

• pdotools_fenom_default — включает обработку через Fenom чанков pdoTools, включено по умолчанию
• pdotools_fenom_parser — включает обработку шаблонизатором всех страниц сайта включая контент и шаблоны
• pdotools_fenom_cache — кеширование скомпилированных шаблонов для повышения производительности

По умолчанию Fenom включен для работы только в чанках которые проходят через pdoTools. Это вполне безопасно и менеджеры системы не получают никаких дополнительных возможностей кроме более удобного синтаксиса и высокой скорости работы.
Включение параметра pdotools_fenom_parser позволяет использовать синтаксис Fenom прямо в контенте документов и шаблонах страниц. Важная особенность — условия в Fenom выполняются до парсинга, что означает более эффективную работу:
{if $.get.test == 1} [[!pdoResources?parents=`0`]] {else} [[!pdoMenu?parents=`0`]] {/if}
В этом примере в зависимости от $_GET['test'] на странице будет запущен или один сниппет или другой. Парсер MODX Revolution же запустил бы оба и результат выполнения одного неподходящего просто не показал.

Преимущества pdoParser

Использование парсера pdoTools дает несколько существенных преимуществ перед стандартным парсером MODX.

• Производительность. Основное преимущество — скорость работы за счет отсутствия создания объектов modElement для простых операций. Парсер обрабатывает простые плейсхолдеры напрямую используя регулярные выражения и замену строк, что работает в разы быстрее полноценного парсинга.
• Гибкость работы с чанками. Возможность использования разных типов чанков (@INLINE, @FILE, @TEMPLATE) без изменения кода сниппетов. Это позволяет выбирать оптимальный способ хранения шаблонов для каждого конкретного проекта.
• Теги fastField. Встроенная поддержка быстрого доступа к данным других ресурсов и глобальных массивов без создания дополнительных объектов. Это особенно удобно когда нужно вывести одно-два поля из другого документа без вызова полноценного сниппета.
• Интеграция с Fenom. Возможность использования современного шаблонизатора с условиями циклами и фильтрами прямо в чанках. При этом сохраняется полная совместимость со старым синтаксисом MODX Revolution.