Sonata Admin Splash Bundle Laravel Package

Getting Started

Before anything else: this is a Symfony bundle, not a Laravel package. It has no service provider, no publishable config, and no config/sonata.php. Dropping it into a Laravel app via Composer accomplishes nothing useful — there is no container binding to register and no routes to load. The only realistic host is a legacy Symfony 3/4 application that already runs sonata-project/admin-bundle and splash/splash-bundle.

Assuming you have that host:

1. composer require splash/sonata-admin-splash-bundle
2. Register the bundle in app/AppKernel.php (or config/bundles.php on Symfony 4 Flex)
3. Import its routing YAML alongside the Sonata Admin routes
4. Register its admin services under a sonata_admin.dashboard.groups entry so they appear in the sidebar
5. bin/console assets:install --symlink and bin/console sonata:admin:setup

Where to look first: the bundle's Admin/ directory (the Sonata AbstractAdmin classes that define the screens), Resources/views/ (Twig templates), and Resources/config/ (service and routing definitions). The actual Splash API client lives in the parent splash/splash-bundle, not here — this bundle is purely the Sonata UI shell around it.

First use case: log into /admin, open the Splash group, and inspect which Splash servers are connected and what each connector's last sync state is — without SSH-ing into the box or curling the Splash API by hand.

Implementation Patterns

Dashboard group wiring. The explorer's admins need an explicit entry in sonata_admin.dashboard.groups. Without it they render but float outside any menu section, which confuses operators. Group them under a single "Splash" label with an icon and ROLE_SUPER_ADMIN items.

Read-mostly ops console. Treat the explorer as observability, not business logic. It shows servers, connector configuration, and sync logs. Don't build domain workflows on top of its admin classes — they're thin views over a remote API and will not survive an upgrade.

Bypass it for automation. If you need to trigger a sync, check a status, or reconcile data programmatically — for example from a Laravel queue job — skip this bundle entirely and call the Splash REST API directly with the same API key / Webservice ID the explorer is configured with. The explorer adds no capability the API lacks.

Split-stack pattern. A common real-world shape: the Laravel app owns the domain and the modern UI; the legacy Symfony app hosts Sonata plus this explorer as an internal-only read-only console. Keep them on separate hosts and separate databases; the only shared state should be the Splash account credentials.

Iframe / reverse-proxy embedding. If stakeholders want these screens inside a Laravel admin panel, proxy the Sonata route behind SSO or iframe it on an internal network. Porting the Twig templates to Blade is more work than reimplementing the three screens against the API.

Feature-flag the route. Gate the whole thing behind an internal-only firewall in security.yaml plus ROLE_SUPER_ADMIN. It exposes connector configuration and sync metadata; it should never be internet-facing.

Gotchas and Tips

• Framework mismatch is the headline gotcha. No Laravel integration of any kind. Every configuration surface is YAML plus bundle registration. If you're a Laravel-only team, budget for a Symfony-competent engineer or don't adopt it.
• Archived, 1 star, 0 dependents. Treat it as frozen. There are no guarantees for Symfony 5/6 or PHP 8 compatibility, and no security patches. Pin exact versions and expect to vendor-patch or fork.
• Sonata asset pipeline. Missing assets:install or sonata:admin:setup produces a broken-looking explorer (unstyled tables, dead JS) rather than an error. If the UI looks wrong, check assets before debugging code.
• Silent role gating. Sonata hides admins the current user lacks roles for. An empty Splash menu is almost always an ACL/role problem, not a routing or service-registration problem.
• Connectivity and credentials. The explorer calls out to the Splash API. Confirm outbound allowlisting for *.splashsync.com and that the API key is set in the splash config section — not hardcoded in an admin class, which is an easy mistake when patching quickly.
• Cache invalidation. Sonata caches admin metadata aggressively. Run bin/console cache:clear after touching services, dashboard groups, or templates; otherwise your changes appear not to apply.
• Debugging path. Start in Admin/ and Resources/views/. Splash API failures usually surface as Sonata flash messages, so tail the app log and the Splash bundle's log channel rather than adding dump() calls.
• Extension points are thin. You can subclass the provided admin classes or override Twig under templates/bundles/. There's no meaningful event system — don't design around hooks that aren't there.
• Migration path. If this bundle is the main reason the Symfony app still exists, extract its two or three screens into a Filament or Nova panel calling the Splash API directly. That's a few hundred lines of straightforward work versus indefinitely maintaining a dead dependency.