Управление активами

Phalcon\Assets — это компонент, который позволяет управлять статическими ресурсами, такими как таблицы стилей CSS или библиотеки JavaScript, в веб-приложении.

Phalcon\Assets\Manager доступен в контейнере сервисов, поэтому вы можете добавлять ресурсы из любой части приложения, где доступен контейнер.

Добавление ресурсов

Управление активами поддерживает два встроенных типа ресурсов: CSS и JavaScript. Вы можете создавать другие ресурсы при необходимости. Менеджер активов внутренне хранит два стандартных набора ресурсов — один для JavaScript и другой для CSS.

Вы можете легко добавить ресурсы в эти наборы следующим образом:

use Phalcon\Mvc\Controller;

class IndexController extends Controller
{
    public function index()
    {
        // Add some local CSS resources
        $this->assets->addCss("css/style.css");
        $this->assets->addCss("css/index.css");

        // And some local JavaScript resources
        $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 в конце HTML, а не в <head>.

Локальные/удаленные ресурсы

Локальные ресурсы предоставляются тем же приложением и расположены в корневой директории приложения. URL-адреса локальных ресурсов генерируются службой «url», обычно Phalcon\Mvc\Url.

Удаленные ресурсы — это такие ресурсы, как общие библиотеки, такие как jQuery, Bootstrap и т. д., которые предоставляются CDN.

Второй параметр addCss() и addJs() указывает, является ли ресурс локальным или нет (true — локальный, false — удаленный). По умолчанию менеджер активов предполагает, что ресурс является локальным:

public function indexAction()
{
    // Add some local CSS resources
    $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");
}

Наборы

Наборы группируют ресурсы одного типа. Менеджер активов неявно создает два набора: css и js. Вы можете создавать дополнительные наборы для группировки определенных ресурсов, чтобы упростить их размещение в представлениях:

// Javascripts in the header
$headerCollection = $this->assets->collection("header");

$headerCollection->addJs("js/jquery.js");
$headerCollection->addJs("js/bootstrap.min.js");

// Javascripts in the footer
$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

Наборы могут иметь префиксы URL, что позволяет легко переключаться между серверами в любой момент:

$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");

Также доступен цепочечный синтаксис:

$headerCollection = $assets
    ->collection("header")
    ->setPrefix("http://cdn.example.com/")
    ->setLocal(false)
    ->addJs("js/jquery.js")
    ->addJs("js/bootstrap.min.js");

Минификация/Фильтрация

Phalcon\Assets предоставляет встроенную минификацию ресурсов JavaScript и CSS. Вы можете создать набор ресурсов, указав менеджеру активов, какие из них необходимо отфильтровать, а какие оставить как есть. В дополнение к вышесказанному, Jsmin от Douglas Crockford входит в состав расширения, обеспечивая минификацию файлов JavaScript для максимальной производительности. В случае CSS также доступна минификация CSSMin от Ryan Day:

Следующий пример демонстрирует, как минифицировать набор ресурсов:

$manager

    // These JavaScripts are located in the page's bottom
    ->collection("jsFooter")

    // The name of the final output
    ->setTargetPath("final.js")

    // The script tag is generated with this URI
    ->setTargetUri("production/final.js")

    // This is a remote resource that does not need filtering
    ->addJs("code.jquery.com/jquery-1.10.0.min.js", false, false)

    // These are local resources that must be filtered
    ->addJs("common-functions.js")
    ->addJs("page-functions.js")

    // Join all the resources in a single file
    ->join(true)

    // Use the built-in Jsmin filter
    ->addFilter(
        new Phalcon\Assets\Filters\Jsmin()
    )

    // Use a custom filter
    ->addFilter(
        new MyApp\Assets\Filters\LicenseStamper()
    );

Набор может содержать ресурсы JavaScript или CSS, но не оба типа одновременно. Некоторые ресурсы могут быть удалёнными, то есть они получены по HTTP из удалённого источника для дальнейшей фильтрации. Рекомендуется преобразовать внешние ресурсы в локальные для повышения производительности.

Как показано выше, метод addJs() используется для добавления ресурсов в набор, второй параметр указывает, является ли ресурс внешним, а третий — необходимо ли отфильтровать ресурс или оставить его как есть:

// These Javascripts are located in the page's bottom
$jsFooterCollection = $manager->collection("jsFooter");

// This a remote resource that does not need filtering
$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");

Фильтры регистрируются в наборе, допускается несколько фильтров, содержимое ресурсов фильтруется в том же порядке, в котором были зарегистрированы фильтры:

// Use the built-in Jsmin filter
$jsFooterCollection->addFilter(
    new Phalcon\Assets\Filters\Jsmin()
);

// Use a custom filter
$jsFooterCollection->addFilter(
    new MyApp\Assets\Filters\LicenseStamper()
);

Обратите внимание, что как встроенные, так и пользовательские фильтры могут быть прозрачно применены к наборам. Последний шаг — определить, необходимо ли объединить все ресурсы набора в один файл или подавать каждый из них индивидуально. Чтобы указать набору, что все ресурсы должны быть объединены, можно использовать метод join().

Если ресурсы будут объединены, необходимо также определить, какой файл будет использоваться для хранения ресурсов и какой URI будет использоваться для его отображения. Эти настройки задаются с помощью setTargetPath() и setTargetUri():

$jsFooterCollection->join(true);

// The name of the final file path
$jsFooterCollection->setTargetPath("public/production/final.js");

// The script HTML tag is generated with this URI
$jsFooterCollection->setTargetUri("production/final.js");

Встроенные фильтры

Phalcon предоставляет 2 встроенных фильтра для минификации JavaScript и CSS, их C-подсистема обеспечивает минимальную нагрузку для выполнения этой задачи:

Фильтр	Описание
Phalcon\Assets\Filters\Jsmin	Минифицирует JavaScript, удаляя ненужные символы, которые игнорируются интерпретаторами/компиляторами JavaScript
Phalcon\Assets\Filters\Cssmin	Минифицирует CSS, удаляя ненужные символы, которые уже игнорируются браузерами

Пользовательские фильтры

В дополнение к встроенным фильтрам вы можете создавать свои собственные фильтры. Они могут использовать существующие и более продвинутые инструменты, такие как YUI, Sass, Closure и т. д.:

use Phalcon\Assets\FilterInterface;

/**
 * Filters CSS content using YUI
 *
 * @param string $contents
 * @return string
 */
class CssYUICompressor implements FilterInterface
{
    protected $_options;

    /**
     * CssYUICompressor constructor
     *
     * @param array $options
     */
    public function __construct(array $options)
    {
        $this->_options = $options;
    }

    /**
     * Do the filtering
     *
     * @param string $contents
     *
     * @return string
     */
    public function filter($contents)
    {
        // Write the string contents into a temporal file
        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 the contents of file
        return file_get_contents("temp/my-temp-file-2.css");
    }
}

Использование:

// Get some CSS collection
$css = $this->assets->get("head");

// Add/Enable the YUI compressor filter in the collection
$css->addFilter(
    new CssYUICompressor(
        [
            "java-bin"      => "/usr/local/bin/java",
            "yui"           => "/some/path/yuicompressor-x.y.z.jar",
            "extra-options" => "--charset utf8",
        ]
    )
);

В предыдущем примере мы использовали пользовательский фильтр с именем LicenseStamper:

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;
    }
}

Настраиваемый вывод

Методы outputJs() и outputCss() доступны для генерации необходимого кода HTML в соответствии с каждым типом ресурсов. Вы можете переопределить этот метод или вручную выводить ресурсы следующим образом:

use Phalcon\Tag;

$jsCollection = $this->assets->collection("js");

foreach ($jsCollection as $resource) {
    echo Tag::javascriptInclude(
        $resource->getPath()
    );
}

© 2011–2017 Phalcon Framework Team
Licensed under the Creative Commons Attribution License 3.0.
https://docs.phalconphp.com/en/latest/reference/assets.html