Cssurlrewrite Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation: Add the bundle via Composer:

   composer require fkr/cssurlrewrite-bundle
   

   Register the bundle in AppKernel.php:

   new Fkr\CssURLRewriteBundle\FkrCssURLRewriteBundle(),
   

2. Configuration: Add minimal config to app/config.yml:

   fkr_css_url_rewrite:
       rewrite_only_if_file_exists: true
       clear_urls: true
   

3. First Use Case: Place a CSS file in BundleName/Resources/public/css/ with relative paths (e.g., background-image: url(../img/logo.png)). Use the filter in Twig:

   {% stylesheets filter='css_url_rewrite'
       '@BundleName/Resources/public/css/style.css'
   %}
       <link rel="stylesheet" href="{{ asset_url }}">
   {% endstylesheets %}
   

   Run php app/console assets:install to generate symlinks and test.

Implementation Patterns

Usage Patterns

1. Standard CSS Path Resolution:

   • Use relative paths in CSS (e.g., ../img/logo.png) and let the filter resolve them to absolute paths like /bundles/bundlename/css/../img/logo.png.
   • Example:

     /* Input */
     background-image: url(../img/logo.png);
     
     /* Output (after filter) */
     background-image: url(../bundles/bundlename/css/../img/logo.png);
     

2. Cross-Bundle Asset References:

   • Reference assets from other bundles using @BundleName notation:

     /* Input */
     background-image: url(@AcmeMediaBundle/img/logo.png);
     
     /* Output */
     background-image: url(../bundles/acmemediabundle/img/logo.png);
     

3. Path Normalization:

   • Enable clear_urls: true to simplify complex paths (e.g., ../less/../img → ../img).

4. Base64 Support:

   • The filter handles base64-encoded images in CSS (added in v1.0.4):

     background-image: url('data:image/png;base64,...');
     

Workflows

1. Development Workflow:

   • Use assets:install --symlink for local development to avoid hardcoding paths.
   • Test CSS changes with assetic:dump --watch for real-time updates.

2. Deployment Workflow:

   • Run assets:install --env=prod to generate production-ready assets.
   • Verify paths in compiled CSS files (e.g., app/cache/prod/...).

3. Debugging Workflow:

   • Temporarily disable the filter (filter='?css_url_rewrite') to isolate path issues.
   • Check logs for FkrCssURLRewriteBundle errors during assetic:dump.

Integration Tips

1. Assetic Filter Chaining: Combine with other filters (e.g., yui_css, lessphp) for multi-step processing:

   {% stylesheets filter='css_url_rewrite,yui_css'
       '@BundleName/Resources/public/css/style.less'
   %}
   

2. Environment-Specific Config: Override settings per environment (e.g., disable rewrite_only_if_file_exists in dev):

   # app/config_dev.yml
   fkr_css_url_rewrite:
       rewrite_only_if_file_exists: false
   

3. Custom Path Handling: Extend the filter by subclassing Fkr\CssURLRewriteBundle\Filter\CssURLRewriteFilter and overriding rewriteUrl().

Gotchas and Tips

Pitfalls

1. Assetic Dependency:

   • The bundle requires AsseticBundle (deprecated in Symfony 4+). Ensure compatibility with your Assetic version.
   • Fix: Pin Assetic to a stable version (e.g., 2.8.*) if using Symfony 3.

2. Path Resolution Failures:

   • If rewrite_only_if_file_exists: true, missing files will not be rewritten, potentially breaking CSS.
   • Fix: Set rewrite_only_if_file_exists: false for development or pre-check paths.

3. Base64 Limitations:

   • Only handles static base64 strings in CSS. Dynamic data URIs may fail.
   • Fix: Avoid complex base64 logic or pre-process CSS.

4. Assetic Dump Issues:

   • Known bug in v1.0.3 with assetic:dump (fixed in later versions). Ensure you’re on v1.0.4.
   • Fix: Run assetic:dump --no-debug if issues persist.

5. Symfony 3+ Compatibility:

   • While v1.0.1 claims Symfony 3 support, some features may break. Test thoroughly.
   • Fix: Use v1.0.1 and monitor for regressions.

Debugging

1. Log Filter Output: Enable debug mode to see rewritten URLs:

   # app/config_dev.yml
   fkr_css_url_rewrite:
       debug: true
   

2. Inspect Compiled CSS: Check app/cache/{env}/... for filtered CSS files to verify path changes.

3. Common Errors:

   • "File not found": Ensure paths in CSS are correct and assets:install is run.
   • "Invalid URL": Avoid malformed paths (e.g., url(../img/) without filename).
   • "Assetic not found": Verify AsseticBundle is installed and registered.

Tips

1. Performance:

   • Disable the filter in production if not needed (e.g., for static assets):

     {% if app.environment == 'prod' %}
         {% stylesheets '@BundleName/Resources/public/css/style.css' %}
     {% else %}
         {% stylesheets filter='css_url_rewrite' '@BundleName/Resources/public/css/style.css' %}
     {% endif %}
     

2. Testing:

   • Use PHPUnit to test CSS path resolution with a mock Assetic environment:

     $filter = new \Fkr\CssURLRewriteBundle\Filter\CssURLRewriteFilter();
     $result = $filter->filter('background-image: url(../img/logo.png)');
     

3. Extending the Filter:

   • Override rewriteUrl() to add custom logic (e.g., environment-specific paths):

     class CustomCssURLRewriteFilter extends \Fkr\CssURLRewriteBundle\Filter\CssURLRewriteFilter {
         protected function rewriteUrl($url) {
             if (strpos($url, '@custom/') === 0) {
                 return str_replace('@custom/', '/custom-assets/', $url);
             }
             return parent::rewriteUrl($url);
         }
     }
     

4. Fallback for Missing Files:

   • Use a custom filter to log missing files when rewrite_only_if_file_exists is true:

     // In a custom filter
     if (!file_exists($path) && $this->container->getParameter('kernel.environment') === 'dev') {
         throw new \RuntimeException("CSS file not found: {$path}");
     }
     

5. Legacy Code:

   • If migrating from Symfony 2 to 3, test the bundle with v1.0.1 and update dependencies:

     composer require symfony/symfony:3.4.*