diff --git a/assetic/_standard_edition_warning.inc b/assetic/_standard_edition_warning.inc deleted file mode 100644 index 7c8a17a..0000000 --- a/assetic/_standard_edition_warning.inc +++ /dev/null @@ -1,5 +0,0 @@ -.. caution:: - - A partir do Symfony 2.8, o Assetic já não está mais incluído por padrão na - Edição Standard do Symfony. Consulte :doc:`este artigo ` - para aprender a instalar e ativar o Assetic em sua aplicação Symfony. diff --git a/assetic/_standard_edition_warning.rst.inc b/assetic/_standard_edition_warning.rst.inc new file mode 100644 index 0000000..0784089 --- /dev/null +++ b/assetic/_standard_edition_warning.rst.inc @@ -0,0 +1,5 @@ +.. caution:: + + A partir do Symfony 2.8, o Assetic já não é mais incluído por padrão na + Edição Standard do Symfony. Consulte :doc:`este artigo ` + para aprender como instalar e ativar o Assetic em sua aplicação Symfony. diff --git a/assetic/asset_management.rst b/assetic/asset_management.rst deleted file mode 100644 index ce752b2..0000000 --- a/assetic/asset_management.rst +++ /dev/null @@ -1,497 +0,0 @@ -.. index:: - single: Assetic; Introdução - -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: - -.. code-block:: bash - - $ 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: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - debug: '%kernel.debug%' - use_controller: '%kernel.debug%' - filters: - cssrewrite: ~ - - # ... - - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php - - // 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: :ref:`assets ` e filtros. -:ref:`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: - -.. configuration-block:: - - .. code-block:: html+jinja - - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AppBundle/Resources/public/js/*') - ) as $url): ?> - - - -.. 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: - - .. code-block:: html+twig - - {# ... #} - {% block javascripts %} - {% javascripts '@AppBundle/Resources/public/js/*' %} - - {% endjavascripts %} - {% endblock %} - {# ... #} - -.. tip:: - - You can also include CSS stylesheets: see :ref:`assetic-including-css`. - - - - -.. tip:: - - Para buscar folhas de estilo CSS, você pode usar as mesmas metodologias vistas - aqui, exceto com a tag `stylesheets` : - - .. configuration-block:: - - .. code-block:: html+jinja - - {% stylesheets '@AcmeFooBundle/Resources/public/css/*' %} - - {% endstylesheets %} - - .. code-block:: html+php - - stylesheets( - array('@AcmeFooBundle/Resources/public/css/*') - ) as $url): ?> - - - -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: - -.. code-block:: html - - - -.. 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: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% javascripts - '@AcmeFooBundle/Resources/public/js/*' - '@AcmeBarBundle/Resources/public/js/form.js' - '@AcmeBarBundle/Resources/public/js/calendar.js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AcmeFooBundle/Resources/public/js/*', - '@AcmeBarBundle/Resources/public/js/form.js', - '@AcmeBarBundle/Resources/public/js/calendar.js')) as $url): ?> - - - -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 :ref:`cookbook-assetic-dumping`. - -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: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% javascripts - '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js' - '@AcmeFooBundle/Resources/public/js/*' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js', - '@AcmeFooBundle/Resources/public/js/*')) as $url): ?> - - - -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: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - yui_js: - jar: "%kernel.root_dir%/Resources/java/yuicompressor.jar" - - .. code-block:: xml - - - - - - - .. code-block:: php - - // 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: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='yui_js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AcmeFooBundle/Resources/public/js/*'), - array('yui_js')) as $url): ?> - - - -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 :doc:`/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: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% javascripts '@AcmeFooBundle/Resources/public/js/*' output='js/compiled/main.js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AcmeFooBundle/Resources/public/js/*'), - array(), - array('output' => 'js/compiled/main.js') - ) as $url): ?> - - - -.. 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:`ref-framework-assets-version`. - -.. _cookbook-assetic-dumping: - -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: - -.. code-block:: html - - - -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: - -.. code-block:: bash - - $ 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``: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config_dev.yml - assetic: - use_controller: false - - .. code-block:: xml - - - - - .. code-block:: php - - // 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: - -.. code-block:: bash - - $ 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 *: - -.. code-block:: bash - - $ 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: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% javascripts '@AcmeFooBundle/Resources/public/js/*' output='js/compiled/main.js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AcmeFooBundle/Resources/public/js/*'), - array(), - array('output' => 'js/compiled/main.js') - ) as $url): ?> - - diff --git a/assetic/index.rst b/assetic/index.rst deleted file mode 100644 index f91943b..0000000 --- a/assetic/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Assetic -======= - -.. toctree:: - :maxdepth: 2 - - asset_management - yuicompressor - jpeg_optimize - apply_to_option diff --git a/assetic/jpeg_optimize.rst b/assetic/jpeg_optimize.rst deleted file mode 100644 index d7bbf21..0000000 --- a/assetic/jpeg_optimize.rst +++ /dev/null @@ -1,254 +0,0 @@ -Como usar o Assetic para otimização de imagem com funções do Twig -================================================================= - -Dentre os seus vários filtros, o Assetic possui quatro que podem ser utilizados para a otimização -de imagens on-the-fly. Isso permite obter os benefícios de tamanhos menores dos arquivos -sem ter que usar um editor de imagens para processar cada imagem. Os resultados são armazenados -em cache e pode ser feito o dump para produção de modo que não há impacto no desempenho -para seus usuários finais. - -Usando o jpegoptim ------------------- - -`Jpegoptim`_ é um utilitário para otimizar arquivos JPEG. Para usá-lo com o Assetic, -adicione o seguinte na configuração do Assetic: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - - .. code-block:: xml - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - ), - ), - )); - -.. note:: - - Observe que, para usar o jpegoptim, você deve instalá-lo em seu - sistema. A opção ``bin`` aponta para a localização do binário compilado. - -Ele agora pode ser usado em um template: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% image '@AcmeFooBundle/Resources/public/images/example.jpg' - filter='jpegoptim' output='/images/example.jpg' - %} - Example - {% endimage %} - - .. code-block:: html+php - - images( - array('@AcmeFooBundle/Resources/public/images/example.jpg'), - array('jpegoptim')) as $url): ?> - Example - - -Removendo todos os dados EXIF -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Por padrão, a execução desse filtro remove apenas algumas das informações meta -armazenadas no arquivo. Os dados EXIF ​​e comentários não são removidos, mas você pode -removê-los usando a opção ``strip_all``: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - strip_all: true - - .. code-block:: xml - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - 'strip_all' => 'true', - ), - ), - )); - -Diminuindo a qualidade máxima -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Por padrão, o nível de qualidade do JPEG não é afetado. Você pode ganhar reduções -adicionais no tamanho dos arquivos ao ajustar a configuração de qualidade máxima -para um valor inferior ao nível atual das imagens. Isto irá, claro, custar a -qualidade de imagem: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - max: 70 - - .. code-block:: xml - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - 'max' => '70', - ), - ), - )); - -Sintaxe curta: Função Twig --------------------------- - -Se você estiver usando o Twig, é possível conseguir tudo isso com uma sintaxe -curta, ao habilitar e usar uma função especial do Twig. Comece adicionando -a seguinte configuração: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - twig: - functions: - jpegoptim: ~ - - .. code-block:: xml - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - ), - ), - 'twig' => array( - 'functions' => array('jpegoptim'), - ), - ), - )); - -O template Twig pode agora ser alterado para o seguinte: - -.. code-block:: html+jinja - - Example - -Você pode especificar o diretório de saída na configuração da seguinte forma: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - jpegoptim: - bin: path/to/jpegoptim - twig: - functions: - jpegoptim: { output: images/*.jpg } - - .. code-block:: xml - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'jpegoptim' => array( - 'bin' => 'path/to/jpegoptim', - ), - ), - 'twig' => array( - 'functions' => array( - 'jpegoptim' => array( - output => 'images/*.jpg' - ), - ), - ), - )); - -.. _`Jpegoptim`: http://www.kokkonen.net/tjko/projects.html diff --git a/assetic/yuicompressor.rst b/assetic/yuicompressor.rst deleted file mode 100644 index 6385341..0000000 --- a/assetic/yuicompressor.rst +++ /dev/null @@ -1,139 +0,0 @@ -Como Minificar JavaScripts e Folhas de Estilo com o YUI Compressor -================================================================== - -A Yahoo! oferece um excelente utilitário, chamado `YUI Compressor`_, para minificar -JavaScripts e folhas de estilo, assim, eles são carregados mais rapidamente. -Graças ao Assetic, você pode tirar proveito desta ferramenta de forma muito fácil. - -Baixe o JAR do YUI Compressor ------------------------------ - -O YUI Compressor é escrito em Java e distribuído como um JAR. `Faça o download do JAR`_ -no site da Yahoo! e salve-o em ``app/Resources/java/yuicompressor.jar``. - -Configure os Filtros do YUI ---------------------------- - -Agora você precisa configurar dois filtros Assetic em sua aplicação, um para -minificar os JavaScripts com o YUI Compressor e um para minificar as -folhas de estilo: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - assetic: - filters: - yui_css: - jar: "%kernel.root_dir%/Resources/java/yuicompressor.jar" - yui_js: - jar: "%kernel.root_dir%/Resources/java/yuicompressor.jar" - - .. code-block:: xml - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('assetic', array( - 'filters' => array( - 'yui_css' => array( - 'jar' => '%kernel.root_dir%/Resources/java/yuicompressor.jar', - ), - 'yui_js' => array( - 'jar' => '%kernel.root_dir%/Resources/java/yuicompressor.jar', - ), - ), - )); - -Você agora tem acesso a dois novos filtros Assetic em sua aplicação: -``yui_css`` e ``yui_js``. Eles utilizarão o YUI Compressor para minificar -as folhas de estilo e JavaScripts, respectivamente. - -Minifique os seus Assets ------------------------- - -Você agora tem o YUI Compressor configurado, mas nada vai acontecer até -aplicar um desses filtros para um asset. Uma vez que os seus assets fazem -parte da camada de visão, este trabalho é feito em seus templates: - -.. configuration-block:: - - .. code-block:: html+jinja - - {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='yui_js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AcmeFooBundle/Resources/public/js/*'), - array('yui_js')) as $url): ?> - - - -.. note:: - - O exemplo acima assume que você tem um bundle chamado ``AcmeFooBundle`` - e os seus arquivos JavaScript estão no diretório``Resources/public/js`` sob - o seu bundle. Entretante, isso não é importante - você pode incluir os seus arquivos - JavaScript, não importa onde eles estiverem. - -Com a adição do filtro ``yui_js`` para as tags asset acima, você deve agora ver -os JavaScripts minificados sendo carregados muito mais rápido. O mesmo processo -pode ser repetido para minificar as suas folhas de estilo. - -.. configuration-block:: - - .. code-block:: html+jinja - - {% stylesheets '@AcmeFooBundle/Resources/public/css/*' filter='yui_css' %} - - {% endstylesheets %} - - .. code-block:: html+php - - stylesheets( - array('@AcmeFooBundle/Resources/public/css/*'), - array('yui_css')) as $url): ?> - - - -Desative a minificação no modo de depuração -------------------------------------------- - -Os JavaScripts e as folhas de estilo minificados são muito difíceis de ler, e muito menos -depurar. Devido a isso, o Assetic permite desabilitar um certo filtro quando a sua -aplicação está no modo de depuração. Você pode fazer isso prefixando o nome do filtro -em seu template com um ponto de interrogação: ``?``. Isto diz ao Assetic para apenas -aplicar esse filtro quando o modo de depuração está desligado. - -.. configuration-block:: - - .. code-block:: html+jinja - - {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='?yui_js' %} - - {% endjavascripts %} - - .. code-block:: html+php - - javascripts( - array('@AcmeFooBundle/Resources/public/js/*'), - array('?yui_js')) as $url): ?> - - - -.. _`YUI Compressor`: http://developer.yahoo.com/yui/compressor/ -.. _`Faça o download do JAR`: http://yuilibrary.com/downloads/#yuicompressor diff --git a/configuration.rst b/configuration.rst new file mode 100644 index 0000000..e6a4358 --- /dev/null +++ b/configuration.rst @@ -0,0 +1,430 @@ +.. index:: + single: Configuration + +Configuring Symfony (and Environments) +====================================== + +Every Symfony application consists of a collection of bundles that add useful tools +(:doc:`services `) to your project. Each bundle can be customized +via configuration files that live - by default - in the ``app/config`` directory. + +Configuration: config.yml +------------------------- + +The main configuration file is called ``config.yml``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: parameters.yml } + - { resource: security.yml } + - { resource: services.yml } + + framework: + secret: '%secret%' + router: { resource: '%kernel.project_dir%/app/config/routing.yml' } + # ... + + # Twig Configuration + twig: + debug: '%kernel.debug%' + strict_variables: '%kernel.debug%' + + # ... + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $this->import('parameters.yml'); + $this->import('security.yml'); + $this->import('services.yml'); + + $container->loadFromExtension('framework', array( + 'secret' => '%secret%', + 'router' => array( + 'resource' => '%kernel.project_dir%/app/config/routing.php', + ), + // ... + )); + + // Twig Configuration + $container->loadFromExtension('twig', array( + 'debug' => '%kernel.debug%', + 'strict_variables' => '%kernel.debug%', + )); + + // ... + +Most top-level keys - like ``framework`` and ``twig`` - are configuration for a +specific bundle (i.e. ``FrameworkBundle`` and ``TwigBundle``). + +.. sidebar:: Configuration Formats + + Throughout the documentation, all configuration examples will be shown in + three formats (YAML, XML and PHP). YAML is used by default, but you can + choose whatever you like best. There is no performance difference: + + * :doc:`/components/yaml/yaml_format`: Simple, clean and readable; + + * *XML*: More powerful than YAML at times & supports IDE autocompletion; + + * *PHP*: Very powerful but less readable than standard configuration formats. + +Configuration Reference & Dumping +--------------------------------- + +There are *two* ways to know *what* keys you can configure: + +#. Use the :doc:`Reference Section `; + +#. Use the ``config:dump-reference`` command. + +For example, if you want to configure something in Twig, you can see an example +dump of all available configuration options by running: + +.. code-block:: terminal + + $ php bin/console config:dump-reference twig + +.. index:: + single: Environments; Introduction + +.. _page-creation-environments: +.. _page-creation-prod-cache-clear: + +The imports Key: Loading other Configuration Files +-------------------------------------------------- + +Symfony's main configuration file is ``app/config/config.yml``. But, for organization, +it *also* loads other configuration files via its ``imports`` key: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: parameters.yml } + - { resource: security.yml } + - { resource: services.yml } + # ... + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $this->import('parameters.yml'); + $this->import('security.yml'); + $this->import('services.yml'); + + // ... + +The ``imports`` key works a lot like the PHP ``include()`` function: the contents of +``parameters.yml``, ``security.yml`` and ``services.yml`` are read and loaded. You +can also load XML files or PHP files. + +.. tip:: + + If your application uses unconventional file extensions (for example, your + YAML files have a ``.res`` extension) you can set the file type explicitly + with the ``type`` option: + + .. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + imports: + - { resource: parameters.res, type: yml } + # ... + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $this->import('parameters.res', 'yml'); + // ... + +.. _config-parameter-intro: + +The parameters Key: Parameters (Variables) +------------------------------------------ + +Another special key is called ``parameters``: it's used to define *variables* that +can be referenced in *any* other configuration file. For example, in ``config.yml``, +a ``locale`` parameter is defined and then referenced below under the ``framework`` +key: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + # ... + + parameters: + locale: en + + framework: + # ... + + # any string surrounded by two % is replaced by that parameter value + default_locale: "%locale%" + + # ... + + .. code-block:: xml + + + + + + + + en + + + + + + + + + + .. code-block:: php + + // app/config/config.php + // ... + + $container->setParameter('locale', 'en'); + + $container->loadFromExtension('framework', array( + 'default_locale' => '%locale%', + // ... + )); + + // ... + +You can define whatever parameter names you want under the ``parameters`` key of +any configuration file. To reference a parameter, surround its name with two percent +signs - e.g. ``%locale%``. + +.. seealso:: + + You can also set parameters dynamically, like from environment variables. + See :doc:`/configuration/external_parameters`. + +For more information about parameters - including how to reference them from inside +a controller - see :ref:`service-container-parameters`. + +.. _config-parameters-yml: + +The Special parameters.yml File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On the surface, ``parameters.yml`` is just like any other configuration file: it +is imported by ``config.yml`` and defines several parameters: + +.. code-block:: yaml + + parameters: + # ... + database_user: root + database_password: ~ + +Not surprisingly, these are referenced from inside of ``config.yml`` and help to +configure DoctrineBundle and other parts of Symfony: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + doctrine: + dbal: + driver: pdo_mysql + # ... + user: '%database_user%' + password: '%database_password%' + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('doctrine', array( + 'dbal' => array( + 'driver' => 'pdo_mysql', + // ... + + 'user' => '%database_user%', + 'password' => '%database_password%', + ), + )); + +But the ``parameters.yml`` file *is* special: it defines the values that usually +change on each server. For example, the database credentials on your local +development machine might be different from your workmates. That's why this file +is not committed to the shared repository and is only stored on your machine. + +Because of that, **parameters.yml is not committed to your version control**. In fact, +the ``.gitignore`` file that comes with Symfony prevents it from being committed. + +However, a ``parameters.yml.dist`` file *is* committed (with dummy values). This file +isn't read by Symfony: it's just a reference so that Symfony knows which parameters +need to be defined in the ``parameters.yml`` file. If you add or remove keys to +``parameters.yml``, add or remove them from ``parameters.yml.dist`` too so both +files are always in sync. + +.. sidebar:: The Interactive Parameter Handler + + When you :ref:`install an existing Symfony project `, you + will need to create the ``parameters.yml`` file using the committed ``parameters.yml.dist`` + file as a reference. To help with this, after you run ``composer install``, a + Symfony script will automatically create this file by interactively asking you + to supply the value for each parameter defined in ``parameters.yml.dist``. For + more details - or to remove or control this behavior - see the + `Incenteev Parameter Handler`_ documentation. + +Environments & the Other Config Files +------------------------------------- + +You have just *one* app, but whether you realize it or not, you need it to behave +*differently* at different times: + +* While **developing**, you want your app to log everything and expose nice debugging + tools; + +* After deploying to **production**, you want that *same* app to be optimized for + speed and only log errors. + +How can you make *one* application behave in two different ways? With *environments*. + +You've probably already been using the ``dev`` environment without even knowing it. +After you deploy, you'll use the ``prod`` environment. + +To learn more about *how* to execute and control each environment, see +:doc:`/configuration/environments`. + +Keep Going! +----------- + +Congratulations! You've tackled the basics in Symfony. Next, learn about *each* +part of Symfony individually by following the guides. Check out: + +* :doc:`/forms` +* :doc:`/doctrine` +* :doc:`/service_container` +* :doc:`/security` +* :doc:`/email` +* :doc:`/logging` + +And the many other topics. + +Learn more +---------- + +.. toctree:: + :maxdepth: 1 + :glob: + + configuration/* + +.. _`Incenteev Parameter Handler`: https://github.com/Incenteev/ParameterHandler diff --git a/frontend.rst b/frontend.rst new file mode 100644 index 0000000..8947cbf --- /dev/null +++ b/frontend.rst @@ -0,0 +1,110 @@ +Managing CSS and JavaScript +=========================== + +Symfony ships with a pure-JavaScript library - called Webpack Encore - that makes +working with CSS and JavaScript a joy. You can use it, use something else, or just +create static CSS and JS files in your ``web/`` directory and include them in your +templates. + +.. _frontend-webpack-encore: + +Webpack Encore +-------------- + +`Webpack Encore`_ is a simpler way to integrate `Webpack`_ into your application. +It *wraps* Webpack, giving you a clean & powerful API for bundling JavaScript modules, +pre-processing CSS & JS and compiling and minifying assets. Encore gives you professional +asset system that's a *delight* to use. + +Encore is inspired by `Webpacker`_ and `Mix`_, but stays in the spirit of Webpack: +using its features, concepts and naming conventions for a familiar feel. It aims +to solve the most common Webpack use cases. + +.. tip:: + + Encore is made by `Symfony`_ and works *beautifully* in Symfony applications. + But it can easily be used in any application... in any language! + +.. _encore-toc: + +Encore Documentation +-------------------- + +Getting Started +............... + +* :doc:`Installation ` +* :doc:`First Example ` + +Adding more Features +.................... + +* :doc:`CSS Preprocessors: Sass, LESS, etc ` +* :doc:`PostCSS and autoprefixing ` +* :doc:`Enabling React.js ` +* :doc:`Enabling Vue.js (vue-loader) ` +* :doc:`Configuring Babel ` +* :doc:`Source maps ` +* :doc:`Enabling TypeScript (ts-loader) ` + +Optimizing +.......... + +* :doc:`Versioning (and the manifest.json file) ` +* :doc:`Using A CDN ` +* :doc:`Creating a "Shared" entry for re-used modules ` + +Guides +...... + +* :doc:`Using Bootstrap CSS & JS ` +* :doc:`Creating Page-Specific CSS/JS ` +* :doc:`jQuery and Legacy Applications ` +* :doc:`Passing Information from Twig to JavaScript ` +* :doc:`webpack-dev-server and Hot Module Replacement (HMR) ` +* :doc:`Adding custom loaders & plugins ` +* :doc:`Advanced Webpack Configuration ` + +Issues & Questions +.................. + +* :doc:`FAQ & Common Issues ` +* :doc:`/frontend/encore/versus-assetic` + +Full API +........ + +* `Full API`_: https://github.com/symfony/webpack-encore/blob/master/index.js + +Assetic +------- + +Assetic is a pure PHP library that helps to process & optimize your assets (similar +to Encore). Even though we recommend using Encore, Assetic still works great. For +a comparison, see :doc:`/frontend/encore/versus-assetic`. + +For more about Assetic, see :doc:`/frontend/assetic`. + +Other Front-End Articles +------------------------ + +.. toctree:: + :hidden: + :glob: + + frontend/encore/installation + frontend/encore/simple-example + frontend/encore/* + +.. toctree:: + :maxdepth: 1 + :glob: + + frontend/* + +.. _`Webpack Encore`: https://www.npmjs.com/package/@symfony/webpack-encore +.. _`Webpack`: https://webpack.js.org/ +.. _`Webpacker`: https://github.com/rails/webpacker +.. _`Mix`: https://laravel.com/docs/5.4/mix +.. _`Symfony`: http://symfony.com/ +.. _`Full API`: https://github.com/symfony/webpack-encore/blob/master/index.js diff --git a/assetic.rst b/frontend/assetic.rst similarity index 100% rename from assetic.rst rename to frontend/assetic.rst diff --git a/assetic/apply_to_option.rst b/frontend/assetic/apply_to_option.rst similarity index 73% rename from assetic/apply_to_option.rst rename to frontend/assetic/apply_to_option.rst index cc5a502..a7db3b6 100644 --- a/assetic/apply_to_option.rst +++ b/frontend/assetic/apply_to_option.rst @@ -1,18 +1,18 @@ .. index:: single: Assetic; Aplicar filtros -Como Aplicar um filtro Assetic a uma extensão de arquivo específica -=================================================================== +Como Aplicar um Filtro do Assetic a uma Extensão de Arquivo Específica +====================================================================== .. include:: /assetic/_standard_edition_warning.rst.inc -Os filtros ``Assetic`` podem ser aplicados em arquivos individuais, grupos de arquivos ou até mesmo, +Os filtros do Assetic podem ser aplicados em arquivos individuais, grupos de arquivos ou até mesmo, como você verá aqui, em arquivos que possuem uma extensão específica. Para mostrar como -lidar com cada opção, vamos supor que você deseja usar o filtro ``CoffeeScript`` do ``Assetic``, -que compila arquivos ``CoffeeScript`` em Javascript. +lidar com cada opção, vamos supor que você deseja usar o filtro CoffeeScript do +Assetic, que compila arquivos CoffeeScript em JavaScript. -A configuração principal é apenas os caminhos para ``coffee``, ``node`` e ``node_modules``. -Uma configuração de exemplo será parecida com a seguinte: +A configuração principal contém apenas os caminhos para ``coffee``, ``node`` e ``node_modules``. +Um exemplo de configuração pode ser assim: .. configuration-block:: @@ -61,10 +61,10 @@ Uma configuração de exemplo será parecida com a seguinte: ), )); -Filtrando um único arquivo +Filtrando um Único Arquivo -------------------------- -Agora, você pode servir um único arquivo ``CoffeeScript`` como JavaScript a partir de seus +Agora você pode servir um único arquivo CoffeeScript como JavaScript a partir de seus templates: .. configuration-block:: @@ -84,13 +84,13 @@ templates: -Isso é tudo o que é necessário para compilar este arquivo ``CoffeeScript`` e servir ele +Isso é tudo o que é necessário para compilar este arquivo CoffeeScript e servi-lo como JavaScript compilado. -Filtrando vários arquivos +Filtrando Vários Arquivos ------------------------- -Você também pode combinar vários arquivos ``CoffeeScript`` em um único arquivo de saída: +Você também pode combinar vários arquivos CoffeeScript em um único arquivo de saída: .. configuration-block:: @@ -114,25 +114,24 @@ Você também pode combinar vários arquivos ``CoffeeScript`` em um único arqui -Ambos os arquivos agora serão servidos como um único arquivo compilado em -JavaScript regular. +Ambos os arquivos agora serão servidos como um único arquivo compilado em JavaScript regular. .. _assetic-apply-to: -Filtrando com base em uma extensão de arquivo +Filtrando com Base em uma Extensão de Arquivo --------------------------------------------- -Uma das grandes vantagens de usar o ``Assetic`` é minimizar o número de arquivos -``asset`` para reduzir as solicitações HTTP. A fim de fazer seu pleno uso, seria -bom combinar *todos* os seus arquivos JavaScript e ``CoffeeScript`` juntos, -uma vez que, todos serão servidos como JavaScript. Infelizmente, apenas -adicionar os arquivos JavaScript aos arquivos a serem combinados como acima não funcionará, -pois, os arquivos JavaScript regulares não sobreviverão a compilação do ``CoffeeScript``. +Uma das grandes vantagens de usar o Assetic é minimizar o número de arquivos +asset para reduzir as requisições HTTP. Para aproveitar isso ao máximo, seria +bom combinar *todos* os seus arquivos JavaScript e CoffeeScript juntos, +uma vez que todos serão servidos como JavaScript. Infelizmente, apenas +adicionar os arquivos JavaScript aos arquivos a serem combinados como mostrado acima não +funcionará, pois os arquivos JavaScript comuns não sobreviverão à compilação do CoffeeScript. -Esse problema pode ser evitado usando a opção ``apply_to``, que permite especificar -que filtro deverá ser sempre aplicado à determinadas extensões de arquivo. -Nesse caso, você pode especificar que o filtro ``coffee`` será -aplicado em todos os arquivos ``.coffee``: +Esse problema pode ser evitado usando a opção ``apply_to``, que permite +especificar que filtro deverá ser sempre aplicado a determinadas extensões de arquivo. +Neste caso, você pode especificar que o filtro ``coffee`` será aplicado em todos +os arquivos ``.coffee``: .. configuration-block:: @@ -164,8 +163,9 @@ aplicado em todos os arquivos ``.coffee``: name="coffee" bin="/usr/bin/coffee" node="/usr/bin/node" - apply_to="\.coffee$" /> - /usr/lib/node_modules/ + apply-to="\.coffee$"> + /usr/lib/node_modules/ + @@ -175,18 +175,18 @@ aplicado em todos os arquivos ``.coffee``: $container->loadFromExtension('assetic', array( 'filters' => array( 'coffee' => array( - 'bin' => '/usr/bin/coffee', - 'node' => '/usr/bin/node', + 'bin' => '/usr/bin/coffee', + 'node' => '/usr/bin/node', 'node_paths' => array('/usr/lib/node_modules/'), - 'apply_to' => '\.coffee$', + 'apply_to' => '\.coffee$', ), ), )); -Com essa opção, você não precisa especificar o filtro ``coffee`` no template. -Você também pode listar os arquivos JavaScript regulares, todos os quais serão combinados -e renderizados como um único arquivo JavaScript (apenas com os arquivos ``.coffee`` -sendo executados através do filtro ``CoffeeScript``): +Com esta opção, você não precisa mais especificar o filtro ``coffee`` no +template. Você também pode listar os arquivos JavaScript comuns, todos os quais serão +combinados e renderizados como um único arquivo JavaScript (com apenas os arquivos ``.coffee`` +sendo passados pelo filtro CoffeeScript): .. configuration-block:: diff --git a/frontend/assetic/asset_management.rst b/frontend/assetic/asset_management.rst new file mode 100644 index 0000000..e46c72c --- /dev/null +++ b/frontend/assetic/asset_management.rst @@ -0,0 +1,691 @@ +.. index:: + single: Assetic; Introdução + +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 um de seus recursos, instale o +AsseticBundle executando o seguinte comando de console no seu projeto: + +.. code-block:: bash + + $ 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: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + debug: '%kernel.debug%' + use_controller: '%kernel.debug%' + filters: + cssrewrite: ~ + + # ... + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'debug' => '%kernel.debug%', + 'use_controller' => '%kernel.debug%', + 'filters' => array( + 'cssrewrite' => null, + ), + // ... + )); + + // ... + +Apresentando o Assetic +---------------------- + +O Assetic combina duas idéias principais: :ref:`assets ` e +:ref:`filtros `. Os assets são arquivos como CSS, +JavaScript e arquivos de imagem. Os filtros podem ser aplicados a +estes 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ê apenas serve os arquivos que estão armazenados na aplicação +diretamente: + +.. configuration-block:: + + .. code-block:: html+twig + + + + .. code-block:: php + + + +Mas *com* o Assetic, você pode manipular estes assets da forma que desejar (ou +carregá-los de qualquer lugar) antes de servi-los. Isso significa que você pode: + +* Minificar e combinar todos os seus arquivos CSS e JS + +* Passar 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 + +.. _assetic-assets: + +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 +obtidos a partir de várias fontes, como, por exemplo, a partir de um bundle. + +Você pode usar o Assetic para processar :ref:`folhas de estilo CSS `, +:ref:`arquivos JavaScript ` e +:ref:`imagens `. A filosofia +por trás da adição é basicamente a mesma, mas com uma sintaxe ligeiramente diferente. + +.. _assetic-including-javascript: + +Incluindo Arquivos JavaScript +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Para incluir arquivos JavaScript, use a tag ``javascripts`` em qualquer template: + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts '@AppBundle/Resources/public/js/*' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AppBundle/Resources/public/js/*') + ) as $url): ?> + + + +.. note:: + + Se os templates da sua aplicação usam os nomes de bloco padrão da Edição + Standard do Symfony, a tag ``javascripts`` provavelmente estará no bloco + ``javascripts``: + + .. code-block:: html+twig + + {# ... #} + {% block javascripts %} + {% javascripts '@AppBundle/Resources/public/js/*' %} + + {% endjavascripts %} + {% endblock %} + {# ... #} + +.. tip:: + + Você também pode incluir folhas de estilo CSS: consulte :ref:`assetic-including-css`. + +Neste exemplo, todos os arquivos no diretório ``Resources/public/js/`` do +AppBundle serão carregados e servidos a partir de um local diferente. A tag +renderizada real pode ser simplesmente: + +.. code-block:: html + + + +Este é um ponto chave: uma vez que você deixe o Assetic lidar com seus assets, os arquivos são +servidos a partir de um local diferente. Isto *causará* problemas com arquivos CSS +que referenciam imagens pelo seu caminho relativo. Consulte :ref:`assetic-cssrewrite`. + +.. _assetic-including-css: + +Incluindo Folhas de Estilo CSS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Para incluir folhas de estilo CSS, você pode usar a mesma técnica explicada acima, +mas com a tag ``stylesheets``: + +.. configuration-block:: + + .. code-block:: html+twig + + {% stylesheets 'bundles/app/css/*' filter='cssrewrite' %} + + {% endstylesheets %} + + .. code-block:: html+php + + stylesheets( + array('bundles/app/css/*'), + array('cssrewrite') + ) as $url): ?> + + + +.. note:: + + Se os templates da sua aplicação usam os nomes de bloco padrão da Edição + Standard do Symfony, a tag ``stylesheets`` provavelmente estará no bloco + ``stylesheets``: + + .. code-block:: html+twig + + {# ... #} + {% block stylesheets %} + {% stylesheets 'bundles/app/css/*' filter='cssrewrite' %} + + {% endstylesheets %} + {% endblock %} + {# ... #} + +Mas devido ao Assetic mudar os caminhos para seus assets, isto *quebrará* quaisquer +imagens de background (ou outros caminhos) que usam caminhos relativos, a menos que você use +o filtro :ref:`cssrewrite `. + +.. note:: + + Observe que exemplo original que incluiu arquivos JavaScript, você + se referiu aos arquivos usando um caminho como ``@AppBundle/Resources/public/file.js``, + mas que neste exemplo, você se referiu aos arquivos CSS usando seus caminhos reais, + publicamente acessíveis: ``bundles/app/css``. Você pode usar qualquer um, exceto + que existe um problema conhecido que faz com que o filtro ``cssrewrite`` falhe + ao usar a sintaxe ``@AppBundle`` para folhas de estilo CSS. + +.. _assetic-including-image: + +Incluindo Imagens +~~~~~~~~~~~~~~~~~ + +Para incluir uma imagem você pode usar a tag ``image``. + +.. configuration-block:: + + .. code-block:: html+twig + + {% image '@AppBundle/Resources/public/images/example.jpg' %} + Example + {% endimage %} + + .. code-block:: html+php + + image( + array('@AppBundle/Resources/public/images/example.jpg') + ) as $url): ?> + Example + + +Você pode também usar o Assetic para otimização de imagens. Mais informações em +:doc:`/frontend/assetic/jpeg_optimize`. + +.. tip:: + + Ao invés de usar o Assetic para incluir imagens, você pode considerar usar o bundle + `LiipImagineBundle`_ da comunidade, que permite comprimir e + manipular imagens (rotacionar, redimencionar, aplicar marca d'água, etc.) antes de servi-las. + +.. _assetic-cssrewrite: + +Corrigindo Caminhos CSS com o Filtro ``cssrewrite`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Como o Assetic gera novos URLs para seus assets, qualquer caminho relativo dentro dos +seus arquivos CSS irá quebrar. Para corrigir isso, certifique-se de usar o filtro ``cssrewrite`` +com sua tag ``stylesheets``. Ele analisa seus arquivos CSS e corrige +os caminhos internamente para refletir a nova localização. + +Você pode ver um exemplo na seção anterior. + +.. caution:: + + Ao usar o filtro ``cssrewrite``, não referencie seus arquivos CSS usando + a sintaxe ``@AppBundle``. Veja a nota na seção anterior para obter detalhes. + +Combinando Assets +~~~~~~~~~~~~~~~~~ + +Um recurso do Assetic é que ele irá combinar vários arquivos em um único. Isto ajuda +a reduzir o número de requisições HTTP, o que é ótimo para o desempenho front-end. +Ele também permite que você mantenha os arquivos mais facilmente, dividindo-os em +partes gerenciáveis. Isso pode ajudar com a reusabilidade, uma vez que você pode facilmente separar +os arquivos específicos do projeto daqueles que podem ser usados em outras aplicações, +mas ainda servi-los como um único arquivo: + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts + '@AppBundle/Resources/public/js/*' + '@AcmeBarBundle/Resources/public/js/form.js' + '@AcmeBarBundle/Resources/public/js/calendar.js' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array( + '@AppBundle/Resources/public/js/*', + '@AcmeBarBundle/Resources/public/js/form.js', + '@AcmeBarBundle/Resources/public/js/calendar.js', + ) + ) as $url): ?> + + + +No ambiente ``dev``, cada arquivo ainda é servido individualmente, de modo que +você possa depurar problemas mais facilmente. No entanto, no ambiente ``prod`` +(ou mais especificamente, quando a flag ``debug`` é ``false``), eles serão +renderizados como uma única tag ``script``, que contém o conteúdo de todos +os arquivos JavaScript. + +.. tip:: + + Se você é novo no Assetic e tentar usar sua aplicação no ambiente + ``prod`` (utilizando o controlador ``app.php``), você provavelmente verá + que todos os seus CSS e JS quebram. Não se preocupe! Isso é de propósito. + Para detalhes sobre a utilização do Assetic no ambiente ``prod``, consulte :ref:`assetic-dumping`. + +A combinação de arquivos não se aplica apenas a *seus* arquivos. Você também pode usar o Assetic para +combinar assets de terceiros, tais como jQuery, com os seus próprios assets em um único arquivo: + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts + '@AppBundle/Resources/public/js/thirdparty/jquery.js' + '@AppBundle/Resources/public/js/*' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array( + '@AppBundle/Resources/public/js/thirdparty/jquery.js', + '@AppBundle/Resources/public/js/*', + ) + ) as $url): ?> + + + +Usando Assets Nomeados +~~~~~~~~~~~~~~~~~~~~~~ + +As diretivas de configuração do AsseticBundle permitem que você defina conjuntos de assets nomeados. +Você pode fazer isso definindo os arquivos de entrada, filtros e arquivos de saída em sua +configuração na seção ``assetic``. Leia mais na +:doc:`Referência da Configuração do Assetic `. + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + assets: + jquery_and_ui: + inputs: + - '@AppBundle/Resources/public/js/thirdparty/jquery.js' + - '@AppBundle/Resources/public/js/thirdparty/jquery.ui.js' + + .. code-block:: xml + + + + + + + + @AppBundle/Resources/public/js/thirdparty/jquery.js + @AppBundle/Resources/public/js/thirdparty/jquery.ui.js + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'assets' => array( + 'jquery_and_ui' => array( + 'inputs' => array( + '@AppBundle/Resources/public/js/thirdparty/jquery.js', + '@AppBundle/Resources/public/js/thirdparty/jquery.ui.js', + ), + ), + ), + )); + +Depois de ter definido os assets nomeados, você pode referenciá-los em seus templates +com a notação ``@asset_nomeado``: + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts + '@jquery_and_ui' + '@AppBundle/Resources/public/js/*' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array( + '@jquery_and_ui', + '@AppBundle/Resources/public/js/*', + ) + ) as $url): ?> + + + +.. _assetic-filters: + +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 arquivos CoffeeScript para JavaScript 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ê precisará instalar +uma biblioteca de terceiro para usar um filtro. A grande vantagem de usar o Assetic +para chamar estas bibliotecas (ao invés de usá-las diretamente) é que, em vez +de ter que executá-las manualmente depois de trabalhar nos arquivos, o Assetic irá +cuidar disso para você e remover completamente esta etapa dos seus processos 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 minificador de JavaScript UglifyJS, a seguinte configuração +deve ser definida: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + uglifyjs2: + bin: /usr/local/bin/uglifyjs + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'uglifyjs2' => array( + 'bin' => '/usr/local/bin/uglifyjs', + ), + ), + )); + +Agora, para efetivamente *usar* o filtro em um grupo de arquivos JavaScript, adicione-o +em seu template: + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts '@AppBundle/Resources/public/js/*' filter='uglifyjs2' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AppBundle/Resources/public/js/*'), + array('uglifyjs2') + ) as $url): ?> + + + +Um guia mais detalhado sobre a configuração e uso dos filtros do Assetic, bem como +detalhes do modo de depuração do Assetic pode ser encontrado em :doc:`/frontend/assetic/uglifyjs`. + +Controlando o URL Usado +----------------------- + +Se desejar, você pode controlar os URLs que o Assetic produz. Isto é +feito a partir do template e é relativo ao diretório público raiz: + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts '@AppBundle/Resources/public/js/*' output='js/compiled/main.js' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AppBundle/Resources/public/js/*'), + array(), + array('output' => 'js/compiled/main.js') + ) as $url): ?> + + + +.. note:: + + O Symfony fornece várias implementações de cache busting através das + opções de configuração + :ref:`version `, + :ref:`version_format ` e + :ref:`json_manifest_path `. + +.. _assetic-dumping: + +Fazendo o Dump dos Arquivos 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 asset que você altere. +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, ao invés +de gerá-los dinamicamente. + +Fazendo o Dump dos Arquivos Asset no Ambiente ``prod`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No ambiente ``prod``, seus arquivos 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: + +.. code-block:: html + + + +Além disso, esse arquivo **não** existe realmente, nem é renderizado de forma dinâmica +pelo Symfony (como os arquivos asset são renderizados no ambiente ``dev``). Isto é de +propósito - deixar o Symfony gerar esses arquivos dinamicamente em um ambiente +de produção é muito lento. + +.. _assetic-dump-prod: + +Em vez disso, cada vez que você usar sua aplicação no ambiente ``prod `` (e, portanto, +cada vez que você implantar), você deve executar o seguinte comando: + +.. code-block:: terminal + + $ php bin/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, você precisará executar o comando novamente para gerar +o novo arquivo. + +Fazendo o Dump dos Arquivos 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), exceto que os assets podem carregar visivelmente 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``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config_dev.yml + assetic: + use_controller: false + + .. code-block:: xml + + + + + + + + + .. code-block:: php + + // 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ê +precisará fazer o dump deles manualmente. Para fazer isso, execute o seguinte comando: + +.. code-block:: terminal + + $ php bin/console assetic:dump + +Isso fisicamente grava todos os arquivos asset que você precisa para seu ambiente +``dev``. A grande desvantagem é que você precisa executar isso cada vez que +você atualizar um asset. Felizmente, ao usar o comando ``assetic:watch``, +os assets serão gerados de novo automaticamente *enquanto eles mudam*: + +.. code-block:: terminal + + $ php bin/console assetic:watch + +O comando ``assetic:watch`` foi introduzido no AsseticBundle 2.4. Em versões +anteriores, você tinha que usar a opção ``--watch`` do comando ``assetic:dump`` +para o mesmo comportamento. + +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: + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts '@AppBundle/Resources/public/js/*' output='js/compiled/main.js' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AppBundle/Resources/public/js/*'), + array(), + array('output' => 'js/compiled/main.js') + ) as $url): ?> + + + +.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle diff --git a/frontend/assetic/jpeg_optimize.rst b/frontend/assetic/jpeg_optimize.rst new file mode 100644 index 0000000..a981f72 --- /dev/null +++ b/frontend/assetic/jpeg_optimize.rst @@ -0,0 +1,310 @@ +.. index:: + single: Assetic; Otimização de Imagens + +Como Usar o Assetic para Otimização de imagens com Funções do Twig +================================================================== + +.. include:: /assetic/_standard_edition_warning.rst.inc + +Dentre os seus vários filtros, o Assetic possui quatro que podem ser utilizados para a otimização +de imagens on-the-fly. Isso permite obter os benefícios de tamanhos menores de arquivos +sem ter que usar um editor de imagens para processar cada imagem. Os resultados +são armazenados em cache e pode ser feito o dump para produção de modo que não haja impacto no desempenho +para seus usuários finais. + +Usando o Jpegoptim +------------------ + +`Jpegoptim`_ é um utilitário para otimizar arquivos JPEG. Para usá-lo com o Assetic, certifique-se +de já tê-lo instalado em seu sistema, e então configure sua localização +usando a opção ``bin`` do filtro ``jpegoptim``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + jpegoptim: + bin: caminho/para/jpegoptim + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'jpegoptim' => array( + 'bin' => 'caminho/para/jpegoptim', + ), + ), + )); + +Ele agora pode ser usado em um template: + +.. configuration-block:: + + .. code-block:: html+twig + + {% image '@AppBundle/Resources/public/images/example.jpg' + filter='jpegoptim' output='/images/example.jpg' %} + Example + {% endimage %} + + .. code-block:: html+php + + image( + array('@AppBundle/Resources/public/images/example.jpg'), + array('jpegoptim') + ) as $url): ?> + Example + + +Removendo Todos os Dados EXIF +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Por padrão, o filtro ``jpegoptim`` remove apenas algumas das meta informações armazenadas +na imagem. Para remover todos os dados EXIF e comentários, configure a opção ``strip_all`` +para ``true``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + jpegoptim: + bin: caminho/para/jpegoptim + strip_all: true + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'jpegoptim' => array( + 'bin' => 'caminho/para/jpegoptim', + 'strip_all' => 'true', + ), + ), + )); + +Diminuindo a Qualidade Máxima +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Por padrão, o filtro ``jpegoptim`` não altera o nível de qualidade da imagem +JPEG. Use a opção ``max`` para configurar a qualidade máxima (numa +escala de ``0`` a ``100``). A redução no tamanho do arquivo da imagem será, claro, +ao custo da sua qualidade: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + jpegoptim: + bin: caminho/para/jpegoptim + max: 70 + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'jpegoptim' => array( + 'bin' => 'caminho/para/jpegoptim', + 'max' => '70', + ), + ), + )); + +Sintaxe Curta: Função Twig +-------------------------- + +Se você estiver usando o Twig, é possível conseguir tudo isso com uma sintaxe +curta, ao habilitar e usar uma função especial do Twig. Comece adicionando a +seguinte configuração: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + jpegoptim: + bin: caminho/para/jpegoptim + twig: + functions: + jpegoptim: ~ + + .. code-block:: xml + + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'jpegoptim' => array( + 'bin' => 'caminho/para/jpegoptim', + ), + ), + 'twig' => array( + 'functions' => array('jpegoptim'), + ), + )); + +O template do Twig agora pode ser alterado para o seguinte: + +.. code-block:: html+twig + + Example + +Você também pode especificar o diretório de saída para imagens no arquivo de configuração do +Assetic: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + jpegoptim: + bin: caminho/para/jpegoptim + twig: + functions: + jpegoptim: { output: images/*.jpg } + + .. code-block:: xml + + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'jpegoptim' => array( + 'bin' => 'caminho/para/jpegoptim', + ), + ), + 'twig' => array( + 'functions' => array( + 'jpegoptim' => array( + 'output' => 'images/*.jpg', + ), + ), + ), + )); + +.. tip:: + + Você pode comprimir e manipular imagens carregadas por upload usando o + bundle `LiipImagineBundle`_ da comunidade. + +.. _`Jpegoptim`: http://www.kokkonen.net/tjko/projects.html +.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle diff --git a/frontend/assetic/php.rst b/frontend/assetic/php.rst new file mode 100644 index 0000000..c0a8f93 --- /dev/null +++ b/frontend/assetic/php.rst @@ -0,0 +1,213 @@ +.. index:: + single: Front-end; Assetic, Bootstrap + +Combinando, Compilando e Minificando Assets Web com Bibliotecas PHP +=================================================================== + +.. include:: /assetic/_standard_edition_warning.rst.inc + +As Melhores Práticas Oficiais do Symfony recomendam o uso do Assetic para +:doc:`gerenciar assets web `, a menos que você se sinta +confortável com ferramentas front-end baseadas em JavaScript. + +Mesmo se estas soluções baseadas em JavaScript forem as mais adequadas do +ponto de vista técnico, o uso de bibliotecas alternativas em PHP puro pode ser útil em +alguns cenários: + +* Se você não pode instalar ou usar o ``npm`` e as outras soluções JavaScript; +* Se você prefere limitar a quantidade de tecnologias diferentes usadas em suas + aplicações; +* Se você quer simplificar a implantação da aplicação. + +Neste artigo, você aprenderá como combinar e minificar arquivos CSS e JavaScript +e como compilar arquivos Sass usando bibliotecas puramente em PHP com o Assetic. + +Instalando as Bibliotecas de Compressão de Terceiros +---------------------------------------------------- + +O Assetic inclui vários filtros prontos para usar, mas não inclui as bibliotecas associadas +a estes filtros. Portanto, antes de habilitar os filtros usados neste artigo, +você deve instalar duas bibliotecas. Abra um console de comando, navegue até o diretório do seu +projeto e execute os seguintes comandos: + +.. code-block:: terminal + + $ composer require leafo/scssphp + $ composer require patchwork/jsqueeze + +Organizando seus Arquivos Asset Web +----------------------------------- + +Este exemplo irá incluir uma configuração usando o framework Bootstrap, jQuery, FontAwesome +e alguns arquivos CSS e JavaScript comuns da aplicação (chamados ``main.css`` e +``main.js``). A estrutura de diretório recomendada para esta configuração parece com a seguinte: + +.. code-block:: text + + web/assets/ + ├── css + │   ├── main.css + │   └── code-highlight.css + ├── js + │   ├── bootstrap.js + │   ├── jquery.js + │   └── main.js + └── scss + ├── bootstrap + │   ├── _alerts.scss + │   ├── ... + │   ├── _variables.scss + │   ├── _wells.scss + │   └── mixins + │   ├── _alerts.scss + │   ├── ... + │   └── _vendor-prefixes.scss + ├── bootstrap.scss + ├── font-awesome + │   ├── _animated.scss + │   ├── ... + │   └── _variables.scss + └── font-awesome.scss + +Combinando e Minificando Arquivos CSS e Compilando Arquivos SCSS +---------------------------------------------------------------- + +Primeiro, configure um novo filtro ``scssphp`` do Assetic: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + scssphp: + formatter: 'Leafo\ScssPhp\Formatter\Compressed' + # ... + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'scssphp' => array( + 'formatter' => 'Leafo\ScssPhp\Formatter\Compressed', + ), + // ... + ), + )); + +O valor da opção ``formatter`` é o nome de classe totalmente qualificado do +formatador usado pelo filtro para produzir o arquivo CSS compilado. O uso do +formatador compactado irá minificar o arquivo resultante, independentemente dos +arquivos originais serem arquivos CSS comuns ou arquivos SCSS. + +Em seguida, atualize seu template Twig para adicionar a tag ``{% stylesheets %}`` definida +pelo Assetic: + +.. code-block:: html+twig + + {# app/Resources/views/base.html.twig #} + + + + + + {% stylesheets filter="scssphp" output="css/app.css" + "assets/scss/bootstrap.scss" + "assets/scss/font-awesome.scss" + "assets/css/*.css" + %} + + {% endstylesheets %} + +Esta simples configuração compila, combina e minifica os arquivos SCSS em um +arquivo CSS comum que é colocado em ``web/css/app.css``. Este é o único arquivo CSS +que será servido aos seus visitantes. + +Combinando e Minificando Arquivos JavaScript +-------------------------------------------- + +Primeiro, configure um novo filtro ``jsqueeze`` do Assetic da seguinte maneira: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + jsqueeze: ~ + # ... + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'jsqueeze' => null, + // ... + ), + )); + +Em seguida, atualize o código do seu template Twig para adicionar a tag ``{% javascripts %}`` +definida pelo Assetic: + +.. code-block:: html+twig + + + + {% javascripts filter="?jsqueeze" output="js/app.js" + "assets/js/jquery.js" + "assets/js/bootstrap.js" + "assets/js/main.js" + %} + + {% endjavascripts %} + + + + +Esta simples configuração combina todos os arquivos JavaScript, minifica o conteúdo +e salva a saída no arquivo ``web/js/app.js``, que é o arquivo +servido aos seus visitantes. + +O caractere ``?`` inicial no nome do filtro ``jsqueeze`` diz ao Assetic para aplicar +o filtro apenas quando *não estiver* em modo ``debug``. Na prática, isso significa que você +verá arquivos não minificados enquanto desenvolve e arquivos minificados no ambiente ``prod``. diff --git a/frontend/assetic/uglifyjs.rst b/frontend/assetic/uglifyjs.rst new file mode 100644 index 0000000..7b98827 --- /dev/null +++ b/frontend/assetic/uglifyjs.rst @@ -0,0 +1,334 @@ +.. index:: + single: Assetic; UglifyJS + +Como Minificar Arquivos CSS/JS (Usando UglifyJS e UglifyCSS) +============================================================ + +.. include:: /assetic/_standard_edition_warning.rst.inc + +O `UglifyJS`_ é um kit de ferramentas de análise/compressão/embelezamento de JavaScript. Ele pode ser usado +para combinar e minificar assets JavaScript para que eles exijam menos requisições HTTP +e façam seu site carregar mais rápido. O `UglifyCSS`_ é um compressor/embelezador CSS +muito semelhante ao UglifyJS. + +Neste artigo, a instalação, configuração e uso do UglifyJS são +mostrados em detalhes. O UglifyCSS funciona da mesma forma e é apenas +mencionado brevemente. + +Instalando o UglifyJS +--------------------- + +O UglifyJS está disponível como um módulo do `Node.js`_. Primeiro, você precisa `instalar o Node.js`_ +e então decidir o método de instalação: global ou local. + +Instalação Global +~~~~~~~~~~~~~~~~~ + +O método de instalação global faz com que todos os seus projetos usem exatamente a mesma versão do +UglifyJS, o que simplifica sua manutenção. Abra seu console de comando e execute +o seguinte comando (você pode precisar executá-lo como um usuário root): + +.. code-block:: terminal + + $ npm install -g uglify-js + +Agora você pode executar o comando global ``uglifyjs`` em qualquer lugar do seu sistema: + +.. code-block:: terminal + + $ uglifyjs --help + +Instalação Local +~~~~~~~~~~~~~~~~ + +Também é possível instalar o UglifyJS apenas dentro do seu projeto, o que é útil +quando seu projeto requer uma versão específica do UglifyJS. Para fazer isso, instale-o +sem a opção ``-g`` e especifique o caminho onde instalará o módulo: + +.. code-block:: terminal + + $ cd /caminho/para/seu/projeto/symfony + $ npm install uglify-js --prefix app/Resources + +É recomendado que você instale o UglifyJS na sua pasta ``app/Resources`` e +adicione a pasta ``node_modules`` ao controle de versão. Alternativamente, você pode criar +um arquivo `package.json`_ do npm e especificar suas dependências lá. + +Agora você pode executar o comando ``uglifyjs`` disponível no diretório +``node_modules``: + +.. code-block:: terminal + + $ "./app/Resources/node_modules/.bin/uglifyjs" --help + +Configurando o Filtro ``uglifyjs2`` +----------------------------------- + +Agora precisamos configurar o Symfony para usar o filtro ``uglifyjs2`` ao processar +seus JavaScripts: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + uglifyjs2: + # o caminho para o executável uglifyjs + bin: /usr/local/bin/uglifyjs + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'uglifyjs2' => array( + // o caminho para o executável uglifyjs + 'bin' => '/usr/local/bin/uglifyjs', + ), + ), + )); + +.. note:: + + O caminho onde o UglifyJS está instalado pode variar dependendo do seu sistema. + Para descobrir onde o npm mantém a pasta ``bin``, execute o seguinte comando: + + .. code-block:: terminal + + $ npm bin -g + + Ele deve exibir uma pasta em seu sistema, dentro da qual você deve encontrar + o executável do UglifyJS. + + Se você instalou o UglifyJS localmente, você pode encontrar a pasta ``bin`` dentro + da pasta ``node_modules``. Ela é chamada ``.bin`` neste caso. + +Você agora tem acesso ao filtro ``uglifyjs2`` em sua aplicação. + +Configurando o Binário ``node`` +------------------------------- + +O Assetic tenta encontrar o binário node automaticamente. Se ele não puder ser encontrado, você +pode configurar sua localização usando a chave ``node``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + # o caminho para o executável node + node: /usr/bin/nodejs + filters: + uglifyjs2: + # o caminho para o executável uglifyjs + bin: /usr/local/bin/uglifyjs + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'node' => '/usr/bin/nodejs', + 'uglifyjs2' => array( + // o caminho para o executável uglifyjs + 'bin' => '/usr/local/bin/uglifyjs', + ), + )); + +Minificando seus Assets +----------------------- + +Para aplicar o UglifyJS em seus assets, adicione a opção ``filter`` nas +tags de asset dos seus templates para dizer ao Assetic para usar o filtro ``uglifyjs2``: + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts '@AppBundle/Resources/public/js/*' filter='uglifyjs2' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AppBundle/Resources/public/js/*'), + array('uglifyj2s') + ) as $url): ?> + + + +.. note:: + + O exemplo acima assume que você tem um bundle chamado AppBundle e seus + arquivos JavaScript estão no diretório ``Resources/public/js`` do seu + bundle. Entretanto, você pode incluir seus arquivos JavaScript, não importa onde eles estejam. + +Com a adição do filtro ``uglifyjs2`` às tags de asset acima, você +agora deve ver os JavaScripts minificados sendo carregados muito mais rápido. + +Desativando a Minificação no Modo de Depuração +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Os JavaScripts minificados são muito difíceis de ler, e mais ainda de depurar. Por +isso, o Assetic permite desabilitar um certo filtro quando a sua aplicação está no +modo de depuração (por exemplo, ``app_dev.php``). Você pode fazer isso prefixando o nome do filtro +em seu template com um ponto de interrogação: ``?``. Isto diz ao Assetic para aplicar +esse filtro apenas quando o modo de depuração estiver desligado. (por exemplo, ``app.php``): + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts '@AppBundle/Resources/public/js/*' filter='?uglifyjs2' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AppBundle/Resources/public/js/*'), + array('?uglifyjs2') + ) as $url): ?> + + + +Para testar isso, mude para o seu ambiente ``prod`` (``app.php``). Mas antes +de mudar, não se esqueça de :ref:`limpar seu cache ` +e :ref:`fazer o dump dos assets do assetic `. + +.. tip:: + + Em vez de adicionar o filtro às tags de asset, você também pode configurar quais + filtros aplicar em cada arquivo no arquivo de configuração da sua aplicação. + Consulte :ref:`assetic-apply-to` para mais detalhes. + +Instalando, Configurando e Usando o UglifyCSS +--------------------------------------------- + +O uso do UglifyCSS funciona da mesma maneira que o UglifyJS. Primeiro, certifique-se de que +o pacote do node está instalado: + +.. code-block:: terminal + + # instalação global + $ npm install -g uglifycss + + # instalação local + $ cd /caminho/para/seu/projeto/symfony + $ npm install uglifycss --prefix app/Resources + +Em seguida, adicione a configuração para este filtro: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + uglifycss: + bin: /usr/local/bin/uglifycss + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'uglifycss' => array( + 'bin' => '/usr/local/bin/uglifycss', + ), + ), + )); + +Para usar o filtro em seus arquivos CSS, adicione o filtro ao helper ``stylesheets`` +do Assetic: + +.. configuration-block:: + + .. code-block:: html+twig + + {% stylesheets 'bundles/App/css/*' filter='uglifycss' filter='cssrewrite' %} + + {% endstylesheets %} + + .. code-block:: html+php + + stylesheets( + array('bundles/App/css/*'), + array('uglifycss'), + array('cssrewrite') + ) as $url): ?> + + + +Assim como com o filtro ``uglifyjs2``, se você prefixar o nome do filtro com +``?`` (isto é, ``?uglifycss``), a minificação irá ocorrer apenas quando você +não estiver em modo de depuração. + +.. _`UglifyJS`: https://github.com/mishoo/UglifyJS +.. _`UglifyCSS`: https://github.com/fmarcia/UglifyCSS +.. _`Node.js`: https://nodejs.org/ +.. _`instalar o Node.js`: https://nodejs.org/ +.. _`package.json`: http://browsenpm.org/package.json diff --git a/frontend/assetic/yuicompressor.rst b/frontend/assetic/yuicompressor.rst new file mode 100644 index 0000000..d92510c --- /dev/null +++ b/frontend/assetic/yuicompressor.rst @@ -0,0 +1,180 @@ +.. index:: + single: Assetic; YUI Compressor + +Como Minificar JavaScripts e Folhas de Estilo com o YUI Compressor +================================================================== + +.. caution:: + + O YUI Compressor `não é mais mantido pela Yahoo`_. É por isso que você é + **fortemente aconselhado a evitar o uso dos utilitários YUI**, a menos que seja estritamente necessário. + Consulte :doc:`/frontend/assetic/uglifyjs` para uma alternativa moderna e atualizada. + +.. include:: /assetic/_standard_edition_warning.rst.inc + +A Yahoo! oferece um excelente utilitário para minificar JavaScripts e folhas de estilo +para que eles sejam carregados mais rápido, o `YUI Compressor`_. Graças ao Assetic, +você pode tirar proveito desta ferramenta de forma muito fácil. + +Baixe o JAR do YUI Compressor +----------------------------- + +O YUI Compressor é escrito em Java e distribuído como um JAR. `Faça o download do JAR`_ +no site da Yahoo! e salve-o em ``app/Resources/java/yuicompressor.jar``. + +Configure os Filtros do YUI +--------------------------- + +Agora você precisa configurar dois filtros do Assetic em sua aplicação, um para +minificar os JavaScripts com o YUI Compressor e um para minificar as +folhas de estilo: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + # java: '/usr/bin/java' + filters: + yui_css: + jar: '%kernel.project_dir%/app/Resources/java/yuicompressor.jar' + yui_js: + jar: '%kernel.project_dir%/app/Resources/java/yuicompressor.jar' + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + // 'java' => '/usr/bin/java', + 'filters' => array( + 'yui_css' => array( + 'jar' => '%kernel.project_dir%/app/Resources/java/yuicompressor.jar', + ), + 'yui_js' => array( + 'jar' => '%kernel.project_dir%/app/Resources/java/yuicompressor.jar', + ), + ), + )); + +.. note:: + + Usuários do Windows precisam lembrar de atualizar a configuração para a localização correta do Java. + No Windows7 x64 bit, por padrão, é ``C:\Program Files (x86)\Java\jre6\bin\java.exe``. + +Você agora tem acesso a dois novos filtros do Assetic em sua aplicação: +``yui_css`` e ``yui_js``. Eles utilizarão o YUI Compressor para minificar +as folhas de estilo e os JavaScripts, respectivamente. + +Minifique os seus Assets +------------------------ + +Você agora tem o YUI Compressor configurado, mas nada vai acontecer até +você aplicar um desses filtros em um asset. Uma vez que os seus assets fazem parte +da camada de visão, este trabalho é feito em seus templates: + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts '@AppBundle/Resources/public/js/*' filter='yui_js' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AppBundle/Resources/public/js/*'), + array('yui_js') + ) as $url): ?> + + + +.. note:: + + O exemplo acima assume que você tem um bundle chamado AppBundle e os seus + arquivos JavaScript estão no diretório ``Resources/public/js`` do seu + bundle. Entretanto, isso não é importante - você pode incluir os seus arquivos + JavaScript, não importa onde eles estão. + +Com a adição do filtro ``yui_js`` nas tags de asset acima, você agora +deve ver os JavaScripts minificados sendo carregados muito mais rápido. O mesmo processo +pode ser repetido para minificar as suas folhas de estilo. + +.. configuration-block:: + + .. code-block:: html+twig + + {% stylesheets '@AppBundle/Resources/public/css/*' filter='yui_css' %} + + {% endstylesheets %} + + .. code-block:: html+php + + stylesheets( + array('@AppBundle/Resources/public/css/*'), + array('yui_css') + ) as $url): ?> + + + +Desativando a Minificação no Modo de Depuração +---------------------------------------------- + +Os JavaScripts e as folhas de estilo minificados são muito difíceis de ler, e mais ainda de +depurar. Por isso, o Assetic permite desabilitar um certo filtro quando a sua +aplicação está no modo de depuração. Você pode fazer isso prefixando o nome do filtro +em seu template com um ponto de interrogação: ``?``. Isto diz ao Assetic para aplicar +esse filtro apenas quando o modo de depuração estiver desligado. + +.. configuration-block:: + + .. code-block:: html+twig + + {% javascripts '@AppBundle/Resources/public/js/*' filter='?yui_js' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AppBundle/Resources/public/js/*'), + array('?yui_js') + ) as $url): ?> + + + +.. tip:: + + Em vez de adicionar o filtro às tags de asset, você também pode habilitá-lo + globalmente adicionando o atributo ``apply_to`` à configuração do filtro, por + exemplo, no filtro ``yui_js`` adicione ``apply_to: "\.js$"``. Para aplicar o filtro + apenas em produção, adicione isso ao arquivo ``config_prod``, em vez do + arquivo de configuração comum. Para obter detalhes sobre a aplicação de filtros por extensão de arquivo, + consulte :ref:`assetic-apply-to`. + +.. _`YUI Compressor`: http://yui.github.io/yuicompressor/ +.. _`Faça o download do JAR`: https://github.com/yui/yuicompressor/releases +.. _`não é mais mantido pela Yahoo`: http://yuiblog.com/blog/2013/01/24/yui-compressor-has-a-new-owner/ diff --git a/frontend/encore/versus-assetic.rst b/frontend/encore/versus-assetic.rst new file mode 100644 index 0000000..8907bd3 --- /dev/null +++ b/frontend/encore/versus-assetic.rst @@ -0,0 +1,56 @@ +Encore Versus Assetic? +====================== + +Symfony originally shipped with support for :doc:`Assetic `: a +pure PHP library capable of processing, combining and minifying CSS and JavaScript +files. And while Encore is now the recommended way of processing your assets, Assetic +still works well. + +So what are the differences between Assetic and Encore? + ++--------------------------+-------------------------------+-------------------------+ +| | Assetic | Encore + ++--------------------------+-------------------------------+-------------------------+ +| Language | Pure PHP, relies on other | Node.js | +| | language tools for some tasks | | ++--------------------------+-------------------------------+-------------------------+ +| Combine assets? | Yes | Yes | ++--------------------------+-------------------------------+-------------------------+ +| Minify assets? | Yes (when configured) | Yes (out-of-the-box) | ++--------------------------+-------------------------------+-------------------------+ +| Process Sass/Less? | Yes | Yes | ++--------------------------+-------------------------------+-------------------------+ +| Loads JS Modules? [1]_ | No | Yes | ++--------------------------+-------------------------------+-------------------------+ +| Load CSS Deps in JS? [1] | No | Yes | ++--------------------------+-------------------------------+-------------------------+ +| React, Vue.js support? | No [2]_ | Yes | ++--------------------------+-------------------------------+-------------------------+ +| Support | Not actively maintained | Actively maintained | ++--------------------------+-------------------------------+-------------------------+ + +.. [1] JavaScript modules allow you to organize your JavaScript into small files + called modules and import them: + + .. code-block:: javascript + + // require third-party modules + var $ = require('jquery'); + + // require your own CoolComponent.js modules + var coolComponent = require('./components/CoolComponent'); + + Encore (via Webpack) parses these automatically and creates a JavaScript + file that contains all needed dependencies. You can even require CSS or + images. + +.. [2] Assetic has outdated support for React.js only. Encore ships with modern + support for React.js, Vue.js, Typescript, etc. + +Should I Upgrade from Assetic to Encore +--------------------------------------- + +If you already have Assetic working in an application, and haven't needed any of +the features that Encore offers over Assetic, continuting to use Assetic is fine. +If you *do* start to need more features, then you might have a business case for +changing to Encore. diff --git a/index.rst b/index.rst index 71fb98c..91b6106 100644 --- a/index.rst +++ b/index.rst @@ -37,7 +37,6 @@ Tópicos .. toctree:: :maxdepth: 1 - assetic bundles console doctrine diff --git a/reference/configuration/assetic.rst b/reference/configuration/assetic.rst index bee91b9..796a776 100644 --- a/reference/configuration/assetic.rst +++ b/reference/configuration/assetic.rst @@ -1,23 +1,26 @@ .. index:: - pair: Assetic; Configuration reference + pair: Assetic; Referência da Configuração Configuração do AsseticBundle ("assetic") -======================================= +========================================= -Configuração Completa Padrão -~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. include:: /assetic/_standard_edition_warning.rst.inc + +Configuração Padrão Completa +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. configuration-block:: .. code-block:: yaml + # app/config/config.yml assetic: - debug: "%kernel.debug%" + debug: '%kernel.debug%' use_controller: - enabled: "%kernel.debug%" + enabled: '%kernel.debug%' profiler: false - read_from: "%kernel.root_dir%/../web" - write_to: "%assetic.read_from%" + read_from: '%assetic.read_from%' + write_to: '%kernel.project_dir%/web' java: /usr/bin/java node: /usr/bin/node ruby: /usr/bin/ruby @@ -48,6 +51,12 @@ Configuração Completa Padrão # An array of named filters (e.g. some_filter, some_other_filter) some_filter: [] + workers: + # see https://github.com/symfony/AsseticBundle/pull/119 + # Cache can also be busted via the framework.assets.version + # setting - see the "framework" configuration section + cache_busting: + enabled: false twig: functions: # An array of named functions (e.g. some_function, some_other_function) @@ -55,49 +64,59 @@ Configuração Completa Padrão .. code-block:: xml - - - FrameworkBundle - SecurityBundle - TwigBundle - MonologBundle - SwiftmailerBundle - DoctrineBundle - AsseticBundle - ... - - - - - - - - - - - - - - + + + + + + + + FrameworkBundle + SecurityBundle + TwigBundle + MonologBundle + SwiftmailerBundle + DoctrineBundle + AsseticBundle + ... - - - - + + + + + + + + + + + + + - - + - - + - + + + + + + + + diff --git a/reference/index.rst b/reference/index.rst index 5c51ed3..dc195ea 100644 --- a/reference/index.rst +++ b/reference/index.rst @@ -4,6 +4,7 @@ Documentos de Referência .. toctree:: :hidden: + configuration/assetic configuration/monolog forms/types diff --git a/templating.rst b/templating.rst index d7010ad..4bf86b6 100644 --- a/templating.rst +++ b/templating.rst @@ -858,7 +858,7 @@ vantagem das heranças de template do Symfony. e asset Javascript em Symfony. Symfony também engloba outra biblioteca, chamada Assetic, que segue essa filosofia mas também permite você fazer mais coisas muito interessantes com esses assets. Para mais informações sobre - usar Assetic veja :doc:`/cookbook/assetic/asset_management`. + usar Assetic veja :doc:`/frontend/assetic/asset_management`. Comece adicionando dois blocos a seu template base que irá abrigar seus assets: uma chamada ``stylesheets`` dentro da tag ``head`` e outra chamada ``javascripts``