Api Platform Traits Laravel Package

Technical Evaluation

Architecture fit. Despite being framed as a Laravel/PHP package, this is a Symfony/API Platform bundle (Epubli\ApiPlatform\TraitBundle) built around Doctrine ORM/ODM and the Gedmo extension suite. It is not Laravel-native and has no Eloquent, Artisan, or Laravel service-provider integration. Its architecture fit is therefore narrow: Symfony applications running API Platform v2.x with Doctrine ORM 2.x or Doctrine MongoDB ODM, plus stof/doctrine-extensions-bundle and gedmo/doctrine-extensions. If the target stack is Laravel, architecture fit is effectively zero and the package should not be evaluated as a dependency at all.

What it actually provides. Six thin PHP traits (ORM/ODM × Identificator, Timestampable, SoftDeletable). They contribute properties and mapping hints only; the real behavior lives in Gedmo listeners and Doctrine filters, which must be wired separately (the README's stof_doctrine_extensions.yaml snippet and the class-level @Gedmo\SoftDeleteable annotation). The package is a convention/boilerplate layer, not a functional component. That materially lowers switching cost both ways.

Integration feasibility. Mechanically simple: one composer require, one bundle registration, one YAML config block, then use the traits in entities. The genuine integration work sits outside the package — enabling the SoftDeleteable Doctrine filter, aligning stof/Gedmo versions, and ensuring deletedAt/timestamps are correctly exposed or hidden by API Platform serialization groups. The companion repo epubli/api-platform-test appears to be the only validation harness; there is no evidence of CI, static analysis, or a version-compatibility matrix in this repository.

Technical risk — high, and mostly lifecycle risk rather than code risk.

• Staleness: last release 2020-04-21, 1 star, 0 dependents. This is a single-maintainer, effectively dormant package.
• Ecosystem drift: the traits and README are annotation-based. Doctrine ORM 3 / DBAL 4 and API Platform 3 moved to PHP attributes; annotation support is deprecated or removed. Adopting on any modern PHP 8.2+/API Platform 3 baseline will likely require forking and rewriting annotations as attributes.
• Supply chain: near-zero community scrutiny means no external security review, no CVE response, and no downstream crowd-testing of edge cases.
• Bus factor: 1. No SLA, no roadmap, no issue-triage signal.
• Mitigating factor: the code surface is tiny (~6 small traits). The cost of vendoring or reimplementing is hours, not weeks, which converts an unacceptable dependency risk into a trivial internal-code risk.

Key questions to resolve before committing.

1. Is the target application Symfony/API Platform or Laravel? If Laravel, close the evaluation.
2. Exact versions of PHP, Symfony, API Platform, Doctrine ORM/ODM, Gedmo, and stof bundle — and do the package's constraints (composer.json on the default branch, not the README) admit them?
3. Are we adopting the package as a dependency, or copying the traits in-repo? (Strong default: copy.)
4. What is the soft-delete data-exposure policy — are deletedAt and soft-deleted records serialized to API consumers?
5. License compatibility and whether the repo is archived.

Integration Approach

Stack fit. Valid only for Symfony + API Platform v2-style stacks with Doctrine. For Laravel/Eloquent, the equivalent (timestamps, soft deletes, UUID/ID traits) is already native and this package offers nothing. For Symfony without API Platform, the traits still work but the value proposition (API Platform conventions) evaporates.

Migration path. Two options, and the recommendation is the second:

1. Depend on the package: composer require, register the bundle, add the stof_doctrine_extensions config, annotate entities with @Gedmo\SoftDeleteable/@Gedmo\Timestampable, then use the traits. Fast, but inherits the staleness and annotation-era constraints.
2. Vendor the traits into the application (or an internal bundle) under our own ownership, rewriting annotations as PHP attributes if the stack is ORM 3 / API Platform 3. Preserves the convention, removes the abandoned dependency, and lets us extend the soft-delete filter behavior without upstream negotiation. This is the sequenced default.

Compatibility. The hard constraints are transitive: Gedmo doctrine-extensions version must match Doctrine ORM/DBAL; stof/doctrine-extensions-bundle must match Symfony; the ODM traits require doctrine/mongodb-odm and the Gedmo MongoDB extensions, which have a separate and stricter version ladder. SoftDeleteable additionally requires the Doctrine filter to be enabled per-entity-manager, or deletes silently behave as hard deletes. None of this is version-verified by the package itself.

Sequencing.

1. Confirm stack and lock the version matrix (PHP, Symfony, API Platform, Doctrine, Gedmo, stof).
2. Timeboxed spike in a throwaway branch: one entity with ORM Timestampable + SoftDeletable, one API Platform resource, exercise create/update/delete/read and confirm the filter.
3. Decide depend-vs-vendor based on whether the spike survives the version matrix unmodified.
4. Implement: traits in place, Gedmo annotations/attributes on the entity class (not the trait, per the README), filter enabled, serialization groups reviewed for deletedAt and timestamp exposure.
5. Add regression tests for soft-delete visibility and timestamp population — this is the coverage the package does not supply.
6. Document the internal fork and its divergence point.

Operational Impact

Maintenance. Treat as unmaintained. Expect no upstream fixes; plan for periodic manual review against Doctrine/API Platform upgrades. With a vendored copy, maintenance is a one-file diff per year at worst; as a dependency, it becomes a recurring upgrade blocker at every Doctrine/API Platform major.

Support. No vendor, no SLA, one maintainer, negligible community. Support is entirely internal: whoever owns the entity model owns these traits. Onboarding docs should state the fork provenance and why it exists, or the next engineer will try to swap in a Packagist package that no longer matches.

Scaling. The traits themselves are compile-time and cost nothing at runtime; the operational behavior comes from Gedmo listeners. Timestampable adds a prePersist/preUpdate listener — negligible. SoftDeleteable is the real scaling consideration: soft-deleted rows accumulate indefinitely (table growth, index bloat), unique constraints must be designed around deletedAt, and every query path must honor the filter. Under high write volume with frequent deletes, this needs a retention/purge job and a decision on hardDelete (the README example sets hardDelete=false).

Failure modes.

• Doctrine annotation support removed in ORM 3 / API Platform 3 → mapping failure at cache warmup, not at request time (fail-fast, at least).
• SoftDeleteable filter not enabled → deleted records silently returned by the API, a data-exposure incident.
• Serialization groups misconfigured → deletedAt or internal timestamps leaked in API payloads.
• Trait property collisions with existing entity fields (id, createdAt, deletedAt) → mapping conflicts.
• Gedmo/stof version skew → runtime listener errors or silent no-op timestamps.
• Timezone/locale drift in timestampable (default_locale: en_US in the README) producing inconsistent timestamps across environments.
• ODM variants carrying a separate and more fragile compatibility ladder than ORM.

Ramp-up. Low. A mid-level Symfony developer can read all six traits in under an hour; the actual learning curve is Gedmo configuration and Doctrine filter semantics, which they would need regardless of this package. The risk is not comprehension, it is the assumption of upkeep — a developer who treats this as a maintained dependency will be surprised at the first Doctrine major. Budget roughly half a day for the spike plus a day for tests and documentation, and near-zero for the traits themselves.