Core Bundle Laravel Package

Getting Started

Before anything else: despite being asked about in a Laravel context, smartbox/core-bundle is a Symfony bundle (the -bundle suffix, the DependencyInjection/ and Resources/config/ layout, and Smartbox Group's stack all point to Symfony, not Laravel). It is not installed via a Laravel service provider and has no facade or config publishing workflow. If you are committing to it, you are committing to a Symfony host app or a port.

Minimal steps:

1. Install with composer require smartbox/core-bundle (pin a version explicitly — do not rely on *; the package is still effectively dormant and v1.8.0 is a small feature bump, not a sign of active maintenance).
2. Register the bundle in the Symfony host's config/bundles.php:

   return [
       // ...
       Smartbox\CoreBundle\SmartboxCoreBundle::class => ['all' => true],
   ];
   

3. Look first at src/ for the bundle class and any Model/, Manager/, Service/, or Serializer/ namespaces — these are the reusable "core" abstractions the bundle exists to share across Smartbox apps. As of v1.8.0, Serializer/ also contains the PlainTextDeserializationVisitor.
4. Read DependencyInjection/Configuration.php and the extension class to see what is actually configurable, and Resources/config/services.* to see what gets registered automatically — including whether the new JMS Serializer visitor is registered by default or must be wired manually.
5. First real use case: it is a shared foundation bundle — base entities/contracts, common managers, cross-cutting services, and (since v1.8.0) a JMS Serializer visitor for plain-text payloads. Use it as a dependency of your feature bundles, not as an application skeleton.

If you cannot justify running Symfony, do not attempt to composer require this into a Laravel app — you will get unresolvable Symfony\*, Doctrine\*, and (now more visibly) JMS\Serializer\* constraints.

Implementation Patterns

Service-layer bootstrapping. The bundle's value is exposing services for autowiring. Inject the managers/contracts it publishes rather than new-ing anything from the package. Treat the bundle's Resources/config/services.xml|yaml as the contract: whatever is public or aliased there is the API.

Composition over consumption. Typical Smartbox usage is layered bundles: core-bundle provides base classes and shared services; feature bundles extend them via compiler passes and prependExtension. If you extend a base model, use the getSubscribedServices / bundle extension hooks rather than overriding container definitions manually.

Plain-text deserialization (new in v1.8.0). The bundle ships a custom PlainTextDeserializationVisitor for JMS Serializer, letting you "deserialize" raw plain-text payloads into typed objects the same way you'd deserialize JSON/XML. Practical implications:

• Confirm the visitor is registered on the host's jms_serializer service (either via the bundle's service config or explicitly in your JMS Serializer bundle config). Register it in the visitor list in the right order — a plain-text visitor that runs before your JSON/XML visitors can hijack content types you didn't intend.
• It is not true structured deserialization: a plain string cannot be mapped field-by-field, so expect the visitor to hand the raw string to a single property or to a constructor/mutator path. Check the visitor source before designing DTOs around it.
• Best fit is endpoints/queues that receive bare text bodies (webhooks, legacy integrations, single-value message payloads). For anything with structure, keep using JSON/XML.

Config-driven extension. If you need to customize the bundle, do it through config/packages/smartbox_core.yaml (matching the extension's alias) and use prependExtension in your own bundle to merge defaults. Do not edit vendor files — this package has a single maintainer signal and no active release cadence; your patches will vanish on composer update.

In a Laravel app (bridging). If you must reach into it from Laravel, isolate it behind an adapter: a single CoreBridge class that wraps the handful of services you actually need, and wire it via a custom service provider that builds those services by hand. Do not try to load the Symfony bundle inside Laravel — there is no Flex-style auto-registration and you'll fight Kernel assumptions. The same applies to the new serializer visitor: if you need plain-text deserialization in Laravel, either port the visitor logic (it is a small, self-contained JMS Serializer visitor) or use a dedicated JMS setup; do not pull the whole bundle in for it.

Versioning discipline. Because there are zero dependents and no active maintainer, treat upgrades as migrations. Commit composer.lock, record the exact SHA/version in a comment, and add a smoke test that boots the container so a broken transitive Symfony or JMS Serializer upgrade fails CI loudly. v1.8.0's serializer change is exactly the kind of thing that can break subtly when JMS Serializer bumps its visitor interfaces.

Gotchas and Tips

• It is still dormant. v1.8.0 is a small feature addition, not a revival — do not expect PHP 8.1+ / Symfony 6+ compatibility without patches. Check composer.json constraints before assuming it will install on a modern stack; it very likely won't without --ignore-platform-reqs and manual fixes, which is a red flag.
• JMS Serializer is now a first-class integration point. v1.8.0 adds a JMS Serializer visitor, which means the bundle is coupled to JMS Serializer's visitor API. That API has changed across major versions; a host app on a newer JMS Serializer may reject or silently ignore the visitor. Pin jms/serializer in the host app and smoke-test that the visitor actually runs.
• Visitor registration is silent when wrong. An unregistered or misordered visitor does not throw — plain-text payloads will simply be processed by the default visitor or fail with an unhelpful serialization error. Verify with debug:container on the serializer service and a small unit test that deserializes a plain string.
• Zero stars, zero dependents. There is no community to ask, no StackOverflow footprint, and no third-party tutorials. The v1.8.0 feature has no docs beyond the release note. Any knowledge you need must come from reading the source. Budget time for that.
• Symfony vs Laravel mismatch is the headline gotcha. Do not add it to a Laravel composer.json; the dependency tree conflicts (now including JMS Serializer) are not worth resolving. If a Laravel contract requires "Smartbox compatibility," port the interface or the visitor, don't install the bundle.
• Bundle alias mismatch. The DI extension alias rarely matches the package name exactly (e.g. smartbox_core vs smartbox/core-bundle). Confirm by reading DependencyInjection/*Extension::getAlias() before writing config YAML — a typo silently yields an empty config, not an error.
• Silent service overrides. Symfony's compiler passes can replace definitions without warning depending on registration order. Use debug:container --tag=... and debug:container <service> to confirm which definition wins before debugging runtime behavior — especially relevant if you also register your own serializer visitors.
• No deprecation bridge. Since the bundle won't emit deprecation warnings for Symfony/JMS BC breaks, treat every minor bump as potentially breaking. Pin Symfony core and JMS Serializer versions in the host app.
• Debugging tip. bin/console lint:container and bin/console debug:container Smartbox are your fastest ways to see what the bundle actually registered — more useful than the docs (which remain minimal). For the new visitor specifically, inspect the jms_serializer service and its visitor list.
• Extension point of last resort. If you need to fix a bug — including adapting the plain-text visitor to a newer JMS Serializer — fork the repo, add a replace entry in your composer.json, or vendor-patch via cweagans/composer-patches. Given the maintenance status, forking is the honest long-term answer.
• License is MIT — you are free to fork and vendor it internally without legal friction, which is the pragmatic path for a Laravel team that inherits a PHP dependency on it, or wants to lift just the new PlainTextDeserializationVisitor into its own package.