Core Bundle Laravel Package

Getting Started

os2display/core-bundle is the shared domain bundle behind the OS2display digital-signage platform. Before you composer require it, note one thing that shapes everything else: this is a Symfony bundle, not a Laravel package. It ships a *Bundle class, a DependencyInjection/ extension, Doctrine entity mappings and event listeners — there is no service provider, no facade, no config file under config/. If you are working in a Laravel app, treat it as a library you integrate deliberately (see Gotchas) rather than something that "just works" after install.

Minimal first steps:

1. composer require os2display/core-bundle:^2.2 and confirm the constraint resolves against your PHP version — the 2.x line targets modern PHP, but check composer.json in the package for the exact floor.
2. Read, in this order: composer.json (dependencies tell you whether it expects JMS Serializer, Doctrine ORM, or Symfony's own serializer), Entity/ (your actual domain model — screens, slides, playlists, media, channels), then EventListener/SerializationListener.php (the file touched in this release).
3. Register the bundle in your kernel/bundles.php and make sure Doctrine picks up the mapping. In a Symfony app this is one line; in Laravel you will need a Doctrine bridge (doctrine/orm plus something like laravel-doctrine/orm) and manual mapping registration.
4. Run your schema tooling against the new entities before writing any feature code. The migrations you need almost certainly do not ship with the bundle.

First use case worth wiring end-to-end: create, list and edit screens via a JSON API. That single flow exercises the entities, the repository layer and — critically — the serialization listener, which is where this release made changes.

Implementation Patterns

Inject the repositories, don't touch the EM. The bundle's entities are plain Doctrine entities; the stable seam for your application code is EntityManagerInterface plus the bundle's repositories. Wrap them in your own thin service (ScreenService, PlaylistService) so that when the bundle's mapping changes in a minor release you have one place to patch instead of fifty controllers.

Serialization is the surface you should own. The bundle deliberately keeps a SerializationListener that decorates entity (de)serialization, and this patch fixes a bug in it. Don't rely on implicit serialization of entities in your controllers. Instead:

• Define explicit serialization groups or your own normalizer/DTO layer, and map bundle entities onto your own response shapes.
• If you do reuse the bundle's listener, register it explicitly and add a test that round-trips a Screen and a Slide, so a future listener change fails loudly in your suite rather than silently in production.

Typical workflow for a resource endpoint:

// app/Services/ScreenService.php
public function __construct(private EntityManagerInterface $em) {}

public function paginate(int $page = 1, int $perPage = 25): array
{
    return $this->em->getRepository(Screen::class)
        ->findBy([], ['id' => 'ASC'], $perPage, ($page - 1) * $perPage);
}

Keep the entity inside the service; return DTOs outward.

Roles: consume the constant, not the string. 2.2.3 introduces a screen administrator role. The correct integration is to reference whatever constant/enum the bundle exposes (look in the bundle's security/role class or Resources/config) and add it to your role hierarchy in one place:

// Symfony security.yaml
role_hierarchy:
    ROLE_SCREEN_ADMIN: [ROLE_USER]

Then gate screen mutations with a voter or denyAccessUnlessGranted() rather than sprinkling isGranted('ROLE_...') checks with hardcoded strings. When the bundle later renames the role, you change one line.

Treat the bundle as the model, your app as the policy. A workable split that holds up over time: bundle entities = persistence shape; your services = validation, authorization and business rules; your serializers = wire format. Do not subclass bundle entities to add fields — Doctrine inheritance across a vendor boundary gets painful fast. Add a related entity or a JSON metadata column instead.

Fixtures and seeding. Because the bundle ships no migrations, keep a make db-reset style task that runs your migrations and the bundle's fixtures (if present) in a deterministic order. Screen/slide content is graph-like; getting seed data right early saves a lot of debugging.

Upgrade rhythm. Pin to ^2.2 and read each patch note. These are small, frequent releases; a monthly composer update os2display/core-bundle --with-dependencies plus your integration test suite is the sane cadence.

Gotchas and Tips

• The serialization listener fix in 2.2.3 is a behaviour change. "Fixed issue" means output for some payload changed. If you have snapshot tests or cached API responses that include serialized screen/slide data, expect diffs. Diff one real response before and after the upgrade; that is ten minutes well spent.
• It is not a Laravel package. No CoreBundleServiceProvider, no config/core.php, no publishes(). Any tutorial assuming Laravel conventions will mislead you. Budget real time for the Doctrine bridge, entity mapping registration and container wiring.
• Debugging the listener. If serialization produces empty or over-populated output, check listener registration order first — a listener registered before Doctrine's proxy initialisation will see uninitialised entities. bin/console debug:event-dispatcher (Symfony) is the fastest way to see what is actually attached.
• Container/cache staleness after upgrade. After bumping the bundle, clear the container and Doctrine metadata cache (cache:clear, doctrine:cache:clear-metadata). A stale metadata cache produces "unknown column"-style errors that look like broken code but aren't.
• Permissions fail open. Introducing a screen admin role does not retroactively protect existing routes. Audit every screen/slide/playlist mutation endpoint after upgrading — a missing check now silently allows the new role through.
• Config quirks. Anything the bundle reads from configuration arrives via its DependencyInjection extension, which means keys are bundled and validated at compile time, not runtime. Errors surface during container build, not on request — read the full compiler output rather than just the last line.
• Extension points, in order of safety: event subscribers on the bundle's dispatched events → decorating its services → a compiler pass → forking. Never patch vendor/; if you need a change, send it upstream (the project clearly takes PRs — this release is one) or decorate.
• Doctrine mapping overrides. If you must change a column type or add an index, use an XML/YAML mapping override in your own bundle rather than annotations in the vendor tree.
• Watch for orphan removal on relationships. Screen↔slide→media graphs invite cascading deletes. Test deletion of a media item referenced by multiple slides before you ship — this is the classic way to lose a customer's content library.
• Log the version. Expose the resolved bundle version in an /health or /about endpoint. When a bug report lands, knowing whether it is pre- or post-2.2.3 saves a round trip.