前天幫同事改個十年前的網站 bug，頁面上一堆 include require 不禁讓人抱頭痛哭。看到 V2EX 上的討論說，寫 PHP 不用框架等同於耍流氓。Yii Framework 是我使用了 2 年多的 PHP 框架，器大活好，皮實耐操。 Yii2 還在 Beta 中，不過不影響拿來預研。

這回要說的是，如何給 Yii2 項目添加外部資源（external assets），以 FontAwesome 為例子。

Yii2 開始使用 composer 來做項目的依賴管理，這貨是類似於 NodeJS 裡面 npm 的東東，可以自動獲取 Github 上最新版本的第三方庫（比如 Bootstrap 啦，FontAwesome 啦之類的）。按官方教程裝好後，就可以開始初始化項目了。

一、初始化項目

通過 Composer 來初始化

php composer.phar create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic basic

然後開始碼代碼，Model Controller View 神馬的，此處按下不表。

二、安裝 FontAwesome

終於，你的項目發展到需要引用第三方庫了，我們仍然通過 Composer 來安裝。搜索 packagist.org 官方的包列表，我們找到了 FontAwesome 的配置。將 FortAwesome/Font-Awesome": "*" 添加到項目的 composer.json 配置文件里。

// ...
"require": {
    "php": ">=5.4.0",
    "hybridauth/hybridauth": "dev-master",
    "FortAwesome/Font-Awesome": "*", // <- 這裡
    "yiisoft/yii2": "*",
    "yiisoft/yii2-swiftmailer": "*",
    "yiisoft/yii2-bootstrap": "*",
    "yiisoft/yii2-debug": "*",
    "yiisoft/yii2-gii": "*"
},
// ...

然後運行

php composer.phar update

從 Github 上拉取 FontAwesome 的包到項目本地。

三、創建 FontAwesome 資源包（asset bundle）

為了使用這些庫，我們需要在項目的 /assets 目錄下創建一個 FontAwesomeAsset.php

namespace assets;
use yii\web\AssetBundle;
class FontAwesomeAsset extends AssetBundle
{
    // 下面這些資源文件並不在 web 目錄下，瀏覽器無法直接訪問。所以我們需要
    // 指定 sourcePath 屬性。注意 @vendor 這個 alias，表示 vender 目錄
    public $sourcePath = '@vendor/fortawesome/font-awesome';
    public $css = [
        'css/font-awesome.css',
    ];
}

四、註冊文件，引入資源

有兩種方法。第一種，當你想在某一個特定頁面引入這個資源包

// 這兩句直接寫在那一頁的 view 里
use assets\FontAwesomeAsset;
FontAwesomeAsset::register($this);

第二種，在你的網站全局引入，或者將其作為另一個資源的依賴引用。在項目的 asset/AppAsset.php 中加上它：

class AppAsset extends AssetBundle
{
    public $basePath = '@webroot';
    public $baseUrl = '@web';
    public $css = [
        'css/site.css',
    ];
    public $js = [
    ];
    public $depends = [
        'yii\web\YiiAsset',
        'yii\bootstrap\BootstrapAsset',
        // 在這裡加上我們的 FontAwesomeAsset 包類
        'assets\FontAwesomeAsset'
    ];
}

刷新頁面，看看是不是已經引入了對應的 css、js 資源。