Repository Api Laravel Package

Getting Started

This package provides the xAPI statement repository contract and related domain wiring used to persist and retrieve Statement objects. It is not an Eloquent package and ships no Laravel migrations or models; you own the storage layer.

Start by looking at:

• StatementRepositoryInterface in the installed package source.
• php-xapi/model v1.0 Statement and StatementId classes.
• php-xapi/exception v1.0 NotFoundException.
• php-xapi/test-fixtures v1.0 for repository tests.

Minimal setup for a Laravel app:

composer require php-xapi/repository:^0.3
composer require --dev php-xapi/test-fixtures:^1.0

Confirm Composer resolves:

composer show php-xapi/model php-xapi/exception php-xapi/test-fixtures

The first practical use case is implementing an Eloquent-backed repository:

use XApi\Model\Statement;
use XApi\Model\StatementId;
use XApi\Exception\NotFoundException;
use XApi\Repository\StatementRepositoryInterface;

class EloquentStatementRepository implements StatementRepositoryInterface
{
    public function storeStatement(Statement $statement): StatementId
    {
        // Persist the statement, then return its StatementId.
    }

    public function findStatementById(StatementId $statementId): Statement
    {
        // Load by string id, hydrate and return a Statement.
    }

    public function findVoidedStatementById(StatementId $voidedStatementId): Statement
    {
        // Load the voided statement or throw NotFoundException.
    }
}

Bind the interface in a service provider:

$this->app->bind(
    StatementRepositoryInterface::class,
    EloquentStatementRepository::class
);

Implementation Patterns

Use the interface as the integration boundary. Controllers, jobs, and services should depend on StatementRepositoryInterface, not on a concrete repository or removed base class.

Convert strings to StatementId at the edge of your application:

use XApi\Model\StatementId;

$statementId = new StatementId($request->route('statementId'));
$statement = $repository->findStatementById($statementId);

Keep the repository thin and map between xAPI domain objects and your Laravel persistence model:

• Store a JSON payload column for the original statement plus indexed columns for id, verb id, actor, timestamp, and voiding status.
• Hydrate a Statement from the stored payload before returning it.
• Return a StatementId from storeStatement(), not a raw string.
• Throw XApi\Exception\NotFoundException when a lookup misses, not a Laravel ModelNotFoundException.
• Wrap writes in a transaction when storing related statement data.

A typical controller flow:

public function store(StoreStatementRequest $request, StatementRepositoryInterface $repository)
{
    $statement = $this->statementFactory->fromRequest($request);
    $statementId = $repository->storeStatement($statement);

    return response()->json(['id' => (string) $statementId], 201);
}

For tests, use php-xapi/test-fixtures to build valid statements and assert against StatementId instances:

$id = $repository->storeStatement($fixtureStatement);

$this->assertInstanceOf(StatementId::class, $id);

If you use Doctrine, use php-xapi/repository-doctrine instead of implementing Doctrine mapping in this package. For Laravel, an Eloquent or query-builder-backed implementation is usually the shortest path.

Gotchas and Tips

• v0.3.0 is a breaking release. Remove or replace usages of MappedStatement, MappedVerb, and the old StatementRepository base class. Doctrine users should move mapping concerns to php-xapi/repository-doctrine.
• Method signatures now use StatementId objects. Passing strings to findStatementById() or findVoidedStatementById() will cause type errors. Cast route parameters and request input before calling the repository.
• storeStatement() now returns a StatementId, not a string. Update callers, tests, and JSON responses accordingly.
• Catch XApi\Exception\NotFoundException, not the old package-local exception. Grep for the old namespace after upgrading.
• The release notes mention extending a base StatementRepository class while also saying it was removed. Verify your installed vendor tree. Treat StatementRepositoryInterface as the stable target; if your code extended the old base class, replace it with your own implementation.
• Composer constraints matter: this release expects php-xapi/model and php-xapi/test-fixtures at ^1.0. Mixed old/new xAPI packages commonly produce signature and class-not-found errors. Use composer why-not php-xapi/model 1.0 when resolution fails.
• In Laravel, bind StatementRepositoryInterface in a service provider. Do not bind the removed concrete class. Keep the repository stateless so it can be resolved normally or as a singleton without request leakage.
• Do not return StatementId objects directly from Laravel JSON responses unless your response layer casts them to strings.
• Map database misses to NotFoundException deliberately. Let unexpected database errors surface or convert them to your application’s error contract, but do not silently return empty statements.
• Debug upgrade failures by grepping for MappedStatement, MappedVerb, StatementRepository, old NotFoundException, and string-based statement id assumptions. Then run repository tests against StatementId values.