Repository Api Laravel Package

Product Decisions This Supports

• Build vs. buy for xAPI persistence. v0.3.0 clarifies the contract: the package now ships a StatementRepositoryInterface that "defines the public API of a statement repository," and you "have to implement the StatementRepositoryInterface and handle Statement classes directly instead." That is a decision point: adopt the abstraction and write your own storage (e.g., Eloquent/MySQL), or take the Doctrine route via php-xapi/repository-doctrine.
• Scope/roadmap confidence. This release removes MappedStatement, MappedVerb, and the base StatementRepository class and shifts Doctrine-specific mapping to a sibling package. It signals the maintainers are separating the protocol/domain layer from ORM concerns — good for long-term portability, but it also confirms this package is still pre-1.0 and still churning.
• Upgrade gating and sprint planning. Breaking API changes affect anyone with a working integration:
  • StatementRepositoryInterface::findStatementById() now takes a StatementId (was a string).
  • findVoidedStatementById() now takes a StatementId.
  • storeStatement() now returns a StatementId (was a string).
  • NotFoundException now comes from php-xapi/exception, not this package. These are mechanical but non-trivial refactors that must be scheduled, not assumed away.
• Standards/interop strategy. The bump to php-xapi/model ^1.0 and php-xapi/test-fixtures ^1.0 means you are now building on stable releases of the domain model and the conformance fixtures — a meaningful de-risking signal for xAPI (Tin Can) / LRS-facing features such as learning analytics, activity tracking, and LMS integration.
• Feature scoping for Laravel products. Because there is no first-party Eloquent implementation, "support xAPI" is not a drop-in feature; it is a small vertical slice of work (schema, mapping, voiding semantics, ID generation).

When to Consider This Package

Consider it when:

• You are building a PHP/Laravel product that must emit or consume xAPI statements and you want a repository abstraction that is explicitly decoupled from a specific ORM.
• You want to define your own persistence layer (Eloquent, raw PDO, a remote LRS client) behind StatementRepositoryInterface rather than inheriting Doctrine mappings.
• You are comfortable pinning to a pre-1.0 package and tracking breaking releases; v0.3.0 is a good moment to start because the model and fixtures dependencies are now on stable ^1.0.
• You need the voiding semantics (findVoidedStatementById) and stable statement identifiers represented as first-class StatementId value objects rather than loose strings.

Look elsewhere when:

• You want Doctrine. Use php-xapi/repository-doctrine, which now owns MappedStatement and MappedVerb. Adopting this package to then re-add Doctrine mapping is wasted work.
• You expect a Laravel-ready repository. This package does not provide one; budget engineering time to build and maintain it, including migrations, indexing, and void-handling tests. Evaluate whether a full LRS product is a cheaper buy.
• You need a complete LRS server or HTTP/API layer. This is a persistence abstraction, not an LRS; the scope gap is large.
• You require post-1.0 API stability, LTS support, or vendor SLAs. Pre-1.0 plus a release that deletes public classes is a reasonable signal to wait or to vendor-and-fork.
• Your stack is pinned to older PHP versions. StatementId type hints imply a modern, typed runtime; verify your minimum PHP version against the package constraints before committing.

How to Pitch It (Stakeholders)

For executives: This is a small, standards-aligned library for storing xAPI learning statements, and the new release is a deliberately breaking reorganization that pushes ORM-specific code out into a sibling package and leaves behind a clean, explicit interface plus stable ^1.0 model and test-fixture dependencies. It is cheap to adopt and low-lock-in — but it is pre-1.0 with real API churn, so the ask is a modest, time-boxed engineering investment (roughly one sprint) to implement StatementRepositoryInterface against our own database, plus a standing commitment to pin versions and absorb breaking releases. Recommendation: adopt for a scoped xAPI use case, do not build a platform strategy on it yet, and re-evaluate at 1.0.

For engineering: v0.3.0 is a breaking release. MappedStatement, MappedVerb, and StatementRepository are gone (moved to php-xapi/repository-doctrine); NotFoundException now comes from php-xapi/exception; statement IDs are StatementId value objects across findStatementById(), findVoidedStatementById(), and the return of storeStatement(). The new StatementRepositoryInterface is the integration point — implement it directly on Eloquent and map Statement objects yourself, or adopt the Doctrine package wholesale. Migration is mostly mechanical signature work, but the void-handling and ID-generation paths need test coverage; lean on php-xapi/test-fixtures ^1.0 for conformance. Pin to an exact version and expect further breaking changes before 1.0.