From 9e1ac654fe4fe93bd83bb1ed9eddd57445e91c53 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 11 Feb 2015 12:52:51 +0100 Subject: [PATCH 1/9] Added the documentation for the new Asset component --- components/asset.rst | 249 +++++++++++++++++++++++++++++++++++++++++ components/index.rst | 1 + components/map.rst.inc | 4 + 3 files changed, 254 insertions(+) create mode 100644 components/asset.rst diff --git a/components/asset.rst b/components/asset.rst new file mode 100644 index 00000000000..ba37caa4c4a --- /dev/null +++ b/components/asset.rst @@ -0,0 +1,249 @@ +.. index:: + single: Asset + single: Components; Asset + +The Asset Component +=================== + + The Asset manages URL generation and versioning for web assets such as CSS + stylsheets, JavaScript files and image files. + +Installation +------------ + +You can install the component in two different ways: + +* :doc:`Install it via Composer ` (``symfony/asset`` on `Packagist`_); +* Use the official Git repository (https://github.com/symfony/Asset). + +Usage +----- + +Asset Packages +~~~~~~~~~~~~~~ + +The Asset component manages its assets through packages. A package groups all +the assets which use the same versioning strategy. In the following basic +example, a package is created to manage assets without any versioning: + +.. code-block:: php + + use Symfony\Component\Asset\Package; + use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy; + + $package = new Package(new EmptyVersionStrategy()); + + echo $package->getUrl('/image.png'); + // result: /image.png + +Packages implement the ``PackageInterface``, which defines the following two +methods:: + + namespace Symfony\Component\Asset; + + interface PackageInterface + { + /** + * Returns the asset version for an asset. + */ + public function getVersion($path); + + /** + * Returns an absolute or root-relative public path. + */ + public function getUrl($path); + } + +Versioned Assets +~~~~~~~~~~~~~~~~ + +One of the main features of the Asset component is to manage the versioning of +the application's assets. Asset versions are commonly used to control how these +assets are cached. + +Instead of relying on a simple version mechanism, the Asset component allows to +define advanced version strategies via PHP classes. The two built-in strategies +provided by the component are ``EmptyVersionStrategy``, which doesn't add any +version to the asset, and ``StaticVersionStrategy``, which allows to set the +version with a format string. + +In this example, the ``StaticVersionStrategy`` is used to append the ``v1`` +suffix to any asset path:: + + use Symfony\Component\Asset\Package; + use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy; + + $package = new Package(new StaticVersionStrategy('v1')); + + echo $package->getUrl('/image.png'); + // result: /image.png?v1 + +In case you want to modify the version format, pass a sprintf-compatible format +string as the second argument of the ``StaticVersionStrategy`` constructor:: + + // put the 'version' word before the version value + $package = new Package(new StaticVersionStrategy('v1', '%s?version=%s')); + + echo $package->getUrl('/image.png'); + // result: /image.png?version=v1 + + // put the asset version before its path + $package = new Package(new StaticVersionStrategy('v1', '%2$s/%1$s')); + + echo $package->getUrl('/image.png'); + // result: /v1/image.png + +Custom Version Strategies +......................... + +Use the ``VersionStrategyInterface`` to define your own version strategy. For +example, you could define a versioning where the current date is appended to +bust the cache every day:: + + use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface; + + class DateVersionStrategy implements VersionStrategyInterface + { + private $version; + + public function __construct() + { + $this->version = date('Ymd'); + } + + public function getVersion($path) + { + return $this->version; + } + + public function applyVersion($path) + { + return sprintf('%s?v=%s', $path, $this->getVersion($path)); + } + } + +Grouped Assets +~~~~~~~~~~~~~~ + +It's common for applications to store their assets in a common path. If that's +your case, replace the default ``Package`` class by ``PathPackage`` to avoid +repeating the same path time and again:: + + use Symfony\Component\Asset\PathPackage; + + $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); + + echo $package->getUrl('/logo.png'); + // result: /static/images/logo.png?v1 + +Request Context Aware Assets +............................ + +If you are also using the HttpFoundation component in your project, for example +in a Symfony application, the ``PathPackage`` class can take into account the +context of the current request:: + + use Symfony\Component\Asset\PathPackage; + use Symfony\Component\Asset\Context\RequestStackContext; + + $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); + $package->setContext(new RequestStackContext($requestStack)); + + echo $package->getUrl('/logo.png'); + // result: /somewhere/static/images/logo.png?v1 + +When the request context is set, in addition to the configured base path, +``PathPackage`` also prepends the current request base URL (``/somewhere/`` in +this example) to assets. This allows your website to be hosted anywhere under +the web server root directory. + +Absolute Assets and CDNs +~~~~~~~~~~~~~~~~~~~~~~~~ + +Applications that host their assets on different domains and CDNs (*Content +Delivery Networks*) should use instead the ``UrlPackage`` class to generate +absolute URLs for their assets:: + + use Symfony\Component\Asset\UrlPackage; + + $package = new UrlPackage('http://static.example.com/images/', new StaticVersionStrategy('v1')); + + echo $package->getUrl('/logo.png'); + // result: http://static.example.com/images/logo.png?v1 + +In case you serve assets from more than one domain to improve application +performance, pass an array of URLs as the first argument of ``UrlPackage`` +constructor:: + + use Symfony\Component\Asset\UrlPackage; + + $urls = array( + 'http://static1.example.com/images/', + 'http://static2.example.com/images/', + ); + $package = new UrlPackage($urls, new StaticVersionStrategy('v1')); + + echo $package->getUrl('/logo.png'); + // result: http://static1.example.com/images/logo.png?v1 + +The selection of the domain which will serve the asset is deterministic, meaning +that each asset will be always served by the same domain. This behavior simplifies +the management of HTTP cache. + +Request Context Aware Assets +............................ + +Similarly to application-relative assets, absolute assets can also take into +account the context of the current request. In this case, only the request +scheme is considered, in order to select the appropriate base URL (HTTPs or +protocol-relative URLs for HTTPs requests, any base URL for HTTP requests):: + + use Symfony\Component\Asset\UrlPackage; + use Symfony\Component\Asset\Context\RequestStackContext; + + $package = new UrlPackage(array('http://example.com/', 'https://example.com/'), new StaticVersionStrategy('v1')); + $package->setContext(new RequestStackContext($requestStack)); + + echo $package->getUrl('/logo.png'); + // result: https://example.com/logo.png?v1 + +Named Packages +~~~~~~~~~~~~~~ + +Applications that manage lots of different assets may need to group them in +packages with the same versioning strategy and base path. The Asset component +includes a ``Packages`` class to simplify the management of several packages. + +In the following example, all packages use the same versioning strategy, but +they all have different base paths:: + + use Symfony\Component\Asset\Package; + use Symfony\Component\Asset\PathPackage; + use Symfony\Component\Asset\UrlPackage; + use Symfony\Component\Asset\Packages; + + $versionStrategy = new StaticVersionStrategy('v1'); + + $defaultPackage = new Package($versionStrategy); + + $namedPackages = array( + 'img' => new UrlPackage('http://img.example.com/', $versionStrategy), + 'doc' => new PathPackage('/somewhere/deep/for/documents', $versionStrategy), + ); + + $packages = new Packages($defaultPackage, $namedPackages) + +The ``Packages`` class requires to define a default package which will be applied +to all assets except those which indicate the name of the package to use. In +addition, this application defines a package named ``img`` to serve images from +an external domain and a ``doc`` package to avoid repeating long paths when +linking to a document inside a template:: + + echo $packages->getUrl('/main.css'); + // result: /main.css?v1 + + echo $packages->getUrl('/logo.png', 'img'); + // result: http://img.example.com/logo.png?v1 + + echo $packages->getUrl('/resume.pdf', 'doc'); + // result: /somewhere/deep/for/documents/resume.pdf?v1 diff --git a/components/index.rst b/components/index.rst index d16b78de06f..9e0acc26da3 100644 --- a/components/index.rst +++ b/components/index.rst @@ -5,6 +5,7 @@ The Components :hidden: using_components + asset class_loader/index config/index console/index diff --git a/components/map.rst.inc b/components/map.rst.inc index 7b6ceae5db2..d8921083591 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -1,5 +1,9 @@ * :doc:`/components/using_components` +* **Asset** + + * :doc:`/components/asset` + * :doc:`/components/class_loader/index` * :doc:`/components/class_loader/introduction` From bc3403a4be0707c87e38c4051a1a3a98b06bdb1d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 11 Feb 2015 17:26:00 +0100 Subject: [PATCH 2/9] Minor rewording --- components/asset.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/asset.rst b/components/asset.rst index ba37caa4c4a..09bfc4c6b6b 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -5,8 +5,8 @@ The Asset Component =================== - The Asset manages URL generation and versioning for web assets such as CSS - stylsheets, JavaScript files and image files. + The Asset component manages URL generation and versioning of web assets such + as CSS stylsheets, JavaScript files and image files. Installation ------------ @@ -62,7 +62,7 @@ the application's assets. Asset versions are commonly used to control how these assets are cached. Instead of relying on a simple version mechanism, the Asset component allows to -define advanced version strategies via PHP classes. The two built-in strategies +define advanced versioning strategies via PHP classes. The two built-in strategies provided by the component are ``EmptyVersionStrategy``, which doesn't add any version to the asset, and ``StaticVersionStrategy``, which allows to set the version with a format string. From e6e2ba46badafc50828615aa6e74edb7c2b7f471 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 12 Feb 2015 11:59:33 +0100 Subject: [PATCH 3/9] Added a missing link reference --- components/asset.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/components/asset.rst b/components/asset.rst index 09bfc4c6b6b..0f8fe4e5a35 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -247,3 +247,5 @@ linking to a document inside a template:: echo $packages->getUrl('/resume.pdf', 'doc'); // result: /somewhere/deep/for/documents/resume.pdf?v1 + +.. _Packagist: https://packagist.org/packages/symfony/asset From 7312638c0a1e9e98ed6857928f9d5a2d66b2183d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 15 Feb 2015 13:25:56 +0100 Subject: [PATCH 4/9] Tweaked documentation and added links to API methods/classes --- components/asset.rst | 96 +++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 46 deletions(-) diff --git a/components/asset.rst b/components/asset.rst index 0f8fe4e5a35..2b5389d0fd6 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -24,9 +24,7 @@ Asset Packages The Asset component manages its assets through packages. A package groups all the assets which use the same versioning strategy. In the following basic -example, a package is created to manage assets without any versioning: - -.. code-block:: php +example, a package is created to manage assets without any versioning:: use Symfony\Component\Asset\Package; use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy; @@ -36,23 +34,14 @@ example, a package is created to manage assets without any versioning: echo $package->getUrl('/image.png'); // result: /image.png -Packages implement the ``PackageInterface``, which defines the following two -methods:: +Packages implement the :class:`Symfony\\Component\\Asset\\PackageInterface`, +which defines the following two methods:: - namespace Symfony\Component\Asset; +:method:`Symfony\\Component\\Asset\\PackageInterface::getVersion` + Returns the asset version for an asset. - interface PackageInterface - { - /** - * Returns the asset version for an asset. - */ - public function getVersion($path); - - /** - * Returns an absolute or root-relative public path. - */ - public function getUrl($path); - } +:method:`Symfony\\Component\\Asset\\PackageInterface::getUrl` + Returns an absolute or root-relative public path. Versioned Assets ~~~~~~~~~~~~~~~~ @@ -63,12 +52,12 @@ assets are cached. Instead of relying on a simple version mechanism, the Asset component allows to define advanced versioning strategies via PHP classes. The two built-in strategies -provided by the component are ``EmptyVersionStrategy``, which doesn't add any -version to the asset, and ``StaticVersionStrategy``, which allows to set the -version with a format string. +provided by the component are :class:`Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy`, +which doesn't add any version to the asset and :class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy`, +which allows to set the version with a format string. -In this example, the ``StaticVersionStrategy`` is used to append the ``v1`` -suffix to any asset path:: +In this example, the :class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy` +is used to append the ``v1`` suffix to any asset path:: use Symfony\Component\Asset\Package; use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy; @@ -79,7 +68,8 @@ suffix to any asset path:: // result: /image.png?v1 In case you want to modify the version format, pass a sprintf-compatible format -string as the second argument of the ``StaticVersionStrategy`` constructor:: +string as the second argument of the +:class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy` constructor:: // put the 'version' word before the version value $package = new Package(new StaticVersionStrategy('v1', '%s?version=%s')); @@ -96,9 +86,9 @@ string as the second argument of the ``StaticVersionStrategy`` constructor:: Custom Version Strategies ......................... -Use the ``VersionStrategyInterface`` to define your own version strategy. For -example, you could define a versioning where the current date is appended to -bust the cache every day:: +Use the :class:`Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface` +to define your own version strategy. For example, you could define a versioning +where the current date is appended to bust the cache every day:: use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface; @@ -126,10 +116,12 @@ Grouped Assets ~~~~~~~~~~~~~~ It's common for applications to store their assets in a common path. If that's -your case, replace the default ``Package`` class by ``PathPackage`` to avoid -repeating the same path time and again:: +your case, replace the default :class:`Symfony\Component\Asset\Package` class by +:class:`Symfony\Component\Asset\PathPackage` to avoid repeating the same path +time and again:: use Symfony\Component\Asset\PathPackage; + // ... $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); @@ -140,11 +132,12 @@ Request Context Aware Assets ............................ If you are also using the HttpFoundation component in your project, for example -in a Symfony application, the ``PathPackage`` class can take into account the -context of the current request:: +in a Symfony application, the :class:`Symfony\Component\Asset\PathPackage` class +can take into account the context of the current request:: use Symfony\Component\Asset\PathPackage; use Symfony\Component\Asset\Context\RequestStackContext; + // ... $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); $package->setContext(new RequestStackContext($requestStack)); @@ -153,29 +146,34 @@ context of the current request:: // result: /somewhere/static/images/logo.png?v1 When the request context is set, in addition to the configured base path, -``PathPackage`` also prepends the current request base URL (``/somewhere/`` in -this example) to assets. This allows your website to be hosted anywhere under -the web server root directory. +:class:`Symfony\Component\Asset\PathPackage` also prepends the current request +base URL (``/somewhere/`` in this example) to assets. This allows your website +to be hosted anywhere under the web server root directory. Absolute Assets and CDNs ~~~~~~~~~~~~~~~~~~~~~~~~ Applications that host their assets on different domains and CDNs (*Content -Delivery Networks*) should use instead the ``UrlPackage`` class to generate -absolute URLs for their assets:: +Delivery Networks*) should use the :class:`Symfony\Component\Asset\UrlPackage` +class to generate absolute URLs for their assets:: use Symfony\Component\Asset\UrlPackage; + // ... - $package = new UrlPackage('http://static.example.com/images/', new StaticVersionStrategy('v1')); + $package = new UrlPackage( + 'http://static.example.com/images/', + new StaticVersionStrategy('v1') + ); echo $package->getUrl('/logo.png'); // result: http://static.example.com/images/logo.png?v1 In case you serve assets from more than one domain to improve application -performance, pass an array of URLs as the first argument of ``UrlPackage`` -constructor:: +performance, pass an array of URLs as the first argument of +:class:`Symfony\Component\Asset\UrlPackage` constructor:: use Symfony\Component\Asset\UrlPackage; + // ... $urls = array( 'http://static1.example.com/images/', @@ -200,8 +198,12 @@ protocol-relative URLs for HTTPs requests, any base URL for HTTP requests):: use Symfony\Component\Asset\UrlPackage; use Symfony\Component\Asset\Context\RequestStackContext; + // ... - $package = new UrlPackage(array('http://example.com/', 'https://example.com/'), new StaticVersionStrategy('v1')); + $package = new UrlPackage( + array('http://example.com/', 'https://example.com/'), + new StaticVersionStrategy('v1') + ); $package->setContext(new RequestStackContext($requestStack)); echo $package->getUrl('/logo.png'); @@ -212,7 +214,8 @@ Named Packages Applications that manage lots of different assets may need to group them in packages with the same versioning strategy and base path. The Asset component -includes a ``Packages`` class to simplify the management of several packages. +includes a :class:`Symfony\Component\Asset\Packages` class to simplify the +management of several packages. In the following example, all packages use the same versioning strategy, but they all have different base paths:: @@ -221,6 +224,7 @@ they all have different base paths:: use Symfony\Component\Asset\PathPackage; use Symfony\Component\Asset\UrlPackage; use Symfony\Component\Asset\Packages; + // ... $versionStrategy = new StaticVersionStrategy('v1'); @@ -233,11 +237,11 @@ they all have different base paths:: $packages = new Packages($defaultPackage, $namedPackages) -The ``Packages`` class requires to define a default package which will be applied -to all assets except those which indicate the name of the package to use. In -addition, this application defines a package named ``img`` to serve images from -an external domain and a ``doc`` package to avoid repeating long paths when -linking to a document inside a template:: +The :class:`Symfony\Component\Asset\Packages` class requires to define a default +package which will be applied to all assets except those which indicate the name +of the package to use. In addition, this application defines a package named +``img`` to serve images from an external domain and a ``doc`` package to avoid +repeating long paths when linking to a document inside a template:: echo $packages->getUrl('/main.css'); // result: /main.css?v1 From ac58089ccd4e3a15b7657b9fc5ad7188add27cc4 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Feb 2015 11:23:17 +0100 Subject: [PATCH 5/9] Fixed a lot of errors and added an introduction --- components/asset.rst | 68 +++++++++++++++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 17 deletions(-) diff --git a/components/asset.rst b/components/asset.rst index 2b5389d0fd6..7ef34d1d276 100644 --- a/components/asset.rst +++ b/components/asset.rst @@ -6,7 +6,37 @@ The Asset Component =================== The Asset component manages URL generation and versioning of web assets such - as CSS stylsheets, JavaScript files and image files. + as CSS stylesheets, JavaScript files and image files. + +In the past, it was common for web applications to hardcode the URLs of the web +assets. For example: + +.. code-block:: html + + + + + + + +This practice is no longer recommended unless the web application is extremely +simple. The main problems of hardcoding asset URLs are the following: + +* **Templates get verbose** because you have to write the full path for each + asset. When using the Asset component, you can group assets in packages to + avoid repeating the common part of their path. +* **Versioning is difficult** because it has to be custom managed for each + application. Adding a version to the asset URLs is essential for some applications + because it allows to control how the assets are cached. The Asset component + allows to define different versioning strategies for each package. +* **Moving assets location** is cumbersome and error-prone, because it requires + you to carefully update the URLs of all assets included in all templates. + The Asset component allows to move assets effortlessly just by changing the + base path value associated with the package of assets. +* **Impossible to use multiple CDNs** because it requires to change the URL of + the asset randomly for each request. The Asset component provides out-of-the-box + support for any number of multiple CDNs, both regular (``http://``) and + secure (``https://``). Installation ------------ @@ -22,9 +52,10 @@ Usage Asset Packages ~~~~~~~~~~~~~~ -The Asset component manages its assets through packages. A package groups all -the assets which use the same versioning strategy. In the following basic -example, a package is created to manage assets without any versioning:: +The Asset component manages assets through packages. A package groups all the +assets which share the same properties: versioning strategy, base path, CDN hosts, +etc. In the following basic example, a package is created to manage assets without +any versioning:: use Symfony\Component\Asset\Package; use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy; @@ -139,16 +170,19 @@ can take into account the context of the current request:: use Symfony\Component\Asset\Context\RequestStackContext; // ... - $package = new PathPackage('/static/images', new StaticVersionStrategy('v1')); - $package->setContext(new RequestStackContext($requestStack)); + $package = new PathPackage( + '/static/images', + new StaticVersionStrategy('v1'), + new RequestStackContext($requestStack) + ); echo $package->getUrl('/logo.png'); // result: /somewhere/static/images/logo.png?v1 -When the request context is set, in addition to the configured base path, -:class:`Symfony\Component\Asset\PathPackage` also prepends the current request -base URL (``/somewhere/`` in this example) to assets. This allows your website -to be hosted anywhere under the web server root directory. +When the request context is set (via the third optional argument), in addition +to the configured base path, :class:`Symfony\Component\Asset\PathPackage` also +prepends the current request base URL (``/somewhere/`` in this example) to assets. +This allows your website to be hosted anywhere under the web server root directory. Absolute Assets and CDNs ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -202,9 +236,9 @@ protocol-relative URLs for HTTPs requests, any base URL for HTTP requests):: $package = new UrlPackage( array('http://example.com/', 'https://example.com/'), - new StaticVersionStrategy('v1') + new StaticVersionStrategy('v1'), + new RequestStackContext($requestStack) ); - $package->setContext(new RequestStackContext($requestStack)); echo $package->getUrl('/logo.png'); // result: https://example.com/logo.png?v1 @@ -237,11 +271,11 @@ they all have different base paths:: $packages = new Packages($defaultPackage, $namedPackages) -The :class:`Symfony\Component\Asset\Packages` class requires to define a default -package which will be applied to all assets except those which indicate the name -of the package to use. In addition, this application defines a package named -``img`` to serve images from an external domain and a ``doc`` package to avoid -repeating long paths when linking to a document inside a template:: +The :class:`Symfony\Component\Asset\Packages` class allows to define a default +package, which will be applied to assets that don't define the name of package +to use. In addition, this application defines a package named ``img`` to serve +images from an external domain and a ``doc`` package to avoid repeating long +paths when linking to a document inside a template:: echo $packages->getUrl('/main.css'); // result: /main.css?v1 From 9c456e38465b96d8bed5cd7f6f5f36c6c09ff140 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Feb 2015 11:28:32 +0100 Subject: [PATCH 6/9] Moved the component documentation to its own folder --- components/asset/index.rst | 7 +++++++ components/{asset.rst => asset/introduction.rst} | 0 components/map.rst.inc | 4 ++-- 3 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 components/asset/index.rst rename components/{asset.rst => asset/introduction.rst} (100%) diff --git a/components/asset/index.rst b/components/asset/index.rst new file mode 100644 index 00000000000..14d04b7eb6f --- /dev/null +++ b/components/asset/index.rst @@ -0,0 +1,7 @@ +Asset +===== + +.. toctree:: + :maxdepth: 2 + + introduction diff --git a/components/asset.rst b/components/asset/introduction.rst similarity index 100% rename from components/asset.rst rename to components/asset/introduction.rst diff --git a/components/map.rst.inc b/components/map.rst.inc index d8921083591..009284614ce 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -1,8 +1,8 @@ * :doc:`/components/using_components` -* **Asset** +* :doc:`/components/asset/index` - * :doc:`/components/asset` + * :doc:`/components/asset/introduction` * :doc:`/components/class_loader/index` From 3c8324341689e43ab39ae8892f035deb06dd7d12 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Feb 2015 19:20:20 +0100 Subject: [PATCH 7/9] Fixed some RST syntax issues --- components/asset/introduction.rst | 2 +- components/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/components/asset/introduction.rst b/components/asset/introduction.rst index 7ef34d1d276..645793527bb 100644 --- a/components/asset/introduction.rst +++ b/components/asset/introduction.rst @@ -66,7 +66,7 @@ any versioning:: // result: /image.png Packages implement the :class:`Symfony\\Component\\Asset\\PackageInterface`, -which defines the following two methods:: +which defines the following two methods: :method:`Symfony\\Component\\Asset\\PackageInterface::getVersion` Returns the asset version for an asset. diff --git a/components/index.rst b/components/index.rst index 9e0acc26da3..41f72d049a4 100644 --- a/components/index.rst +++ b/components/index.rst @@ -5,7 +5,7 @@ The Components :hidden: using_components - asset + asset/index class_loader/index config/index console/index From 6f7a63ed3b3c51ec5df422329651bdb7b61b8a95 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Feb 2015 17:23:14 +0100 Subject: [PATCH 8/9] Fixed RST syntax issues --- components/asset/introduction.rst | 47 +++++++++++++++---------------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/components/asset/introduction.rst b/components/asset/introduction.rst index 645793527bb..70b6d0e400c 100644 --- a/components/asset/introduction.rst +++ b/components/asset/introduction.rst @@ -83,12 +83,12 @@ assets are cached. Instead of relying on a simple version mechanism, the Asset component allows to define advanced versioning strategies via PHP classes. The two built-in strategies -provided by the component are :class:`Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy`, -which doesn't add any version to the asset and :class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy`, +provided by the component are :class:`Symfony\\Component\\Asset\\VersionStrategy\\EmptyVersionStrategy`, +which doesn't add any version to the asset and :class:`Symfony\\Component\\Asset\\VersionStrategy\\StaticVersionStrategy`, which allows to set the version with a format string. -In this example, the :class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy` -is used to append the ``v1`` suffix to any asset path:: +In this example, the ``StaticVersionStrategy`` is used to append the ``v1`` +suffix to any asset path:: use Symfony\Component\Asset\Package; use Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy; @@ -99,8 +99,7 @@ is used to append the ``v1`` suffix to any asset path:: // result: /image.png?v1 In case you want to modify the version format, pass a sprintf-compatible format -string as the second argument of the -:class:`Symfony\Component\Asset\VersionStrategy\StaticVersionStrategy` constructor:: +string as the second argument of the ``StaticVersionStrategy`` constructor:: // put the 'version' word before the version value $package = new Package(new StaticVersionStrategy('v1', '%s?version=%s')); @@ -117,7 +116,7 @@ string as the second argument of the Custom Version Strategies ......................... -Use the :class:`Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface` +Use the :class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface` to define your own version strategy. For example, you could define a versioning where the current date is appended to bust the cache every day:: @@ -147,9 +146,9 @@ Grouped Assets ~~~~~~~~~~~~~~ It's common for applications to store their assets in a common path. If that's -your case, replace the default :class:`Symfony\Component\Asset\Package` class by -:class:`Symfony\Component\Asset\PathPackage` to avoid repeating the same path -time and again:: +your case, replace the default :class:`Symfony\\Component\\Asset\\Package` class +by :class:`Symfony\\Component\\Asset\\PathPackage` to avoid repeating the same +path time and again:: use Symfony\Component\Asset\PathPackage; // ... @@ -163,8 +162,8 @@ Request Context Aware Assets ............................ If you are also using the HttpFoundation component in your project, for example -in a Symfony application, the :class:`Symfony\Component\Asset\PathPackage` class -can take into account the context of the current request:: +in a Symfony application, the ``PathPackage`` class can take into account the +context of the current request:: use Symfony\Component\Asset\PathPackage; use Symfony\Component\Asset\Context\RequestStackContext; @@ -180,15 +179,15 @@ can take into account the context of the current request:: // result: /somewhere/static/images/logo.png?v1 When the request context is set (via the third optional argument), in addition -to the configured base path, :class:`Symfony\Component\Asset\PathPackage` also -prepends the current request base URL (``/somewhere/`` in this example) to assets. -This allows your website to be hosted anywhere under the web server root directory. +to the configured base path, ``PathPackage`` also prepends the current request +base URL (``/somewhere/`` in this example) to assets. This allows your website +to be hosted anywhere under the web server root directory. Absolute Assets and CDNs ~~~~~~~~~~~~~~~~~~~~~~~~ Applications that host their assets on different domains and CDNs (*Content -Delivery Networks*) should use the :class:`Symfony\Component\Asset\UrlPackage` +Delivery Networks*) should use the :class:`Symfony\\Component\\Asset\\UrlPackage` class to generate absolute URLs for their assets:: use Symfony\Component\Asset\UrlPackage; @@ -203,8 +202,8 @@ class to generate absolute URLs for their assets:: // result: http://static.example.com/images/logo.png?v1 In case you serve assets from more than one domain to improve application -performance, pass an array of URLs as the first argument of -:class:`Symfony\Component\Asset\UrlPackage` constructor:: +performance, pass an array of URLs as the first argument of ``UrlPackage`` +constructor:: use Symfony\Component\Asset\UrlPackage; // ... @@ -248,7 +247,7 @@ Named Packages Applications that manage lots of different assets may need to group them in packages with the same versioning strategy and base path. The Asset component -includes a :class:`Symfony\Component\Asset\Packages` class to simplify the +includes a :class:`Symfony\\Component\\Asset\\Packages` class to simplify the management of several packages. In the following example, all packages use the same versioning strategy, but @@ -271,11 +270,11 @@ they all have different base paths:: $packages = new Packages($defaultPackage, $namedPackages) -The :class:`Symfony\Component\Asset\Packages` class allows to define a default -package, which will be applied to assets that don't define the name of package -to use. In addition, this application defines a package named ``img`` to serve -images from an external domain and a ``doc`` package to avoid repeating long -paths when linking to a document inside a template:: +The ``Packages`` class allows to define a default package, which will be applied +to assets that don't define the name of package to use. In addition, this +application defines a package named ``img`` to serve images from an external +domain and a ``doc`` package to avoid repeating long paths when linking to a +document inside a template:: echo $packages->getUrl('/main.css'); // result: /main.css?v1 From 6c2b2eefeda5d7e4a8d77f5b57497d5c56091522 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 20 Feb 2015 08:53:45 +0100 Subject: [PATCH 9/9] Lots of fixes and rewordings --- components/asset/introduction.rst | 45 ++++++++++++++++--------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/components/asset/introduction.rst b/components/asset/introduction.rst index 70b6d0e400c..eb2d1d22ba2 100644 --- a/components/asset/introduction.rst +++ b/components/asset/introduction.rst @@ -8,8 +8,8 @@ The Asset Component The Asset component manages URL generation and versioning of web assets such as CSS stylesheets, JavaScript files and image files. -In the past, it was common for web applications to hardcode the URLs of the web -assets. For example: +In the past, it was common for web applications to hardcode URLs of web assets. +For example: .. code-block:: html @@ -20,23 +20,23 @@ assets. For example: This practice is no longer recommended unless the web application is extremely -simple. The main problems of hardcoding asset URLs are the following: +simple. Hardcoding URLs can be a disadvantage because: -* **Templates get verbose** because you have to write the full path for each +* **Templates get verbose**: you have to write the full path for each asset. When using the Asset component, you can group assets in packages to - avoid repeating the common part of their path. -* **Versioning is difficult** because it has to be custom managed for each + avoid repeating the common part of their path; +* **Versioning is difficult**: it has to be custom managed for each application. Adding a version to the asset URLs is essential for some applications because it allows to control how the assets are cached. The Asset component - allows to define different versioning strategies for each package. -* **Moving assets location** is cumbersome and error-prone, because it requires - you to carefully update the URLs of all assets included in all templates. - The Asset component allows to move assets effortlessly just by changing the - base path value associated with the package of assets. -* **Impossible to use multiple CDNs** because it requires to change the URL of - the asset randomly for each request. The Asset component provides out-of-the-box - support for any number of multiple CDNs, both regular (``http://``) and - secure (``https://``). + allows to define different versioning strategies for each package; +* **Moving assets location** is cumbersome and error-prone: it requires you to + carefully update the URLs of all assets included in all templates. The Asset + component allows to move assets effortlessly just by changing the base path + value associated with the package of assets; +* **It's nearly impossible to use multiple CDNs**: this technique requires to + change the URL of the asset randomly for each request. The Asset component + provides out-of-the-box support for any number of multiple CDNs, both regular + (``http://``) and secure (``https://``). Installation ------------ @@ -117,8 +117,9 @@ Custom Version Strategies ......................... Use the :class:`Symfony\\Component\\Asset\\VersionStrategy\\VersionStrategyInterface` -to define your own version strategy. For example, you could define a versioning -where the current date is appended to bust the cache every day:: +to define your own versioning strategy. For example, your application may need +to append the current date to all its web assets in order to bust the cache +every day:: use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface; @@ -178,10 +179,10 @@ context of the current request:: echo $package->getUrl('/logo.png'); // result: /somewhere/static/images/logo.png?v1 -When the request context is set (via the third optional argument), in addition -to the configured base path, ``PathPackage`` also prepends the current request -base URL (``/somewhere/`` in this example) to assets. This allows your website -to be hosted anywhere under the web server root directory. +When the request context is set (via an optional third argument), in addition to +the configured base path, ``PathPackage`` also prepends the current request base +URL (``/somewhere/`` in this example) to assets. This allows your website to be +hosted anywhere under the web server root directory. Absolute Assets and CDNs ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -247,7 +248,7 @@ Named Packages Applications that manage lots of different assets may need to group them in packages with the same versioning strategy and base path. The Asset component -includes a :class:`Symfony\\Component\\Asset\\Packages` class to simplify the +includes a :class:`Symfony\\Component\\Asset\\Packages` class to simplify management of several packages. In the following example, all packages use the same versioning strategy, but