Pimp My Sonata Bundle Laravel Package

Getting Started

Before anything else, internalize the project status: archived, 0 stars, 0 dependents. This is not a dependency you adopt for a new project; it is reference material for how PrestaConcept themed and extended SonataAdminBundle around the Sonata 2.x/3.x era. Treat the repository as a source of copy-paste patterns, not a Composer requirement.

Minimal steps to evaluate it:

1. Read composer.json first. Check the sonata-project/admin-bundle constraint and the Symfony version range. If your app runs Sonata 4/5 or Symfony 5+, assume incompatibility until proven otherwise. This single file determines whether the package is usable at all.
2. Inspect Resources/views/. This is where the "pimping" lives — overridden Sonata layout, dashboard, and standard layout templates. This directory is the highest-value artifact in the repo.
3. Inspect Resources/public/ for CSS/JS/icon assets and how they are wired into the layout.
4. Read DependencyInjection/Configuration.php to see the config tree (theme toggles, block options, asset paths). This tells you whether it is config-driven or hardcoded.
5. Scan the bundle class and any compiler passes for service overrides or Twig namespace registration.

First use case: restyle the Sonata admin chrome (header, sidebar, dashboard, login page) globally without touching every Admin class. The bundle's core value is a set of Twig overrides for SonataAdminBundle templates plus a matching asset bundle.

# Only if constraints match your stack
composer require presta/pimp-my-sonata-bundle
php bin/console assets:install --symlink
php bin/console cache:clear

Then register the bundle in config/bundles.php and look for a presta_pimp_my_sonata: section in the README/config to enable it.

If constraints do not match — the likely case — do not install it. Instead, vendor the templates you want directly into templates/bundles/SonataAdminBundle/ in your app. That is the same mechanism the bundle uses, with none of the abandonment risk.

Implementation Patterns

Prefer template overrides over bundle activation. Sonata resolves templates through the standard Twig bundle override path, so copying a file from Resources/views/ into templates/bundles/SonataAdminBundle/ gives you the visual change with zero dependency. This is the pattern to use for an archived bundle.

Scope the override narrowly. Sonata's standard_layout.html.twig and layout.html.twig are the highest-leverage files but also the most fragile. If you only need a restyled dashboard, override Block/dashboard.html.twig and leave the layout chain alone.

Keep per-admin customization in the admin class, not the bundle. Use $admin->setTemplate('list', '...') for one-off screens and reserve the global override for things that must apply everywhere (branding, nav, login). Mixing both makes regressions hard to trace.

Mirror the bundle's structure in your app. If you fork any part of it, create templates/bundles/SonataAdminBundle/ plus a small app-level asset entry (Webpack Encore or assets/). This gives you an upgrade path and a clear diff against upstream Sonata template changes.

Compose, don't fork the service layer. If you need behavior beyond styling, decorate Sonata services (e.g., block services, sonata.admin.pool) rather than copying the bundle's DI config. Decoration is version-tolerant; copied service definitions are not.

Config-driven theming pattern: if you replicate the bundle's config approach, expose a small tree (theme, logo, colors, menu_items) under your own bundle and read it in a Twig extension or global. This is the part of PimpMySonata that is worth reimplementing cleanly, because hardcoded assets in templates are painful to change later.

Asset strategy: point layout templates at asset paths you control (asset('build/admin.css')). Do not rely on Resources/public paths that require assets:install symlinks, especially in Docker/CI where symlinks and permissions cause repeated friction.

Gotchas and Tips

• Archived means no security patches and no Sonata compatibility work. Any CVE in the templates or assets is yours. The Sonata 4 rewrite changed template names, block structure, and asset handling substantially; expect breakage.
• Composer conflicts are the first wall. Old Symfony/Sonata constraints will fight your lockfile. Do not use --ignore-platform-reqs to force it in; you will get runtime Twig errors instead of install errors, which are much harder to debug.
• Twig deprecations surface as blank pages. Sonata's template inheritance chain is deep; a removed function or changed block name often yields a white screen or a silently missing block. Use bin/console debug:twig and bin/console debug:container --parameter=twig.paths to confirm which template actually wins.
• Override precedence is easy to get wrong. App-level templates/bundles/SonataAdminBundle/ wins over bundle templates. If your change "does nothing", you are editing a template that is not being loaded — check with debug:twig and Twig's {% dump %} or the Symfony profiler's template panel.
• Cache is your enemy during theming. cache:clear after every template move; in dev, twig.auto_reload should be on. Stale compiled templates are the most common false alarm.
• Asset publishing bites in CI. assets:install --symlink behaves differently in containers and on Windows. Prefer Encore/Webpack and reference built assets directly.
• Don't stack admin themes. Combining this with other Sonata UI bundles (or a custom theme) causes CSS specificity wars and duplicated JS. Pick one source of admin chrome.
• Extension points to prefer: Twig blocks (override {% block %} rather than rewriting files), Sonata's sonata_admin.templates config keys, and service decoration. All three survive Sonata upgrades better than wholesale template copies.
• Debugging checklist: confirm bundle registration → confirm template resolution (debug:twig) → confirm asset URL loads (browser network tab) → clear cache → check profiler for Twig exceptions.
• Long-term recommendation: do not build on this. Extract the visual ideas you want, implement them as app-level overrides backed by Encore, and keep your Sonata version current. The "pimping" is 90% CSS and template overrides — you can reproduce the useful 10% in an afternoon without inheriting an archived dependency.