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

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

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

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

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

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

class IndexController extends Phalcon\Mvc\Controller
{
    public function index()
    {

        //Add some local CSS resources
        $this->assets
            ->addCss('css/style.css')
            ->addCss('css/index.css');

        //and some local javascript resources
        $this->assets
            ->addJs('js/jquery.js')
            ->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>

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

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

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

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)
        ->addCss('css/style.css', true);
}

Наборы

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

//Javascripts in the header
$this->assets
    ->collection('header')
    ->addJs('js/jquery.js')
    ->addJs('js/bootstrap.min.js');

//Javascripts in the footer
$this->assets
    ->collection('footer')
    ->addJs('js/jquery.js')
    ->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-префиксы, что позволяет легко переключаться между серверами в любой момент:

$scripts = $this->assets->collection('footer');

if ($config->environment == 'development') {
    $scripts->setPrefix('/');
} else {
    $scripts->setPrefix('http:://cdn.example.com/');
}

$scripts->addJs('js/jquery.js')
        ->addJs('js/bootstrap.min.js');

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

$scripts = $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 для минификации CSS-файлов:

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

$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', true, 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 из удалённого источника для дальнейшей фильтрации. Рекомендуется преобразовать внешние ресурсы в локальные, чтобы избежать накладных расходов на их получение.

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

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

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

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

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

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

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

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

// This a remote resource that does not need filtering
$js->join(true);

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

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

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

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

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($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(array(
     'java-bin' => '/usr/local/bin/java',
     'yui' => '/some/path/yuicompressor-x.y.z.jar',
     'extra-options' => '--charset utf8'
)));

Настройка вывода

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

foreach ($this->assets->collection('js') as $resource) {
    echo \Phalcon\Tag::javascriptInclude($resource->getPath());
}

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