README

MtHaml 是 HAML 语言的 PHP 实现，可以针对多种语言进行目标化。

目前支持的目标是 PHP 和 Twig，新的目标可以轻松添加。

Mt-Haml 实现了与 ruby-haml 完全相同的语法；唯一的区别是任何支持的语言都可以在 HAML 预期 Ruby 代码的地方使用。

HAML/Twig

%ul#users
  - for user in users
    %li.user
      = user.name
      Email: #{user.email}
      %a(href=user.url) Home page

渲染

<ul id="users">
  {% for user in users %}
    <li class="user">
      {{ user.name }}
      Email: {{ user.email }}
      <a href="{{ user.url }}">Home page</a>
    </li>
  {% endfor %}
</ul>

HAML/PHP

%ul#users
  - foreach($users as $user)
    %li.user
      = $user->getName()
      Email: #{$user->getEmail()}
      %a(href=$user->getUrl()) Home page

渲染

<ul id="users">
  <?php foreach($users as $user) { ?>
    <li class="user">
      <?php echo $user->getName(); ?>
      Email: <?php echo $user->getEmail(); ?>
      <a href="<?php echo $user->getUrl(); ?>">Home page</a>
    </li>
  <?php } ?>
</ul>

用法

PHP

<?php
$haml = new MtHaml\Environment('php');
$executor = new MtHaml\Support\Php\Executor($haml, array(
    'cache' => sys_get_temp_dir().'/haml',
));

// Compiles and executes the HAML template, with variables given as second
// argument
$executor->display('template.haml', array(
    'var' => 'value',
));

Twig:

<?php
$haml = new MtHaml\Environment('twig', array('enable_escaper' => false));

// Use a custom loader, whose responsibility is to convert HAML templates
// to Twig syntax, before handing them out to Twig:
$hamlLoader = new MtHaml\Support\Twig\Loader($haml, $twig->getLoader());
$twig->setLoader($hamlLoader);

// Register the Twig extension before executing a HAML template
$twig->addExtension(new MtHaml\Support\Twig\Extension());

// Render templates as usual
$twig->render('template.haml', ...);

请参阅 示例 和 使用 Twig 与 MtHaml

转义

MtHaml 默认转义一切。由于 Twig 已经支持自动转义，建议在 Twig 中启用它，并在 MtHaml 中禁用它

new MtHaml\Environment('twig', array('enable_escaper' => false));

启用自动转义时，HAML/PHP 的渲染方式如下

Email #{$user->getEmail()}
%a(href=$user->getUrl()) Home page

Email <?php echo htmlspecialchars($user->getEmail(), ENT_QUOTES, 'UTF-8'); ?>
<a href="<?php echo htmlspecialchars($user->getUrl(), ENT_QUOTES, 'UTF-8'); ?>">Home page</a>

Twig

在 HAML 中使用 Twig 可以更精确地控制可以执行的内容，暴露给模板的变量和函数等。这也允许使用 Twig 的所有出色功能，如模板继承、宏、块、过滤器、函数、测试等。

- extends "some-template.haml"

- macro printSomething()
  %p something

- block body
  %h1 Title
  = _self.printSomething()

在 Twig 中的集成

MtHaml 附带一个示例 Twig_Loader，它将在加载时自动将 HAML 转换为 Twig（然后 Twig 将编译生成的 Twig 脚本并将其缓存）。扩展名为 .haml 的模板或其源以 {% haml %} 开头的模板将被转换，其他模板将被保留不变。

该加载器作为代理，并接受另一个加载器作为参数

<?php

$haml = new MtHaml\Environment(...);

$twig_loader = new Twig_Loader_Filesystem(...);
$twig_loader = new MtHaml\Support\Twig\Loader($haml, $twig_loader);

运行时支持

在某些情况下，编译后的 MtHaml/Twig 模板需要在运行时得到 MtHaml 的支持。因此，在执行模板之前必须加载 Twig 扩展。

<?php
// Register the MtHaml extension before executing the template:
$twig->addExtension(new MtHaml\Support\Twig\Extension());
$twig->render("rendered_twig_template.twig");

语法

语法与 HAML/Ruby 的语法相同，只是在 Ruby 应用的地方必须使用 PHP 或 Twig。

请参阅 教程 和 参考

性能

MtHaml 将 HAML 转换为 PHP 或 Twig 代码。生成的代码可以缓存并多次执行，且在运行时不依赖于 HAML。

MtHaml 没有运行时开销。

辅助函数

HAML/Ruby 中的辅助函数只是暴露给模板的 Ruby 函数。任何函数都可以通过目标语言（该函数只需在运行时可用）提供给 HAML 模板。

在 HAML/Twig 中，可以使用所有 Twig 的函数、过滤器和标签。在 HAML/PHP 中，可以使用所有 PHP 函数。

过滤器

过滤器接受纯文本输入（支持 #{...} 插值），并对其进行转换或包装。

使用 javascript 过滤器的示例

%p something
:javascript
  some.javascript.code("#{var|escape('js')}");

<p>something</p>
<script type="text/javascript">
//<![CDATA[
  some.javascript.code("{{ var|escape('js') }}");
//]]>
</script>

以下过滤器可用

• css：用样式标签包裹
• cdata：用 CDATA 标记包裹
• coffee*：将 coffeescript 编译成 javascript
• escaped：HTML 转义
• javascript：用脚本标签包裹
• less*：将 lesscss 编译成 css
• markdown*：将 markdown 转换为 html
• php：将输入作为 php 代码执行
• plain：不解析过滤后的文本
• preseve：保留预格式化文本
• scss*：将 scss 转换为 css
• twig：将输入作为 twig 代码执行

带有 * 标记的过滤器有运行时依赖，默认情况下不可用。此类过滤器需要显式地提供给 MtHaml\Environment。

使用 Coffee 过滤器的示例

<?php

$coffeeFilter = new MtHaml\Filter\CoffeeScript(new CoffeeScript\Compiler);

$env = new MtHaml\Environment('twig', array(
    'enable_escaper' => false,
), array(
    'coffee' => $coffeeFilter,
));

Sass

Sass 可用于 PHP 项目而不会出现问题。它只依赖于 Ruby，且不需要在生产服务器上安装。因此，MtHaml 不会重新实现 Sass。

框架和 CMS 支持

• CakePHP: https://github.com/TiuTalk/haml
• Drupal: https://github.com/antoinelafontaine/oxide
• FuelPHP: https://github.com/fuel/parser
• Laravel (PHP): https://github.com/BKWLD/laravel-haml
• Laravel (Twig): https://github.com/SimonDegraeve/laravel-twigbridge
• PHPixie: https://github.com/dracony/PHPixie-HAML
• Silex: https://github.com/arnaud-lb/Silex-MtHaml
• Sprockets-PHP: https://github.com/Nami-Doc/Sprockets-PHP
• Symfony2: https://github.com/arnaud-lb/MtHamlBundle
• Yii2 框架: https://github.com/mervick/yii2-mthaml
• Zend Framework 1: https://github.com/bonndan/mthaml-zf1
• PhileCMS: https://bitbucket.org/jacmoe/templatemthaml

添加您的： https://github.com/arnaud-lb/MtHaml/edit/master/README.markdown

许可证

MtHaml 采用 MIT 许可证发布（与 HAML/Ruby 相同）。