Ting Bundle Laravel Package

Getting Started

• Reality check first: ting_bundle is a Symfony bundle (7.4 / 8) around the Ting persistence layer — not an Eloquent-style package with Laravel auto-discovery. There's no service provider, no Artisan commands, no Laravel bridge. It's only relevant to a Laravel developer who is also running (or migrating to) Symfony. Everything below assumes Symfony conventions.
• Requirements: PHP 8.2+ (8.4 for Symfony 8), Symfony ^7.4 || ^8.0, xavierleune/ting ^4.0.
• Install:

  composer require xavierleune/ting_bundle:^4.0
  

• Register the bundle in config/bundles.php. Flex usually handles this, but verify it explicitly if you're coming from ccmbenchmark/ting_bundle (see UPGRADE-4.0.md).
• Set the defaults once so entities stay short:

  # config/packages/ting.yaml
  ting:
      default_connection: main
      default_database: '%env(DATABASE_NAME)%'
  

• First use case — one entity, one repository, one query:

  #[Table(name: 'city', repository: CityRepository::class)]
  class City implements NotifyPropertyInterface
  {
      // ...
  }
  

  Then autowire CityRepository into a controller or console command and call countBy() / existsBy() to prove the wiring before touching the profiler.
• Read first: the new getting started guide (validated against a real kernel in the test suite), then UPGRADE-4.0.md if you have any 3.x code.

Implementation Patterns

• Entities carry their own persistence metadata. #[Table(name:, repository:)] per entity; default_connection / default_database fill in whatever you omit, and explicit values still win. Multi-connection apps only annotate the exceptions.
• Treat repositories as services. Autowire them directly into controllers, handlers and commands rather than building a factory. RepositoryFactory is itself autowirable when you need to resolve repositories dynamically.
• Prefer the shortcuts over hand-built criteria: countBy, existsBy, getBySql, transactional, plus typed query parameters (pass the int/enum/DTO, let Ting bind it).
• Enums and value objects: backed enums persist as their scalar value via Ting's BackedEnum serializer. Type-aware change tracking means readonly value objects, enums and serializer-handled DateTimeImmutable aren't compared on every save — override with #[Column(mutable: ...)] when you genuinely want dirty-checking.
• Caching: cache_provider is the id of any Symfony cache pool. Pick a dedicated pool rather than leaning on cache.app by accident.
• Worker mode is supported: repositories are reset between requests (FrankenPHP, RoadRunner), alongside the pool, unit of work, loggers and collectors. Anything you cache around a repository is still your responsibility.
• Validation: UniqueEntity takes named arguments only, and its violation message now renders enum, date and object values correctly.
• Security: the user provider's refreshUser() reloads by primary key — re-test any custom provider that assumed 3.x behaviour.
• Integration tip: repositories autowired as services receive Ting's cache, not cache.app. If you want your pool, inject it explicitly.

Gotchas and Tips

• Breaking — connection keys: master / slaves became primary / replicas. The old keys fail the container build with a message naming the replacements; friendly, but it blocks boot until renamed.
• Breaking — cache: cache_provider changed from a doctrine/cache service to a Symfony cache pool id. doctrine/cache is gone entirely; a stale id fails at build time.
• Breaking — enum storage: 3.x wrote backed enums JSON-encoded; 4.x writes the raw value. Either write a data conversion or set enum_serializer: symfony_serializer to keep the old storage. Decide before deploying, not after.
• Breaking — UniqueEntity: named arguments only. Positional usages from 3.x won't be tolerated; grep for them during the upgrade.
• serializerOptions now replace defaults instead of merging into lists. Setting a single option expecting the rest to survive silently drops them.
• JSON columns hydrate differently: an array property now gives you an associative array, not a stdClass. Every $entity->json->prop becomes $entity->json['prop'].
• Build-time strictness is deliberate: union-typed or untyped #[Column], or a #[Table] missing connection/database/repository, fails the container build with the entity named. Warm the container in CI to catch these before runtime.
• Change tracking follows property type, not your intent. If an update mysteriously doesn't flush, check #[Column(mutable: ...)] before assuming a query bug.
• Coming from ccmbenchmark/ting_bundle: the namespace changed. With Flex, re-check config/bundles.php after the switch — a leftover entry bites you at boot.
• Debugging: every query shows up in the Symfony profiler, so check there before adding logging. Under worker mode the profiler is per-request — don't chase data across requests.
• Symfony 8: the ting service previously failed on the new file_locator service; drop any workaround you pinned around that.
• Extension points: autowirable RepositoryFactory, custom serializers registered with Ting, and per-column mutable overrides. If behaviour isn't expressible in #[Table] / #[Column], hook there rather than subclassing repositories.