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，该 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 的语法相同，只是需要使用 PHP 或 Twig 来替换 Ruby。

请参阅教程和参考

性能

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：用script标签包装
less*：编译为Lesscss
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框架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相同）。

mthaml / mthaml

维护者

详细信息