資源文件管理 · Phalcon3中文文檔

# 資源文件管理（Assets Management） `Phalcon\Assets`是一個讓開發者管理靜態資源的組件，如管理CSS，JavaScript等。 [Phalcon\\Assets\\Manager](http://docs.iphalcon.cn/api/Phalcon_Assets_Manager.html)存在于DI容器中，所以我們可以在服務容器存在的任何地方使用它來添加/管理資源。 ## 添加資源（Adding Resources） Assets支持兩個內置的資源管理器：css和javascripts.我們可以根據需要創建其它的資源。資源管理器內部保存了兩類資源集合一為 JavaScript另一為CSS. 我們可以非常簡單的向這兩個集合里添加資源，如下： ~~~ <?php use Phalcon\Mvc\Controller; class IndexController extends Controller { public function index() { // 添加本地CSS資源 $this->assets->addCss("css/style.css"); $this->assets->addCss("css/index.css"); // 添加本地JavaScript資源 $this->assets->addJs("js/jquery.js"); $this->assets->addJs("js/bootstrap.min.js"); } } ~~~ 然后我們可以在視圖中輸出資源： ~~~ <html> <head> <title>Some amazing website</title> <?php $this->assets->outputCss(); ?> </head> <body>  <?php $this->assets->outputJs(); ?> </body> <html> ~~~ Volt語法： ~~~ <html> <head> <title>Some amazing website</title> {{ assets.outputCss() }} </head> <body>  {{ assets.outputJs() }} </body> <html> ~~~ 為了提升頁面加載性能，建議在頁面底部（標簽前）加載javascript，而不是在`<head>`處加載。 ## 本地與遠程資源（Local/Remote resources）本地資源是同一應用中的資源，這些資源存在于應用的根目錄中。[Phalcon\\Mvc\\Url](http://docs.iphalcon.cn/api/Phalcon_Mvc_Url.html)用來生成本地的url. 遠程資源即是一種存在于CDN或其它遠程服務器上的資源，比如常用的jQuery, Bootstrap等資源。 `addCss()`和`addJs()`方法的第二個參數的作用是申明當前資源是本地資源還是遠程資源(`true`為本地資源,`false`為遠程資源)。不傳此參數時，默認為本地資源: ~~~ <?php public function indexAction() { // 添加遠程及本地資源 $this->assets->addCss("//netdna.bootstrapcdn.com/twitter-bootstrap/2.3.1/css/bootstrap-combined.min.css", false); $this->assets->addCss("css/style.css", true); $this->assets->addCss("css/extra.css"); } ~~~ ## 集合（Collections）集合即是把一同類的資源放在一些，資源管理器隱含的創建了兩個集合：css和js. 當然我們可以創建其它的集合以歸類其它的資源，這樣我們可以很容易的在視圖里顯示： ~~~ <?php // HTML 頭部的js資源 $headerCollection = $this->assets->collection("header"); $headerCollection->addJs("js/jquery.js"); $headerCollection->addJs("js/bootstrap.min.js"); // HTML尾部的js資源 $footerCollection = $this->assets->collection("footer"); $footerCollection->addJs("js/jquery.js"); $footerCollection->addJs("js/bootstrap.min.js"); ~~~ 然后在視圖中如下使用： ~~~ <html> <head> <title>Some amazing website</title> <?php $this->assets->outputJs("header"); ?> </head> <body>  <?php $this->assets->outputJs("footer"); ?> </body> <html> ~~~ Volt語法： ~~~ <html> <head> <title>Some amazing website</title> {{ assets.outputCss("header") }} </head> <body>  {{ assets.outputJs("footer") }} </body> <html> ~~~ ## 前綴（URL Prefixes）集合可以添加前綴，這可以實現非常簡單的更換服務器： ~~~ <?php $footerCollection = $this->assets->collection("footer"); if ($config->environment === "development") { $footerCollection->setPrefix("/"); } else { $footerCollection->setPrefix("http:://cdn.example.com/"); } $footerCollection->addJs("js/jquery.js"); $footerCollection->addJs("js/bootstrap.min.js"); ~~~ 我們也可以使用鏈式語法，如下： ~~~ <?php $headerCollection = $assets ->collection("header") ->setPrefix("http://cdn.example.com/") ->setLocal(false) ->addJs("js/jquery.js") ->addJs("js/bootstrap.min.js"); ~~~ ## 壓縮與過濾（Minification/Filtering） `Phalcon\Assets`提供了內置的js及css壓縮工具。開發者可以設定資源管理器以確定對哪些資源進行壓縮哪些資源不進行壓縮。除了上面這些之外，我們還可以使用Douglas Crockford書寫的Jsmin壓縮工具，及Ryan Day提供的CSSMin來對js及css文件進行壓縮. 下面的例子中展示了如何使用集合對資源文件進行壓縮： ~~~ <?php $manager // 這些javascript資源位于html文件的底部 ->collection("jsFooter") // 最終輸出名 ->setTargetPath("final.js") // 使用此uri顯示資源 ->setTargetUri("production/final.js") // 添加遠程資源但不壓縮 ->addJs("code.jquery.com/jquery-1.10.0.min.js", false, false) // 這些資源必須要壓縮 ->addJs("common-functions.js") ->addJs("page-functions.js") // 把這些資源放入一個文件內 ->join(true) // 使用內置的JsMin過濾器 ->addFilter( new Phalcon\Assets\Filters\Jsmin() ) // 使用自定義過濾器 ->addFilter( new MyApp\Assets\Filters\LicenseStamper() ); ~~~ 開始部分我們通過資源管理器取得了一個命名的集合，集合中可以包含JavaScript或CSS資源但不能同時包含兩個。一些資源可能位于遠程的服務器上，這些資源我們可以通過http取得。為了提高性能建議把遠程的資源取到本地來，以減少加載遠程資源的開銷。如上示例，`addJs()`方法用于將資源添加到集合中，第二個參數表示當前資源是否為外部資源，第三個參數表示當前資源是否需要進行壓縮: ~~~ <?php // 這些Javscript文件放在頁面的底端 $jsFooterCollection = $manager->collection("jsFooter"); // 添加遠程資源但不壓縮 $jsFooterCollection->addJs("code.jquery.com/jquery-1.10.0.min.js", false, false); // These are local resources that must be filtered // 添加本地資源并壓縮 $jsFooterCollection->addJs("common-functions.js"); $jsFooterCollection->addJs("page-functions.js"); ~~~ 過濾器被注冊到集合內，我們可以注冊多個過濾器，資源內容被過濾的順序和過濾器注冊的順序是一樣的。 ~~~ <?php // 使用內置的Jsmin過濾器 $jsFooterCollection->addFilter( new Phalcon\Assets\Filters\Jsmin() ); // 使用自定義的過濾器 $jsFooterCollection->addFilter( new MyApp\Assets\Filters\LicenseStamper() ); ~~~ 注意：不管是內置的還是自定義的過濾器對集合來說他們都是透明的。最后一步用來確定所有的資源文件寫到同一個文件中還是分開保存。如果要讓集合中所有的資源文件合成一個文件只需要使用:code:[`](http://docs.iphalcon.cn/reference/assets.html#id1)join()`函數. 如果資源被寫入同一文件，則我們需要定義使用哪一個文件來保存要寫入的資源數據，及使用一個ur來展示資源。這兩個設置可以使用`setTargetPath()`和`setTargetUri()`兩個函數來配置: ~~~ <?php $jsFooterCollection->join(true); // 設置最終輸出文件 $jsFooterCollection->setTargetPath("public/production/final.js"); // 使用此uri引用js $jsFooterCollection->setTargetUri("production/final.js"); ~~~ ### 內置過濾器（Built-In Filters） Phalcon內置了兩個過濾器以分別實現對JavaScript及CSS的壓縮，由于二者是使用c實現的故極大的減少了性能上的開銷： | 過濾器 | 說明 | | --- | --- | | [Phalcon\\Assets\\Filters\\Jsmin](http://docs.iphalcon.cn/api/Phalcon_Assets_Filters_Jsmin.html) | 壓縮JavaScript文件即去除掉JavaScript解釋器/編譯器忽略的一些字符 | | [Phalcon\\Assets\\Filters\\Cssmin](http://docs.iphalcon.cn/api/Phalcon_Assets_Filters_Cssmin.html) | 壓縮CSS文件即去除掉瀏覽器在渲染CSS時不需要的一些字符 | ### 自定義過濾器（Custom Filters）除了使用Phalcon內置的過濾器外，開發者還可以創建自己的過濾器。這樣我們就可以使用[YUI](http://yui.github.io/yuicompressor/),[Sass](http://sass-lang.com/),[Closure](https://developers.google.com/closure/compiler/?hl=fr), 等。 ~~~ <?php use Phalcon\Assets\FilterInterface; /** * 使用YUI過濾CSS內容 * * @param string $contents * @return string */ class CssYUICompressor implements FilterInterface { protected $_options; /** * CssYUICompressor 構造函數 * * @param array $options */ public function __construct(array $options) { $this->_options = $options; } /** * 執行過濾 * * @param string $contents * * @return string */ public function filter($contents) { // 保存字符呂內容到臨時文件中 file_put_contents("temp/my-temp-1.css", $contents); system( $this->_options["java-bin"] . " -jar " . $this->_options["yui"] . " --type css " . "temp/my-temp-file-1.css " . $this->_options["extra-options"] . " -o temp/my-temp-file-2.css" ); // 返回文件內容 return file_get_contents("temp/my-temp-file-2.css"); } } ~~~ 用法: ~~~ <?php // 取CSS集合 $css = $this->assets->get("head"); // 添加/啟用YUI壓縮器 $css->addFilter( new CssYUICompressor( [ "java-bin" => "/usr/local/bin/java", "yui" => "/some/path/yuicompressor-x.y.z.jar", "extra-options" => "--charset utf8", ] ) ); ~~~ In a previous example, we used a custom filter called`LicenseStamper`: ~~~ <?php use Phalcon\Assets\FilterInterface; /** * Adds a license message to the top of the file * * @param string $contents * * @return string */ class LicenseStamper implements FilterInterface { /** * Do the filtering * * @param string $contents * @return string */ public function filter($contents) { $license = "/* (c) 2015 Your Name Here */"; return $license . PHP_EOL . PHP_EOL . $contents; } } ~~~ ## 自定義輸出（Custom Output） `outputJs()`及`outputCss()`方法可以依據不同的資源類來創建需要的HTML代碼。我們可以重寫這個方法或是手動的輸出這些資源方法如下： ~~~ <?php use Phalcon\Tag; $jsCollection = $this->assets->collection("js"); foreach ($jsCollection as $resource) { echo Tag::javascriptInclude( $resource->getPath() ); } ~~~