Documentação do Symfony - versão 3.1
Renderizada do repositório symfony-docs-pt-BR no Github

Como usar o Assetic para o Gerenciamento de Assets

Instalando e Ativando o Assetic

A partir do Symfony 2.8, o Assetic não é mais incluído por padrão na Edição Standard do Symfony. Antes de utilizar qualquer de seus recursos, instale o AsseticBundle executando o seguinte comando de console no seu projeto:

1
$ composer require symfony/assetic-bundle

Então, ative o bundle no arquivo AppKernel.php da sua aplicação Symfony:

// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    // ...

    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Symfony\Bundle\AsseticBundle\AsseticBundle(),
        );

        // ...
    }
}

Finalmente, adicione a seguinte configuração mínima para ativar o suporte ao Assetic na sua aplicação:

  • YAML
    1
2
3
4
5
6
7
8
    # app/config/config.yml
assetic:
    debug:          '%kernel.debug%'
    use_controller: '%kernel.debug%'
    filters:
        cssrewrite: ~

# ...
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
    <!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:assetic="http://symfony.com/schema/dic/assetic"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/assetic
        http://symfony.com/schema/dic/assetic/assetic-1.0.xsd">

    <assetic:config debug="%kernel.debug%" use-controller="%kernel.debug%">
        <assetic:filters cssrewrite="null" />
    </assetic:config>

    <!-- ... -->
</container>
  • PHP
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    // app/config/config.php
$container->loadFromExtension('assetic', array(
    'debug' => '%kernel.debug%',
    'use_controller' => '%kernel.debug%',
    'filters' => array(
        'cssrewrite' => null,
    ),
    // ...
));

// ...

Introducing Assetic

O Assetic combina duas idéias principais: assets e filtros. filters. Os assets são arquivos CSS, JavaScript e arquivos de imagem. Os filtros podem ser aplicados a esses arquivos antes deles serem servidos ao navegador. Isso permite uma separação entre os arquivos asset armazenados na aplicação e os arquivos que são efetivamente apresentados ao usuário.

Sem o Assetic, você somente serve os arquivos que são armazenados diretamente na aplicação:

  • Twig
    1
    <script src="{{ asset('js/script.js') }}" type="text/javascript" />
  • PHP
    1
    <script src="<?php echo $view['assets']->getUrl('js/script.js') ?>" type="text/javascript" />

Mas com o Assetic, você pode manipular esses assets da forma que desejar (ou carregá-los de qualquer lugar) antes de serví-los. Isso significa que você pode:

  • Minificar e combinar todos os seus arquivos CSS e JS
  • Executar todos (ou apenas alguns) dos seus arquivos CSS ou JS através de algum tipo de compilador, como o LESS, SASS ou CoffeeScript
  • Executar otimizações em suas imagens

Assets

O uso do Assetic oferece muitas vantagens sobre servir diretamente os arquivos. Os arquivos não precisam ser armazenados onde eles são servidos e podem ser buscados a partir de várias fontes, como, por exemplo, a partir de um bundle.

Você pode usar o Assetic para processar stylesheets CSS, arquivos JavaScript e imagens. A filosofia para adicionar é basicamente a mesma, mas com uma sintaxe ligeiramente diferente.

Incluindo Arquivos JavaScript

Para incluir arquivos JavaScript, use a tag javascripts em qualquer template:

  • Twig
    1
2
3
    {% javascripts '@AppBundle/Resources/public/js/*' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}
  • PHP
    1
2
3
4
5
    <?php foreach ($view['assetic']->javascripts(
    array('@AppBundle/Resources/public/js/*')
) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach ?>

Note

If your application templates use the default block names from the Symfony Standard Edition, the javascripts tag will most commonly live in the javascripts block:

1
2
3
4
5
6
7
{# ... #}
{% block javascripts %}
    {% javascripts '@AppBundle/Resources/public/js/*' %}
        <script src="{{ asset_url }}"></script>
    {% endjavascripts %}
{% endblock %}
{# ... #}

Tip

You can also include CSS stylesheets: see assetic-including-css.

Tip

Para buscar folhas de estilo CSS, você pode usar as mesmas metodologias vistas aqui, exceto com a tag stylesheets :

  • Twig
    1
2
3
    {% stylesheets '@AcmeFooBundle/Resources/public/css/*' %}
    <link rel="stylesheet" href="{{ asset_url }}" />
{% endstylesheets %}
  • PHP
    1
2
3
4
5
    <?php foreach ($view['assetic']->stylesheets(
                                     array('@AcmeFooBundle/Resources/public/css/*')
                                 ) as $url): ?>
    <link rel="stylesheet" href="<?php echo $view->escape($url) ?>" />
<?php endforeach; ?>

Neste exemplo, todos os arquivos no diretório Resources/public/js/ do AcmeFooBundle serão carregados e servidos em um local diferente. A tag atual renderizada pode parecer simplesmente com:

1
<script src="/app_dev.php/js/abcd123.js"></script>

Note

Este é um ponto-chave: uma vez que você deixar o Assetic lidar com seus assets, os arquivos são servidos a partir de um local diferente. Isto pode causar problemas com os arquivos CSS que referenciam imagens pelo seu caminho relativo. No entanto, isso pode ser corrigido usando o filtro cssrewrite, que atualiza os caminhos nos arquivos CSS para refletir a sua nova localização.

Combinando Assets

Você também pode combinar vários arquivos em um único. Isto ajuda a reduzir o número de solicitações HTTP, o que é ótimo para o desempenho front-end. Também permite que você mantenha os arquivos mais facilmente, dividindo-os em partes gerenciáveis. Isso pode ajudar com a possibilidade de reutilização, uma vez que você pode facilmente dividir os arquivos específicos do projeto daqueles que podem ser usados ​​em outras aplicações, mas ainda serví-los como um único arquivo:

  • Twig
    1
2
3
4
5
6
    {% javascripts
    '@AcmeFooBundle/Resources/public/js/*'
    '@AcmeBarBundle/Resources/public/js/form.js'
    '@AcmeBarBundle/Resources/public/js/calendar.js' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}
  • PHP
    1
2
3
4
5
6
    <?php foreach ($view['assetic']->javascripts(
    array('@AcmeFooBundle/Resources/public/js/*',
          '@AcmeBarBundle/Resources/public/js/form.js',
          '@AcmeBarBundle/Resources/public/js/calendar.js')) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>

No ambiente dev, cada arquivo ainda é servido individualmente, de modo que você pode depurar problemas mais facilmente. No entanto, no ambiente prod, serão processados como uma única tag script.

Tip

Se você é novo no Assetic e tentar usar a sua aplicação no ambiente prod (utilizando o controlador app.php), você provavelmente verá que todos os seus CSS e JS estão corrompidos. Não se preocupe! Isso é de propósito. Para detalhes sobre a utilização do Assetic no ambiente prod, consulte Dump dos arquivos de asset.

E a combinação de arquivos não se aplica apenas para seus arquivos. Você também pode usar o Assetic para combinar assets de terceiros, tais como jQuery, como seu próprio em um único arquivo:

  • Twig
    1
2
3
4
5
    {% javascripts
    '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js'
    '@AcmeFooBundle/Resources/public/js/*' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}
  • PHP
    1
2
3
4
5
    <?php foreach ($view['assetic']->javascripts(
    array('@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js',
          '@AcmeFooBundle/Resources/public/js/*')) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>

Filtros

Uma vez que são gerenciados pelo Assetic, você pode aplicar filtros em seus assets antes deles serem servidos. Isso inclui filtros que comprimem a saída de seus assets para tamanhos de arquivos menores (e melhor otimização do front-end). Outros filtros podem compilar os arquivos JavaScript a partir de arquivos CoffeeScript e processar SASS em CSS. Na verdade, o Assetic tem uma longa lista de filtros disponíveis.

Muitos dos filtros não fazem o trabalho diretamente, mas usam bibliotecas existentes de terceiros para fazer o trabalho pesado. Isto significa que muitas vezes você vai precisar instalar uma biblioteca de terceiro para usar um filtro. A grande vantagem de usar o Assetic para chamar estas bibliotecas (em oposição a usá-las diretamente) é que, em vez de ter que executá-las manualmente depois de trabalhar nos arquivos, o Assetic irá cuidar disto para você e remover completamente esta etapa do seu processo de desenvolvimento e implantação.

Para usar um filtro, primeiro você precisa especificá-lo na configuração do Assetic. Adicionar um filtro aqui não significa que ele está sendo usado - apenas significa que está disponível para uso (vamos usar o filtro abaixo).

Por exemplo, para usar o JavaScript YUI Compressor, a configuração seguinte deve ser acrescentada:

  • YAML
    1
2
3
4
5
    # app/config/config.yml
assetic:
    filters:
        yui_js:
            jar: "%kernel.root_dir%/Resources/java/yuicompressor.jar"
  • XML
    1
2
3
4
5
6
    <!-- app/config/config.xml -->
<assetic:config>
    <assetic:filter
        name="yui_js"
        jar="%kernel.root_dir%/Resources/java/yuicompressor.jar" />
</assetic:config>
  • PHP
    1
2
3
4
5
6
7
8
    // app/config/config.php
$container->loadFromExtension('assetic', array(
    'filters' => array(
        'yui_js' => array(
            'jar' => '%kernel.root_dir%/Resources/java/yuicompressor.jar',
        ),
    ),
));

Agora, para efetivamente usar o filtro em um grupo de arquivos JavaScript, adicione-o em seu template:

  • Twig
    1
2
3
    {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='yui_js' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}
  • PHP
    1
2
3
4
5
    <?php foreach ($view['assetic']->javascripts(
    array('@AcmeFooBundle/Resources/public/js/*'),
    array('yui_js')) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>

Um guia mais detalhado sobre a configuração e uso dos filtros Assetic, bem como detalhes do modo de depuração do Assetic pode ser encontrado em /cookbook/assetic/yuicompressor.

Controlando a URL usada

Se desejar, você pode controlar as URLs que o Assetic produz. Isto é feito a partir do template e é relativo à raiz do documento público:

  • Twig
    1
2
3
    {% javascripts '@AcmeFooBundle/Resources/public/js/*' output='js/compiled/main.js' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}
  • PHP
    1
2
3
4
5
6
7
    <?php foreach ($view['assetic']->javascripts(
    array('@AcmeFooBundle/Resources/public/js/*'),
    array(),
    array('output' => 'js/compiled/main.js')
) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>

Note

O Symfony também contém um método de busting de cache, onde a URL final gerada pelo Assetic contém um parâmetro de query, que pode ser incrementado através de configuração em cada implantação. Para mais informações, consulte a opção de configuração ref-framework-assets-version.

Dump dos arquivos de asset

No ambiente dev, o Assetic gera caminhos para os arquivos CSS e JavaScript que não existem fisicamente em seu computador. Mas, eles renderizam mesmo assim porque um controlador interno do Symfony abre os arquivos e serve de volta o conteúdo (após a execução de quaisquer filtros).

Este tipo de publicação dinâmica dos assets processados ​​é ótima porque significa que você pode ver imediatamente o novo estado de quaisquer arquivos de assets que foram alterados. Também é ruim, porque pode ser muito lento. Se você estiver usando uma série de filtros, pode ser francamente frustrante.

Felizmente, o Assetic fornece uma forma de fazer o dump de seus assets para arquivos reais, em vez de ser gerado dinamicamente.

Dump dos arquivos asset no ambiente prod

No ambiente prod, seus JS e CSS são representados por uma única tag cada. Em outras palavras, em vez de ver cada arquivo JavaScript que você está incluindo no seu código fonte, é provável que você só veja algo semelhante a:

1
<script src="/app_dev.php/js/abcd123.js"></script>

Além disso, esse arquivo não existe realmente, nem é renderizado de forma dinâmica pelo Symfony (pois os arquivos de asset estão no ambiente dev). Isto é de propósito - deixar o Symfony gerar esses arquivos dinamicamente em um ambiente de produção é muito lento.

Em vez disso, cada vez que você usar a sua aplicação no ambiente ``prod `` (e, portanto, cada vez que você implantar), você deve executar o seguinte comando:

1
$ php app/console assetic:dump --env=prod --no-debug

Isso vai gerar fisicamente e escrever cada arquivo que você precisa (por exemplo, /js/abcd123.js). Se você atualizar qualquer um de seus assets, é necessário executar o comando novamente para gerar o novo arquivo.

Dump dos arquivos de asset no ambiente dev

Por padrão, cada caminho de asset gerado no ambiente dev é gerenciado dinamicamente pelo Symfony. Isso não tem desvantagem (você pode ver as suas alterações imediatamente), com exceção de que os assets podem visivelmente carregar mais lentos. Se você sentir que seus assets estão carregando muito lentamente, siga este guia.

Primeiro, diga ao Symfony para parar de tentar processar estes arquivos dinamicamente. Faça a seguinte alteração em seu arquivo config_dev.yml:

  • YAML
    1
2
3
    # app/config/config_dev.yml
assetic:
    use_controller: false
  • XML
    1
2
    <!-- app/config/config_dev.xml -->
<assetic:config use-controller="false" />
  • PHP
    1
2
3
4
    // app/config/config_dev.php
$container->loadFromExtension('assetic', array(
    'use_controller' => false,
));

Em seguida, uma vez que o Symfony não está mais gerando esses assets para você, você vai precisar fazer o dump deles manualmente. Para isso, execute o seguinte:

1
$ php app/console assetic:dump

Esta fisicamente grava todos os arquivos ativos que você precisa para seu `` `` dev produção. A grande desvantagem é que você precisa executar este cada vez você atualizar um ativo. Felizmente, passando o `` - assistir opção ``, o comando automaticamente regenerar ativos * como eles mudam *:

1
$ php app/console assetic:dump --watch

Uma vez que executar este comando no ambiente dev pode gerar vários arquivos, geralmente é uma boa idéia apontar os seus arquivos assets gerados para algum diretório isolado (por exemplo, /js/compiled), para manter as coisas organizadas:

  • Twig
    1
2
3
    {% javascripts '@AcmeFooBundle/Resources/public/js/*' output='js/compiled/main.js' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}
  • PHP
    1
2
3
4
5
6
7
    <?php foreach ($view['assetic']->javascripts(
    array('@AcmeFooBundle/Resources/public/js/*'),
    array(),
    array('output' => 'js/compiled/main.js')
) as $url): ?>
    <script src="<?php echo $view->escape($url) ?>"></script>
<?php endforeach; ?>

© 2017 andreiabohner.org