nitronet / fwk-assetic
Requires
- php: >=5.3.0
- fwk/core: dev-master
- kriswallsmith/assetic: dev-master
This package is not auto-updated.
Last update: 2024-10-26 15:20:23 UTC
README
Adds Assetic to Fwk\Core Applications.
Installation
1: Install the sources
Via Composer:
{
"require": {
"nitronet/fwk-assetic": "dev-master",
}
}
If you don't use Composer, you can still download this repository and add it
to your include_path
PSR-0 compatible
2: Configure Assetic as a Service
Configures Assetic classes in your Di Container, and tweak it the way you want. To make it customizable, we'll also use some INI properties:
[services] ; :packageDir is the directory where your service.xml is. assetic.assets.directory = :packageDir/MyApp/templates/assets assetic.debug = true assetic.action.name = Asset
services.xml:
<!-- Assetic AssetFactory --> <class-definition name="assetic.AssetFactory" class="Assetic\Factory\AssetFactory" shared="true"> <argument>:assetic.assets.directory</argument> <argument>:assetic.debug</argument> <call method="setFilterManager"> <argument>@assetic.FilterManager</argument> </call> </class-definition> <!-- Assetic FilterManager --> <class-definition name="assetic.FilterManager" class="Assetic\FilterManager" shared="true" /> <!-- Fwk Service --> <class-definition name="assetic" class="FwkAssetic\AssetsService" shared="true"> <argument>@assetic.AssetFactory</argument> </class-definition> <!-- Fwk ViewHelper --> <class-definition name="_vh.AsseticViewHelper" class="FwkAssetic\AssetViewHelper" shared="true"> <argument desc="Name of the Fwk Service">assetic</argument> <argument desc="Name of your Url ViewHelper">url</argument> <argument desc="Enable Assetic debugging">:assetic.debug</argument> <argument desc="Asset action name">:assetic.action.name</argument> </class-definition>
Next, you want to add the ViewHelper to your ViewHelperService:
<!-- You probably already have this one --> <class-definition name="viewHelper" class="Fwk\Core\Components\ViewHelper\ViewHelperService" shared="true"> <!-- ... --> <call method="add"> <argument desc="Name of the helper (to be used in templates)">asset</argument> <argument desc="Instance of the AsseticViewHelper">@_vh.AsseticViewHelper</argument> </call> </class-definition>
3: Register action and routes to the Asset Action
fwk.xml:
<action name="Asset" shortcut="FwkAssetic\Controllers\AssetAction:show" />
If you use the UrlRewriterService, you can also customize the action route:
<url-rewrite> <!-- ... ---> <url route="/asset/:asset" action="Asset"> <param name="asset" regex=".*" /> </url> </url-rewrite>
4: That's it!
You can now use the viewHelper in your templates, like so:
<?php foreach($this->_helper->asset(array('/path/to/site.css'), $filters = array(), $output = "site") as $asset): ?> <link href="<?php echo $asset; ?>" media="all" rel="stylesheet" type="text/css" /> <?php endforeach; ?>
Or if you use Twig:
{% for asset in _helper.asset(['/path/to/site.css'], [], 'site', true) %} <link href="{{ asset }}" media="all" rel="stylesheet" type="text/css" /> {% endfor %}
CssRewrite
To display images and resources referenced in your CSS, you'll have to use a "rewrite" filter.
Back to your services.xml, declare the filter definition and change your assetic.FilterManager
definition to this:
<!-- Assetic FilterManager --> <class-definition name="assetic.FilterManager" class="Assetic\FilterManager" shared="true"> <call method="set"> <argument desc="Filter alias">cssrewrite</argument> <argument desc="Filter instance">@assetic.CssRewriteFilter</argument> </call> </class-definition> <!-- CssRewriteFilter --> <class-definition name="assetic.CssRewriteFilter" class="FwkAssetic\Filters\CssRewriteFilter" shared="true"> <argument>@_vh.AsseticViewHelper</argument> </class-definition>
Now, just call the cssrewrite filter in your templates:
<?php foreach($this->_helper->asset('/path/to/site.css', 'cssrewrite') as $asset): ?> <link href="<?php echo $asset; ?>" media="all" rel="stylesheet" type="text/css" /> <?php endforeach; ?>
That's it!
Configure Caching
To prevent 404 errors on assets urls, you'll have to use the Assetic caching mechanism, which require some more configuration...
1: Configuration variables and caching directory
Create a directory where Assetic can cache the assets:
$ mkdir /path/to/app/cache $ chmod 777 /path/to/app/cache
Configure the application:
assetic.use.cache = true assetic.cache.directory = /path/to/app/cache ; could be content or modification assetic.cache.strategy = content
2: Configure Services
Adds the following definitions to your services.xml
<!-- Assetic FilesystemCache --> <class-definition name="assetic.FilesystemCache" class="Assetic\Cache\FilesystemCache" shared="true"> <argument>:assetic.cache.directory</argument> </class-definition> <!-- Assetic CacheBustingWorker --> <class-definition name="assetic.CacheBustingWorker" class="Assetic\Factory\Worker\CacheBustingWorker" shared="true"> <argument>:assetic.cache.strategy</argument> </class-definition>
And reconfigure previous definitions:
<!-- Assetic AssetFactory --> <class-definition name="assetic.AssetFactory" class="Assetic\Factory\AssetFactory" shared="true"> <argument>:assetic.assets.directory</argument> <argument>:assetic.debug</argument> <call method="setFilterManager"> <argument>@assetic.FilterManager</argument> </call> <!-- enable assetic cache --> <call method="addWorker"> <argument>@assetic.CacheBustingWorker</argument> </call> </class-definition> <!-- Fwk Service --> <class-definition name="assetic" class="FwkAssetic\AssetsService" shared="true"> <argument>@assetic.AssetFactory</argument> <!-- enable assetic cache --> <argument>@assetic.FilesystemCache</argument> </class-definition>
3: You're done!
Now you can refresh your pages and admire your frontend skills ;)
Shortcuts to Assets
Sometimes it can be useful to define shortcuts to assets directories if they are not in your :assetic.assets.directory
.
1: Create an array of shortcuts
<!-- Assets shortcuts --> <array-definition name="assetic.Shortcuts"> <param key="bower">:packageDir/../public/bower_components</param> <param key="theme">:packageDir/templates/assets</param> </array-definition>
2: Add a method call to your AssetsService
<!-- Assets Service --> <class-definition name="assetic" class="FwkAssetic\AssetsService" shared="true"> <argument>@assetic.AssetFactory</argument> <argument>@assetic.FilesystemCache</argument> <!-- add shortcuts --> <call method="addShortcuts"> <argument>@assetic.Shortcuts</argument> </call> </class-definition>
3: Use your shortcuts
Now that shortcuts have been defined, we can call our assets easily:
<?php foreach($this->_helper->asset(array('+bower/bootstrap/css/bootstrap.css')) as $asset): ?> <link href="<?php echo $asset; ?>" media="all" rel="stylesheet" type="text/css" /> <?php endforeach; ?>
Full XML configuration
<!-- ASSETIC (fwk-assetic) --> <class-definition name="assetic.CssRewriteFilter" class="FwkAssetic\Filters\CssRewriteFilter" shared="true"> <argument>@_vh.AsseticViewHelper</argument> </class-definition> <class-definition name="assetic.FilterManager" class="Assetic\FilterManager" shared="true"> <call method="set"> <argument>cssrewrite</argument> <argument>@assetic.CssRewriteFilter</argument> </call> </class-definition> <class-definition name="assetic.FilesystemCache" class="Assetic\Cache\FilesystemCache" shared="true"> <argument>:assetic.cache.directory</argument> </class-definition> <class-definition name="assetic.CacheBustingWorker" class="Assetic\Factory\Worker\CacheBustingWorker" shared="true"> <argument>:assetic.cache.strategy</argument> </class-definition> <class-definition name="assetic.AssetFactory" class="Assetic\Factory\AssetFactory" shared="true"> <argument>:assetic.assets.directory</argument> <argument>:assetic.debug</argument> <call method="setFilterManager"> <argument>@assetic.FilterManager</argument> </call> <!-- enable assetic cache --> <call method="addWorker"> <argument>@assetic.CacheBustingWorker</argument> </call> </class-definition> <!-- Assets Service --> <class-definition name="assetic" class="FwkAssetic\AssetsService" shared="true"> <argument>@assetic.AssetFactory</argument> <argument>@assetic.FilesystemCache</argument> <!-- add shortcuts --> <call method="addShortcuts"> <argument>@assetic.Shortcuts</argument> </call> </class-definition> <class-definition name="_vh.AsseticViewHelper" class="\FwkAssetic\AssetViewHelper" shared="true"> <argument>assetic</argument> <argument>url</argument> <argument>:assetic.debug</argument> <argument>:assetic.action.name</argument> </class-definition> <!-- Assets shortcuts --> <array-definition name="assetic.Shortcuts"> <param key="bower">:packageDir/../public/bower_components</param> <param key="theme">:packageDir/templates/assets</param> </array-definition>
Contributions / Community
- Issues on Github: https://github.com/nitronet/fwk-assetic/issues
- Follow Fwk on Twitter: @phpfwk