Cssurlrewrite Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require fkr/cssurlrewrite-bundle
   

   Or manually via Git submodule/deps (if not using Composer).

2. Enable the Bundle Register in app/AppKernel.php:

   new Fkr\CssURLRewriteBundle\FkrCssURLRewriteBundle(),
   

3. Configure Add minimal config in app/config.yml:

   fkr_css_url_rewrite:
       rewrite_only_if_file_exists: true  # Default: true
       clear_urls: true                    # Default: false
   

4. First Use Case Apply the filter to an Assetic CSS asset in a Twig template:

   {% stylesheets
       'bundles/yourbundle/css/style.css'
       filter='cssurlrewrite'
   %}
       <link rel="stylesheet" href="{{ asset_url }}">
   {% endstylesheets %}
   

Implementation Patterns

Core Workflow

1. Integrate with Assetic Use the cssurlrewrite filter in Twig or PHP:

   {% stylesheets 'path/to/styles.css' filter='cssurlrewrite' %}
   

   Or programmatically:

   $asset = $this->get('assetic.asset_manager')->getAsset('path/to/styles.css');
   $asset->setTargetPath('path/to/output.css');
   $asset->setFilter(new \Fkr\CssURLRewriteBundle\Filter\CssUrlRewriteFilter());
   

2. Dynamic URL Handling

   • Cross-Platform Paths: Fixes paths like ../images/logo.png to absolute URLs (e.g., /bundles/yourbundle/images/logo.png).
   • Environment-Aware: Works seamlessly in dev, test, and prod environments (leverages Symfony’s asset() helper).

3. Chaining Filters Combine with other Assetic filters (e.g., cssrewrite, yui_compressor):

   {% stylesheets 'styles.css' filter='cssurlrewrite,yui_compressor' %}
   

4. Twig Extensions Use the bundle’s Twig extension for direct URL rewriting in templates:

   {{ fkr_css_url_rewrite('relative/path/to/image.png') }}
   

Advanced Patterns

1. Custom Base Paths Override the base path for specific assets via config:

   fkr_css_url_rewrite:
       base_path: /custom/base/path
   

2. Conditional Rewriting Disable rewriting for non-critical assets:

   fkr_css_url_rewrite:
       rewrite_only_if_file_exists: false  # Rewrite even if file doesn’t exist
   

3. Debugging Mode Enable clear_urls: false to preserve original paths for debugging:

   fkr_css_url_rewrite:
       clear_urls: false
   

4. Event Listeners Extend functionality via Symfony events (e.g., post-asset dump):

   // src/Acme/EventListener/CssRewriteListener.php
   class CssRewriteListener
   {
       public function onKernelRequest(GetResponseEvent $event)
       {
           if ($event->isMasterRequest()) {
               // Custom logic here
           }
       }
   }
   

Gotchas and Tips

Pitfalls

1. File Existence Checks

   • If rewrite_only_if_file_exists: true (default), missing files will not be rewritten.
   • Fix: Set to false if you need to rewrite paths regardless of file existence.

2. Circular References

   • Nested @import rules in CSS may cause infinite loops if paths are malformed.
   • Fix: Validate CSS files before processing or use clear_urls: true to reset paths.

3. Assetic Cache Invalidation

   • Changes to CSS files or config require clearing Assetic cache:

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

4. Environment-Specific Paths

   • URLs may break if asset() helper is misconfigured (e.g., wrong public_path).
   • Fix: Verify asset() output matches your expected paths.

Debugging Tips

1. Log Rewritten URLs Enable debug mode in config.yml:

   fkr_css_url_rewrite:
       debug: true  # Logs rewritten paths to Symfony’s log channel
   

2. Inspect Filter Output Dump the filtered content to verify changes:

   $filter = new \Fkr\CssURLRewriteBundle\Filter\CssUrlRewriteFilter();
   $content = $filter->filter($asset->getContent());
   var_dump($content);  // Check rewritten paths
   

3. Test Locally First

   • Use dev environment to test rewrites before deploying to prod.
   • Tip: Override asset() in Twig for testing:

     {{ asset('path/to/file.css', { debug: true }) }}
     

Extension Points

1. Custom URL Strategies Override the default URL generator:

   // src/Fkr/CssURLRewriteBundle/Filter/CustomUrlRewriteFilter.php
   class CustomUrlRewriteFilter extends \Fkr\CssURLRewriteBundle\Filter\CssUrlRewriteFilter
   {
       protected function generateUrl($path)
       {
           return '/custom/' . parent::generateUrl($path);
       }
   }
   

   Register in services.yml:

   services:
       custom.cssurlrewrite.filter:
           class: Fkr\CssURLRewriteBundle\Filter\CustomUrlRewriteFilter
           tags:
               - { name: assetic.filter, alias: custom_cssurlrewrite }
   

2. Pre/Post-Processing Hook into the filter’s filter() method to add logic:

   $content = $this->preProcess($content);
   $content = parent::filter($content);
   $content = $this->postProcess($content);
   return $content;
   

3. Exclude Specific Files Use Assetic’s exclude option in Twig:

   {% stylesheets 'styles.css' filter='cssurlrewrite' exclude='vendor.css' %}