Admin Bundle Laravel Package

Getting Started

This is a Symfony 2-era bundle that layers a Sonata Admin UI on top of the Vespolina e-commerce stack. Expect to install it alongside—not instead of—sonata-project/admin-bundle, vespolina/core-bundle, vespolina/product-bundle, and vespolina/order-bundle. Because the package is effectively unmaintained (4 stars, no dependents, low score), treat the install as a "vendor and pin" exercise rather than a modern composer require.

Minimal steps:

1. Pin the dependency explicitly in composer.json (a dev-master constraint is usually the only thing available on Packagist for repos like this). Pair it with the Sonata and Vespolina versions the bundle's own composer.json was written against—do not let Composer float them.
2. Register the bundle in app/AppKernel.php after the Sonata bundles. Confirm the actual bundle class name by opening the file at the repo root (VespolinaAdminBundle.php); the namespace is likely Vespolina\Bundle\AdminBundle.
3. Import routing—both Sonata's admin routes and the bundle's own routes—in app/config/routing.yml.
4. Configure sonata_admin in app/config/config.yml, wiring in the admin services the bundle ships (look in Resources/config/*.xml).
5. Run assets:install / assetic:dump (this predates the Webpack Encore era), then create a Sonata admin user and hit /admin.

Where to look first:

• README.md and any docs/ folder for the intended bundle registration order.
• Resources/config/ (usually admin.xml or similar) — this is the service-definition map that tells you exactly which Admin classes exist and what they are tagged with.
• Admin/ — the concrete classes (ProductAdmin, OrderAdmin, etc.). Skim configureFormFields, configureListFields, and configureDatagridFilters to understand what UI is provided out of the box.
• DependencyInjection/Configuration.php — the bundle's own config tree, which tells you what is actually configurable versus hard-coded.

First use case: stand up the admin dashboard and use it to CRUD products and view/manage orders. That is the bundle's entire reason to exist: a store operator backend, not a developer tool.

Implementation Patterns

Do not edit vendor code. The bundle is stale enough that you will want to upgrade or replace it later; keep your customizations in your application layer. The normal pattern is to subclass the bundle's admin classes:

// src/Acme/StoreBundle/Admin/ProductAdmin.php
namespace Acme\StoreBundle\Admin;

use Vespolina\Bundle\AdminBundle\Admin\ProductAdmin as BaseProductAdmin;

class ProductAdmin extends BaseProductAdmin
{
    protected function configureListFields(ListMapper $list)
    {
        parent::configureListFields($list);
        // add or reorder columns
    }
}

Then register your subclass as the service and point the sonata.admin tag at it, overriding the original service ID (or use the same ID in your app config so it wins over the vendor definition). This is the day-to-day workflow: the bundle gives you a working baseline, and you tune fields, filters, and templates for the client.

Extend, don't fork, for field customization. Sonata's configure*Fields methods are the intended extension points. Add fields for product attributes (SKU, price, tax, inventory), order status, and customer data there rather than touching templates.

Template overrides go in app/Resources/. Sonata resolves admin templates through a known override path. If the bundle ships templates under Resources/views/, copy the specific one you need into app/Resources/VespolinaAdminBundle/views/... and edit that. This survives a vendor update and keeps the diff small.

Menu and dashboard integration. Products and orders should appear as top-level menu entries. Do this through the sonata_admin config in app/config/config.yml (dashboard groups, menu items), not by editing the bundle. If you need dynamic menu behavior (e.g., badge with open orders), use Sonata's MenuBuilder events.

Access control. Give each admin class a distinct security role (ROLE_STORE_PRODUCT_ADMIN, ROLE_STORE_ORDER_ADMIN). Sonata's security config on the admin service plus your firewall config is the whole story—do not rely on the bundle to enforce anything, it almost certainly does not.

Order lifecycle work is the real substance. The admin gives you editing screens; the actual state transitions belong in your Vespolina order processor layer. Wire buttons/actions in the order admin to call your own service, then redirect back to the Sonata list. Keep business rules out of the Admin class itself so you can test them without booting the UI.

Testing. Use functional tests that hit the admin routes with an authenticated admin user and assert the list/form pages render. This catches Sonata version skew early—which is the most common failure mode with this package.

Gotchas and Tips

• This is an abandoned, low-adoption package. Four stars and zero dependents means the happy path is the only path anyone has walked. Pin every related dependency (Symfony, Sonata, Doctrine, Vespolina) and commit composer.lock. Budget time to read vendor source when something breaks—StackOverflow will not have answers.
• Symfony 2 only. The service definitions, bundle class, and AppKernel registration pattern will not work on Symfony 3+, let alone 4/5/6. If the target application is modern, this bundle is the wrong tool; port the admin screens to a current stack instead.
• Sonata version coupling is the sharpest edge. The bundle was written against a specific Sonata Admin generation. A minor Sonata bump can break configureDatagridFilters signatures, template blocks, or the service tag attributes. Check the bundle's composer.json constraints and install exactly within them.
• Asset pipeline assumptions. Expect Assetic and assets:install --symlink. If your app has moved to Webpack Encore, you will be hand-porting the admin CSS/JS. Verify the admin layout renders before you build anything on top of it.
• Doctrine inheritance and mapping. Vespolina models products and orders with class-resolution/mapping configuration. If your app uses custom entity classes, misconfigured resolve_target_entities or missing bundle ordering produces confusing "class not found" or empty-grid errors. Run doctrine:schema:validate and check the admin filters actually return rows.
• Routing order matters. Import Sonata admin routes before the bundle's routes; otherwise the dashboard route can shadow specific admin endpoints. When a page 404s, app/console router:debug (or debug:router) is your first stop.
• Debugging service wiring. app/console container:debug | grep -i vespolina and container:debug | grep sonata.admin show which admin services are registered, their tags, and their roles. Most "the admin page is blank" issues are a missing or mistagged service, not a code bug.
• Templates and translations are the usual quick wins. If the UI looks broken, compare your override against the vendor template—Sonata versions renamed blocks between releases.
• Extension points to prefer: subclass the Admin classes, override templates under app/Resources, and decorate services for cross-cutting behavior (audit logging, permission checks). Avoid forking the bundle unless you intend to maintain the fork, because the upstream is not going to accept or ship your patches.
• Exit strategy. Given the package's state, write the admin customization as a thin, replaceable layer. The realistic long-term plan is to migrate these screens to a maintained admin framework and keep the Vespolina domain layer—which is the part with actual value—untouched.