React Admin Api Bundle Laravel Package

Getting Started

• Check the framework fit first. freema/react-admin-api-bundle is a Symfony bundle, not a Laravel package — there is no service provider, no Eloquent integration, and no config/*.php to publish. On a Laravel codebase you are either (a) reading it for the trait patterns, or (b) running it against a Symfony service in the same estate. Do not plan a Laravel sprint around it without confirming which of those you are doing.
• Install pinned: composer require freema/react-admin-api-bundle:^1.3.0. The 1.2.x line carries a delete bug (see Gotchas) — do not start on it.
• Read UPGRADING.md at the 1.3.0 tag before anything else. It is the only migration surface the maintainers publish, and the release notes point at it rather than repeating contents.
• Then read the traits, in this order: DeleteTrait, SoftDeleteTrait, then the list traits. These are the actual API contract — they define the response shapes (DeleteDataResult) and the query-parameter handling (sorting, filtering) that react-admin's dataProvider expects.
• First use case: wire one entity into a controller that composes the list + delete traits, point a react-admin <Resource> at it, and verify list, sort, and delete round-trip before adding a second entity. The traits are the unit of reuse; adopt them one resource at a time.

Implementation Patterns

• Compose, don't inherit. The intended shape is a thin controller that uses the relevant traits. Keep your own business logic in a service the controller calls, so a future trait signature change (like the SortDirection shift in 1.3.0) is a one-line controller edit rather than a rewrite.
• Let the list traits own sorting. As of 1.3.0 they pass the SortDirection enum when the installed doctrine/orm accepts it and fall back to the string on older versions. Do not hand-roll orderBy() from $_GET['sort'] in your own controllers — you will reintroduce the deprecation the release just fixed, and you lose the version negotiation.
• Treat delete as a status-returning operation. DeleteDataResult now returns success, or 400 for an unknown id — matching DeleteTrait. Model this in your client: a 400 means "already gone / never existed", not "server broke". react-admin will surface it as an error notification, so map it deliberately if your UI should treat it as idempotent.
• Soft delete and hard delete should be interchangeable from the client's perspective. That equivalence is precisely what 1.3.0 restored. If you maintain both variants of a resource, keep their response contracts aligned and test both paths.
• Version matrix drives your runtime choice:
  • Symfony 6.4 / 7.4 → PHP 8.2+ is fine (CI covers 8.2–8.5).
  • Symfony 8 → PHP 8.4 and DoctrineBundle 3 required; follow DoctrineBundle's own upgrade notes, not this bundle's.
  • Nothing changes for apps staying on 6.4/7 — the Symfony 8 work is additive.
• Mirror the static analysis bar. CI runs PHPStan 2 at level 8. If you extend or override the traits, matching that level locally will catch signature drift (e.g. enum-vs-string parameters) at build time instead of at runtime.
• Test in your app, not in vendor. Since 1.3.0 the dist package ships no tests, CI, or dev files. Your integration tests are now the only coverage for how you compose these traits.

Gotchas and Tips

• The 1.2.x delete bug is worse than a plain 500. SoftDeleteTrait::delete() passed the entity id where DeleteDataResult expects a status, throwing a TypeError after the entity had already been soft-deleted or removed. Every failed call was a half-applied mutation. If you ran 1.2.x in any environment, audit delete endpoints and logs for TypeErrors and check whether retries or queue consumers double-fired deletes on records that were already gone.
• Response semantics shifted under clients. Anything that previously saw a 500 from a failed soft delete now sees a clean status or a 400. If you have error-monitoring alerts keyed on delete failures, they will look like they stopped working — that is the fix, not a regression.
• Doctrine ORM 3.7 deprecation cuts both ways. The bundle now handles it internally, but any custom list code, custom filter classes, or overridden trait methods you wrote will still pass strings and emit the deprecation. Grep your own code for orderBy( with a literal 'ASC'/'DESC'.
• Symfony 8 is a PHP 8.4 gate, not just a Composer bump. Plan the runtime upgrade before the framework upgrade; the two cannot be sequenced the other way round. DoctrineBundle 3 is a separate, independent migration.
• No tests in the package. vendor/freema/react-admin-api-bundle has no CI config, no composer.lock, no dev dependencies. Do not try to run the upstream suite from vendor to reproduce a bug — go to the GitHub tag instead.
• Extension points: override trait methods in your controller or a small base controller rather than forking. The traits are the seams the maintainers change between minor versions; a fork puts you off the upgrade path for exactly the fixes 1.3.0 delivers.
• Watch the delete-trait behavioural parity. DeleteTrait and SoftDeleteTrait are now documented as answering identically. If a future release drifts them apart, that is a client-visible breaking change even in a patch — worth a quick regression test on both.