Добрый день! Документации еще нет. modxSmarty примеры есть на самой страничке пакета.
По поводу MODX-тегов в phpTemplates. Здесь никаких ограничений как бы и нет. Есть только одно условие — статический php-шаблон обязательно должен выполнять возврат конечного результата. То есть нельзя использовать print, echo и т.п., а так же писать вольный HTML. Это связано с тем, что шаблон должен отдать этот код дальше MODX-парсеру. Первые версии пакета позволяли использовать произвольный код, но с этим возникло много подводных камней, включая тонкости с кешированием, по этому сейчас все только через return $результат. Но вы свободно можете возвращать конечный код вперемешку с MODX-тегами, к примеру так:
$output = '<p>[[++site_name]]</p>'; return $output;
То есть в данном случае даже не используется modxSmarty. Вы просто выполняете произвольный php-код и возвращаете результат. Так же вы совершенно легко можете MODX-теги использовать в Smarty-шаблонах, но есть писать [[snippet]] и т.п. Но в данном случае надо учитывать, что этот тег уже будет обрабатываться самим MODX-парсером, из-за чего вы проигрываете в скорости. Так что в Smarty-шаблонах можно непосредственно вызывать метод {snippet name=«snippet_name» params=""}. В итоге в конечный код попадет уже результат выполнения сниппета.
Есть еще один очень важный момент с phpTemplates: сейчас по умолчанию все MODX-шаблоны кешируемые. То есть если страница уже выполнялась (на нее заходили), то при повторном заходе на нее php-шаблон не вызывается. Весь код страницы стандартно берется из кеша, и повторно выполняться будут только некешируемые MODX-теги (вот их как раз и имеет смысл использовать в Smarty-шаблонах там, где элемент должен выполняться при каждом заходе на страницу). Если же вам надо, чтобы при каждом заходе на страницу выполнялся php-шаблон, то в MODX-шаблоне создайте логическую переменную-параметр phptemplates.non-cached и установите ей значение 1. В таком случае шаблон будет отрабатываться при каждом заходе на страницу. Но здесь надо еще учитывать кеширование Smarty. В настройках modxSmarty есть параметр modxSmarty.caching. Все это выглядит довольно запутанно, но на самом деле имеет смысл, и позволяет кеширование настроить очень гибко под различные задачи.