Store Bundle Laravel Package

Getting Started

This is a Symfony 2.x bundle from the Vespolina e-commerce stack, so the first thing to check before anything else is whether your project is actually on Symfony 2.x. If you're on Symfony 3+ or 4+, the bundle's service definitions and bundle class conventions will not load cleanly and you should stop here.

Assuming a compatible Symfony 2.x app:

1. Require the bundle and its siblings (vespolina/commerce, vespolina/product, vespolina/cart) — StoreBundle alone gives you very little, since store/channel/currency concepts are consumed by those bundles.
2. Register Vespolina\StoreBundle\VespolinaStoreBundle in AppKernel.php.
3. Import the bundle's routing and services config in app/config/config.yml under vespolina_store.
4. Persist the Store entity/document (the bundle ships both ORM Entity/Store.php and ODM Document/Store.php variants) via your own mapping configuration — the bundle does not ship mapping files you can rely on out of the box.

The first real use case is: create a Store, attach a currency and a tax zone, and reference it from a product or order. Look first at Model/StoreInterface.php, Model/StoreManager.php, and Model/StoreManagerInterface.php — that manager is the entry point for most day-to-day work. Everything else (entities, documents, DI wiring) exists to support those abstractions.

Because the package has essentially no active maintainers, treat the repo's Model/ PHP files as the authoritative API surface and expect to read source rather than docs.

Implementation Patterns

Extend the abstract models, don't use them directly. The bundle's Entity/Store and Document/Store are meant to be subclassed in your application so you can add fields (contact info, warehouses, opening hours) without patching the vendor. Follow the standard Vespolina pattern: create AppBundle\Entity\Store extends Vespolina\StoreBundle\Doctrine\ORM\Store and point the manager at your class.

Use the manager service, not repositories. StoreManager wraps persistence and exposes store lookup operations. Inject vespolina_store.store_manager (check Resources/config/services.xml for the exact service id, as it varies across versions) rather than EntityManager directly. This keeps your controllers testable and lets you swap ORM/ODM.

Channel-based multi-store setups. If you're doing multi-storefront, model it as: one Store per currency/fulfilment context, and let the Channel/Zone concepts from sibling bundles reference the store id. Keep resolution logic in a small service of your own (e.g. StoreResolver) rather than scattering getStore() calls across controllers.

Seed data via fixtures, not migrations. Because store data includes currencies and zones that almost always need bootstrap values, write Doctrine fixtures that create the default store and attach it to your product/order services on boot.

Integrate at the service level. The realistic integration is: your Cart or Order service takes a StoreInterface and reads getCurrency(), getTaxZone(), etc. Wire that in your services.yml by passing the manager's getDefaultStore() — but cache it per request, since the manager will hit the DB if not.

Testing pattern. Mock StoreManagerInterface and StoreInterface in your unit tests; don't spin up a kernel. For integration tests against the real manager, use an in-memory SQLite database with a minimal Store subclass.

Gotchas and Tips

• This bundle is essentially unmaintained. Twelve stars, zero dependents, last meaningful commits years ago. Budget time for reading source and expect no upstream fixes. Pin the exact composer version and vendor in your repo if you depend on it.
• No mapping files ship with the bundle. You must provide your own Resources/config/doctrine/Store.orm.xml (or annotations in your subclass). Forgetting this is the most common "it installs but nothing works" failure.
• Currency and tax data have no defaults. The store will accept an empty currency string and break downstream pricing silently — validate at the entity level yourself.
• Service IDs drift. Between the Symfony 2.0 and 2.3+ eras the bundle's services.xml and extension alias changed. Always open DependencyInjection/VespolinaStoreExtension.php and confirm the alias before writing config.
• ODM vs ORM divergence. The Mongo and Doctrine ORM implementations are not perfectly symmetrical — some StoreInterface methods behave subtly differently (e.g. how associated zones are returned). If you're on MongoDB, read Document/Store.php line-by-line; it receives fewer fixes than the ORM path.
• Extension point for custom logic. Rather than subclassing StoreManager, decorate it in your own bundle and register it under the same service id. This survives composer updates better than editing vendor code, which is tempting given the low activity.
• Debugging. Enable %kernel.debug% and check app/cache/dev/appDevDebugProjectContainer.xml to confirm the actual service ids and arguments the bundle registered — this is faster than trusting the docs.
• Escape hatch. If your store model starts to grow beyond currency + zones, consider keeping Vespolina models as thin adapters around your own domain entities rather than letting your app inherit the bundle's schema. That way an eventual migration off the bundle is a service swap, not a data migration.