Repository Doctrine Laravel Package

Product Decisions This Supports

• Build vs. buy for xAPI (Experience API) persistence: this package is the Doctrine ORM bridge between the php-xapi domain model and your relational database. If your product needs to store/query xAPI Statements (LRS functionality, learning-record storage, analytics ingestion), this is the "don't build it yourself" option for the storage layer — you still own the API surface, auth, and query/business logic on top.
• Timing of adoption in the roadmap: v0.3.0 is a breaking release — MappedStatement/MappedVerb and MappedStatementRepository were removed from php-xapi/model and replaced by new mapping classes and a StatementRepository under XApi\Repository\Doctrine\Mapping. Any code, fixtures, or tests referencing the old class names must be migrated. Treat this as a planned refactor line item, not a drop-in upgrade.
• Stability signal for dependency planning: the bump to php-xapi/model ^1.0 and php-xapi/test-fixtures ^1.0 means the underlying domain model is now stable, which materially lowers the risk of the data model shifting under you. The repository layer itself (php-xapi/repository-api ^0.3, this package at 0.3.x) is still pre-1.0.
• Coverage decision: "mapping classes for all statement properties" is the feature that decides whether this package is usable for your product. Full property coverage means you can persist complete Statements (verbs, actors, objects, results, context, timestamps, authority, attachments metadata) rather than a lossy subset — which is the difference between supporting real xAPI conformance and supporting a demo.
• Vendor lock-in / exit-cost estimate: the value here is a thin, replaceable persistence adapter over a stable domain model. That means a future swap to a custom repository implementation or a managed LRS is a contained engineering effort, not a rewrite of product logic.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP with Doctrine ORM and need to persist xAPI Statements in your own relational schema (rather than buying a hosted LRS).
• You are comfortable pinning to a pre-1.0 repository layer and budgeting for periodic breaking upgrades — the package's own history shows class renames across minor versions.
• Your team can absorb the v0.3.0 migration (old Mapped* classes → XApi\Repository\Doctrine\Mapping\*, MappedStatementRepository → StatementRepository).
• You want the stable php-xapi/model 1.0 domain objects as your in-app representation, with this package as the persistence seam.

Look elsewhere when:

• You need a production-stable, versioned API contract today with no expected breaking changes — wait for 1.0 or budget an abstraction layer in front of it.
• You need a full LRS (HTTP endpoints, conformance, query API, auth) — this is storage plumbing, not an LRS. Consider a hosted LRS or a more complete implementation.
• Your stack is Eloquent-first and introducing Doctrine is a net-negative architectural change; the integration cost outweighs the reuse benefit.
• Your Statements are simple/append-only and a JSON column plus a small custom repository would cover 80% of the need.

How to Pitch It (Stakeholders)

To executives: This is a small, focused open-source component that saves us from hand-writing the database layer for xAPI learning records. The important signal in this release is that the underlying data model has reached a stable 1.0, which reduces the risk of our stored data schema churning. The persistence layer itself is still pre-1.0, so we should plan for occasional upgrade work rather than assume it is frozen.

To engineering: v0.3.0 is a breaking change. Mapping classes moved out of php-xapi/model into XApi\Repository\Doctrine\Mapping, and MappedStatementRepository is now StatementRepository under …\Repository\Mapping. All statement properties are now mapped, which closes the main functional gap for conformance-grade storage. Dependencies are now php-xapi/model ^1.0, php-xapi/test-fixtures ^1.0, and php-xapi/repository-api ^0.3. Recommendation: wrap the repository behind our own interface at the boundary so future renames stay contained, pin versions explicitly, and schedule the migration with tests that assert round-trip fidelity of every statement property.