fkr/cssurlrewrite-bundle
Symfony2/Assetic filter that rewrites relative url() paths in CSS so assets (images/fonts) resolve correctly after assets:install. Optionally rewrites only when the target file exists and can normalize/clean generated URLs.
## Technical Evaluation
### Architecture Fit
- **Legacy Symfony2/Assetic Alignment**: The package is a **Symfony2 Assetic filter bundle**, designed to resolve relative CSS paths (e.g., `../img/logo.png`) to absolute paths (e.g., `/bundles/bundlename/img/logo.png`). This directly addresses a core pain point in **Symfony2 bundle development**, where cross-bundle asset references often break due to inconsistent path resolution.
- **Cross-Bundle Resource Sharing**: Supports `@BundleName` notation (e.g., `@AcmeMediaBundle/img/logo.png`), enabling **modular asset reuse** across Symfony bundles—a feature lacking in modern Laravel/Mix or Symfony4+ ecosystems.
- **Path Normalization**: Handles edge cases like `../less/../img` → `../img` and **base64-encoded images**, reducing manual CSS maintenance.
- **Symfony3 Partial Support**: Officially compatible with Symfony3 (v1.0.1), but **no guarantees for newer versions**. Assetic’s deprecation in Symfony4+ makes this a **legacy-only solution**.
### Integration Feasibility
- **Minimal Setup for Symfony2**:
- **Composer install** + **Kernel registration** + **Assetic filter configuration** (3 steps).
- Zero runtime dependencies beyond AsseticBundle.
- **Assetic Dependency Risk**:
- **Blocked in Symfony4+**: Assetic is deprecated; migration would require a rewrite (e.g., Webpack Encore + custom path resolver).
- **Potential Conflicts**: May clash with other Assetic filters or custom loaders.
- **Configuration Flexibility**:
- `rewrite_only_if_file_exists`: Safeguards against broken links.
- `clear_urls`: Normalizes paths like `../less/../img` to `../img`.
- **Base64 Support**: Limited to **static base64 strings** (not dynamic data URIs or CSS variables).
### Technical Risk
- **Deprecated Stack**:
- **Assetic is obsolete** in Symfony4+ (replaced by Webpack Encore). No path to upgrade without a rewrite.
- **PHP 5.3+ only**: Incompatible with PHP 8+ features (e.g., named arguments, attributes).
- **Stagnant Maintenance**:
- Last release in **2016**; no Symfony5/6 or Laravel compatibility.
- **Unresolved Bugs**: v1.0.3 fixed an `assetic:dump` issue, suggesting instability in edge cases.
- **CSS Parsing Limitations**:
- Relies on **Assetic’s CSS parser**, which may fail on modern CSS (e.g., `@import` rules, CSS variables).
- No support for **Sass/SCSS** or **PostCSS** (requires pre-processing).
- **No Modern Alternatives**:
- Laravel uses **Laravel Mix/Webpack** for asset pipelines (no direct equivalent).
- Symfony4+ relies on **Vite** or **Symfony UX** for asset handling.
### Key Questions
1. **Is Assetic still in use?**
- If **yes**, this is a **low-risk, high-value** fix for CSS path resolution.
- If **no**, evaluate **Webpack Encore** (Symfony4+) or **custom Laravel Mix plugins**.
2. **Are cross-bundle asset references critical?**
- If **yes**, the `@BundleName` feature justifies adoption despite risks.
3. **Can Assetic be phased out?**
- For Symfony4+, **migrate to Vite** or **Symfony UX** for long-term viability.
4. **What’s the CSS complexity?**
- Simple projects benefit more than those with **dynamic paths** (e.g., SASS variables, `@import`).
5. **Is PHP 7.4+ required?**
- If **yes**, this package is **incompatible** (PHP 5.3+ only).
---
## Integration Approach
### Stack Fit
- **Symfony2 + Assetic**: **Native fit**; no additional dependencies.
- **Symfony3**: **Partially supported** (v1.0.1), but untested in newer versions.
- **Laravel**: **Not applicable**. Requires a **custom solution**:
- **Option 1**: Laravel Mix **PostCSS plugin** to rewrite paths.
- **Option 2**: **PostHTML plugin** for static CSS rewrites.
- **Option 3**: **Laravel-specific package** (e.g., `spatie/laravel-css-url-rewriter`).
- **Other Frameworks**: Could be adapted for **Lumen/Slim** with Assetic, but **not recommended**.
### Migration Path
| **Current Stack** | **Target Stack** | **Migration Strategy** |
|--------------------------|----------------------------|----------------------------------------------------------------------------------------|
| Symfony2 → Symfony2 | Same | 1. Composer install. 2. Register bundle. 3. Configure Assetic filter. |
| Symfony2 → Symfony4+ | Webpack Encore | **Rewrite**: Replace Assetic with **Encore’s `copyFiles` + custom path resolver**. |
| Laravel (Legacy) | Laravel Mix | **Build alternative**: Use **PostCSS/PostHTML plugins** for path rewrites. |
| Symfony3 → Symfony4+ | Vite/Laravel Mix | **Hybrid approach**: Run Assetic in dev, migrate to Vite in stages. |
### Compatibility
- **Assetic Version**:
- Tested with **Symfony2 Assetic (1.x–2.x)**. May fail on newer Assetic forks (e.g., `symfony/assetic-bundle` updates).
- **PHP Version**:
- **PHP 5.3+ required**. Incompatible with PHP 8+ (e.g., no `match` expressions, attributes).
- **CSS Parsing**:
- **No support for**:
- SASS/SCSS (requires pre-processing).
- CSS variables (e.g., `--path: url(...)`).
- Dynamic `@import` rules.
- **Works for**:
- Static `url()` references.
- Relative paths (`../img/logo.png`).
- `@BundleName` notation.
- **Base64 Handling**:
- Limited to **static base64 strings** (not dynamic data URIs or CSS custom properties).
### Sequencing
1. **Assess Asset Pipeline**:
- Confirm if Assetic is the **only option** (or if Webpack/Vite is feasible).
- Audit CSS files for **complex paths** (e.g., SASS, variables).
2. **Pilot in Staging**:
- Test with a **subset of CSS files** using the `css_url_rewrite` filter.
- Validate `@BundleName` references and path normalization.
3. **Fallback Plan**:
- If bugs arise (e.g., `assetic:dump` failures), implement a **custom Assetic filter** or switch to Webpack.
4. **Deprecation Warning**:
- Document the **Symfony2-only** limitation and **plan for migration** to Webpack/Vite.
---
## Operational Impact
### Maintenance
- **No Active Development**:
- Risk of **breaking changes** if Symfony/Assetic updates.
- **No Symfony5/6 or Laravel support**.
- **Debugging Challenges**:
- CSS path issues may require **manual inspection** of compiled assets.
- Assetic’s **dumping mechanism** (v1.0.3 bug) could cause **silent failures**.
- **Workarounds**:
- Cache-busting (e.g., `?v=1.0`) may be needed if paths change unexpectedly.
- **Fallback**: Use **Twig’s `asset()` helper** for critical paths.
### Support
- **Limited Community**:
- **33 stars but no open issues** suggests niche usage. **No official support**.
- **Vendor Lock-in**:
- Tightly coupled to **Assetic’s internals**; hard to maintain if Assetic is deprecated.
- **Alternatives**:
- **Symfony4+**: Use **Symfony’s `asset()` helper** or **Vite’s `@/` aliases**.
- **Laravel**: Use **Laravel Mix’s `copy` or `postcss` plugins**.
### Scaling
- **Performance**:
- **Minimal runtime overhead** (filter runs during asset compilation).
- **Build-time cost**: Assetic processing adds to `assets:install`/`assetic:dump` time.
- **Mitigation**: Run in **parallel** (if Assetic supports it).
- **Large Projects**:
- May slow down **CI/CD pipelines** if CSS files are numerous.
- **Recommendation**: **Exclude non-critical CSS** from the filter.
### Failure Modes
| **Failure Scenario** | **Impact** | **Mitigation** |
|-------------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| **Assetic Deprecation** | Bundle breaks in Symfony4+. | Migrate to **Webpack Encore** or **Vite**. |
| **CSS Path Resolution Failures** | Broken images/fonts in production. | Test with `rewrite_only_if_file_exists=false` or **fallback to `asset()`**. |
| **Base64 Parsing Bugs** | Embedded images fail to render. | Avoid base64 or **pre-process CSS** with a custom tool. |
|
How can I help you explore Laravel packages today?