Pipe 项目技术文档

1. 安装指南

首先，您需要获取 composer。如果尚未安装，可以通过以下命令进行安装：

wget http://getcomposer.org/composer.phar

然后，在项目的根目录下创建一个 composer.json 文件，并添加以下内容：

{
    "require": {
        "chh/pipe": "*"
    }
}

接下来，执行以下命令来安装 Pipe：

php composer.phar install

2. 项目的使用说明

环境配置

首先，需要创建一个 Pipe\Environment 实例。环境用于维护加载路径，检索资产以及将处理器/引擎映射到资产上。

<?php
use Pipe\Environment;

$env = new Environment;
$env->appendPath("assets");
$env->appendPath("vendor_assets");

资产可以通过访问环境实例的索引或调用 find 方法来检索。

<?php

$asset = $env["js/application.js"];
// 等同于：
$asset = $env->find("js/application.js");

要获取资产的已处理内容，请使用 getBody 方法。

<?php

echo $asset->getBody();

资产输出到文件

要将资产输出到文件，请使用 write 方法。该方法接受以下选项：

• dir (string): 文件的前缀目录。资产的哈希值会自动包含在生成的文件名中。
• include_digest (bool): 是否在文件名中包含 SHA1 哈希值。
• compress (bool): 是否使用 GZIP 压缩内容，并以 .gz 扩展名保存。

启用压缩

可以通过设置 js_compressor 和 css_compressor 配置键或在环境实例上调用 setJsCompressor 或 setCssCompressor 来启用压缩。

支持的 JavaScript 压缩器：

• uglify_js: 基于 NodeJS 的 Uglify JS 压缩器。通过 npm -g install uglify-js 安装。
• yuglify_js: 基于 Uglify JS 并行为类似于 YUI 压缩器。通过 npm -g install yuglify 安装。

支持的 CSS 压缩器：

• yuglify_css: 使用 Yuglify 压缩器的能力来压缩 CSS，依赖于 CSSmin。需要 yuglify NPM 包。

示例：

<?php

$env = new Environment;
$env->appendPath("assets/stylesheets");
$env->appendPath("assets/vendor/stylesheets");
$env->appendPath("assets/javascripts");
$env->appendPath("assets/vendor/javascripts");

$env->setJsCompressor('yuglify_js');
$env->setCssCompressor('yuglify_css');

// 压缩器是捆绑处理器。捆绑处理器仅对捆绑资产运行。
$asset = $env->find('application.js', ['bundled' => true]);

echo $asset->getBody();

3. 项目API使用文档

指令

每个 application/javascript 或 text/css 类型的文件都会被 DirectiveProcessor 处理。DirectiveProcessor 会解析文件开头的特殊注释，这些注释以等号 (=) 开头。

/* CSS
 *= require foo.css
 *= depend_on bar.css
 */

# CoffeeScript
#= require foo.coffee

// Javascript
//= require foo.js

每个指令的参数都会按照壳脚本 (Bourne Shell) 的规则进行分割。这意味着如果参数中包含空格，需要使用单引号或双引号进行引用。

require

用法：

require <path>

require 指令接受一个资产路径作为参数，处理这个资产，并将依赖的资产内容放在当前资产内容之前。

路径也可以以 ./ 开头，这会跳过路径解析的加载路径，直接在当前资产的同一路径下查找文件。

depend_on

用法：

depend_on <path>

定义 path 是当前资产的依赖，但不会处理任何内容。以这种方式定义的资产在计算最后修改时间时会被考虑，但内容不会被前置。

require_tree

用法：

require_tree <path>

要求指定路径下的所有文件。

例如，如果您有一个包含所有单独小部件和一个小部件基原型目录，可以通过 require_tree 小部件目录。这样每个开发人员都可以简单地将文件放入小部件目录中，而无需维护一个庞大的单独资产列表。

// index.js
//= require ./widget_base
//= require_tree ./widgets

引擎

引擎用于在资产被输出之前处理资产。每个引擎都映射到一个或多个文件扩展名（例如，CoffeeScript 到 .coffee）。每个资产可以由一个或多个引擎处理。使用哪个引擎以及它们的顺序由资产的文件扩展名决定。

例如，要将资产首先通过 PHP 引擎处理，然后通过 LESS 编译器处理，可以给资产加上 .less.php 后缀。

以下是默认提供的引擎及其映射到的文件扩展名列表：

引擎	扩展名	要求
CoffeeScript	.coffee	coffee — 通过 npm install -g coffee-script 安装
LESS	.less	lessc — 通过 npm install -g less 安装
PHP	.php, .phtml
Mustache	.mustache	添加 phly/mustache 包
Markdown	.markdown, .md	添加 dflydev/markdown 包
Twig	.twig	添加 twig/twig 包
TypeScript	.ts	tsc — 通过 npm install -g typescript 安装

在内部，Pipe 引擎是 meta-template 模板。关于构建自己的引擎的更多信息，请查看其 README。

要将引擎类添加到 Pipe，请使用环境的 registerEngine 方法，该方法接受引擎的类名作为第一个参数和扩展名数组作为第二个参数。

4. 项目安装方式

如前所述，使用 composer 进行安装：

php composer.phar install

确保在 composer.json 文件中添加了 Pipe 的依赖。

{
    "require": {
        "chh/pipe": "*"
    }
}

此外，如果需要动态服务资产，还需要安装 symfony/http-foundation：

{
    "require": {
        "chh/pipe": "*@dev",
        "symfony/http-foundation": "*"
    }
}