README

Pug-php

Pug-php为Pug模板编译器添加了内联PHP脚本支持。自3.0版本起，它使用由tale-pug和pug-php开发者制作的非常可定制的Pug模板引擎Phug作为新的PHP Pug引擎参考。

安装

如果您还没有安装composer，请先安装： https://getcomposer.org.cn/download/

然后运行

composer require pug-php/pug

在您喜欢的框架中使用Pug

Phalcon: https://github.com/pug-php/pug-phalcon

Symfony: https://github.com/pug-php/pug-symfony

Laravel: https://github.com/BKWLD/laravel-pug

CodeIgniter: https://github.com/pug-php/ci-pug-engine

Yii 2: https://github.com/rmrevin/yii2-pug

Slim 3: https://github.com/MarcelloDuarte/pug-slim

Zend Expressive: https://github.com/kpicaza/infw-pug

使用

<?php

include 'vendor/autoload.php';

$pug = new Pug([
    // here you can set options
]);

$pug->displayFile('my-pug-template.pug');

从pug-php 3.1.2版本开始，您不再需要使用use Pug\Pug;导入类，因为我们提供了一个别名。

主要方法有render、renderFile、compile、compileFile、display、displayFile和setOption，完整的文档请见此处：phug-lang.com。

您还可以使用外观来静态调用方法

<?php

use Pug\Facade as PugFacade;

include 'vendor/autoload.php';

$html = PugFacade::renderFile('my-pug-template.pug');

Pug选项

Pug选项应传递给构造函数

$pug = new Pug(array(
    'pretty' => true,
    'cache' => 'pathto/writable/cachefolder/'
));

本地变量支持

$pug = new Pug();
$output = $pug->render('file', array(
    'title' => 'Hello World'
));

pug-php 3 新特性

pug-php 3 现已与 pugjs 2 对齐，目标是完美实现 JS 项目。这也是为什么在这个新版本中会有破坏性变更。

查看变更日志以了解新增内容

若要从 pug-php 2 升级到 3，请参阅迁移指南

自定义过滤器支持

过滤器必须是可调用的：它可以是一个实现 __invoke() 方法的类或匿名函数。

$pug->filter('escaped', 'My\Callable\Class');

// or

$pug->filter('escaped', function($node, $compiler){
    foreach ($node->block->nodes as $line) {
        $output[] = $compiler->interpolate($line->value);
    }
    return htmlentities(implode("\n", $output));
});

内置过滤器

:css
:php
:javascript
:escaped
:cdata

使用 Composer 安装其他过滤器

http://pug-filters.selfbuild.fr/

发布您自己的过滤器

https://github.com/pug-php/pug-filter-base#readme

自定义关键字支持

您可以添加自定义关键字，以下是一些示例

匿名函数:

$pug->addKeyword('range', function ($args) {
    list($from, $to) = explode(' ', trim($args));

    return array(
        'beginPhp' => 'for ($i = ' . $from . '; $i <= ' . $to . '; $i++) {',
        'endPhp' => '}',
    );
});

$pug->render('
range 1 3
    p= i
');

这将渲染

<p>1</p>
<p>2</p>
<p>3</p>

请注意，现有的 for..in 操作符将具有此自定义 for 关键字的优先级。

可调用类:

class UserKeyword
{
    public function __invoke($arguments, $block, $keyWord)
    {
        $badges = array();
        foreach ($block->nodes as $index => $tag) {
            if ($tag->name === 'badge') {
                $href = $tag->getAttribute('color');
                $badges[] = $href['value'];
                unset($block->nodes[$index]);
            }
        }

        return array(
            'begin' => '<div class="' . $keyWord . '" data-name="' . $arguments . '" data-badges="[' . implode(',', $badges) . ']">',
            'end' => '</div>',
        );
    }
}

$pug->addKeyword('user', new UserKeyword());

$pug->render('
user Bob
    badge(color="blue")
    badge(color="red")
    em Registered yesterday
');

这将渲染

<div class="user" data-name="Bob" data-badges="['blue', 'red']">
    <em>Registered yesterday</em>
</div>

关键字必须返回一个数组（包含 begin 和/或 end 条目）或一个字符串（用作 begin 条目）。

begin 和 end 将作为原始 HTML 渲染，但您也可以使用 beginPhp 和 endPhp（如第一个示例所示）来渲染将围绕渲染块包裹的 PHP 代码（如果有的话）。

PHP 辅助函数

如果您想在模板中或所有模板中方便地使用 PHP 函数，请使用闭包并像任何其他变量一样传递它们

$myClosure = function ($string) {
    return 'Hey you ' . $string . ', out there on your own, can you hear me?';
};

$pug->render('p=$myClosure("Pink")', array('myClosure' => $myClosure));

这将渲染

<p>Hey you Pink, out there on your own, can you hear me?</p>

您可以使用 share 方法使该闭包对所有模板都可用，而无需在渲染参数中传递它

// ... $pug instantiation
$pug->share('myClosure', $myClosure);
$pug->render('p=$myClosure("Pink")');

这将渲染与上一个示例相同的 HTML。请注意，share 允许您传递任何类型的值。

缓存

重要：为了提高生产环境中的性能，请启用 Pug 缓存，将 cache 选项设置为可写目录，您可以在部署期间一次性缓存所有模板

$pug = new Pug(array(
    'cache' => 'var/cache/pug',
);
list($success, $errors) = $pug->cacheDirectory('path/to/pug/templates');
echo "$success files have been cached\n";
echo "$errors errors occurred\n";

确保没有意外错误发生，并且您的模板目录中的所有模板都已缓存。

然后，在生产环境中使用相同的缓存目录和模板目录，将选项 upToDateCheck 设置为 false 以绕过缓存检查并自动使用缓存版本

$pug = new Pug(array(
    'cache' => 'var/cache/pug',
    'basedir' => 'path/to/pug/templates',
    'upToDateCheck' => false,
);
$pug->render('path/to/pug/templates/my-page.pug');

来自 pug-js 的模板

首先记住 pug-php 是一个 PHP 模板引擎。Pug-js 和 Pug-php 都提供了 HAML 类似的语法和语言的一些抽象（循环、条件等）。但对于表达式和原始代码，pug-js 使用 JS，而 pug-php 使用 PHP。默认情况下，我们进行一些魔术操作，将简单的 JS 语法转换为 PHP。这应该有助于您在已经有一些模板的情况下更顺利地从 pug-js 迁移，同时又能享受到 PHP 的优势。

如果您开始一个新项目，我们强烈建议您使用以下选项

$pug = new Pug(array(
    'expressionLanguage' => 'php'
);

这将禁用所有翻译，因此您必须始终使用显式的PHP语法

- $concat = $foo . $bar
p=$concat

如果您想使用与JS非常接近的表达式，可以使用

$pug = new Pug(array(
    'expressionLanguage' => 'js'
);

这将允许在JS风格的语法中使用PHP和JS。但您必须坚持使用它，您将无法在此模式下混合PHP和JS。

最后，您可以使用本机pug-js引擎

$pug = new Pug(array(
    'pugjs' => true
);

此模式需要已安装node和npm，因为它将安装并直接调用它。此模式将扁平化您的局部变量（这意味着复杂的对象如DateTime或具有魔术方法的类将被转换为JSON的简单对象），您将无法从混合缩进、预/后渲染钩子等一些功能中受益。但在此模式下，您将获得与pug-js完全相同的输出。

使用pug-js将局部对象写入JSON文件

如果您的局部对象很大，可能会导致RuntimeException。这是因为局部对象被直接作为参数传递给pug-cli。要解决这个问题，您可以使用localsJsonFile选项

$pug = new Pug(array(
    'pugjs' => true,
    'localsJsonFile' => true
);

然后您的局部对象将被写入一个JSON文件，文件的路径将被传递给编译器。

Pug CLI

Pug还提供了一个CLI工具

./vendor/bin/pug render-file dir/my-template.pug --output-file

请在此处查看完整的CLI文档：完整CLI文档

检查需求

要检查您的环境是否准备好使用Pug，请使用requirements方法

$pug = new Pug(array(
    'cache' => 'pathto/writable/cachefolder/'
);
$missingRequirements = array_keys(array_filter($pug->requirements(), function ($valid) {
    return $valid === false;
}));
$missings = count($missingRequirements);
if ($missings) {
    echo $missings . ' requirements are missing.<br />';
    foreach ($missingRequirements as $requirement) {
        switch($requirement) {
            case 'streamWhiteListed':
                echo 'Suhosin is enabled and ' . $pug->getOption('stream') . ' is not in suhosin.executor.include.whitelist, please add it to your php.ini file.<br />';
                break;
            case 'cacheFolderExists':
                echo 'The cache folder does not exists, please enter in a command line : <code>mkdir -p ' . $pug->getOption('cache') . '</code>.<br />';
                break;
            case 'cacheFolderIsWritable':
                echo 'The cache folder is not writable, please enter in a command line : <code>chmod -R +w ' . $pug->getOption('cache') . '</code>.<br />';
                break;
            default:
                echo $requirement . ' is false.<br />';
        }
    }
    exit(1);
}