Search by

adachsoft / item-list-contracts

Arkadiusz Adach

Storage-independent contracts for generic shared item lists (shopping, packing, to-do) with access policy and repository contract tests.

Package info

gitlab.com/a.adach/item-list-contracts

Issues

pkg:composer/adachsoft/item-list-contracts

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

v0.1.0 2026-11-22 19:28 UTC

This package is auto-updated.

Last update: 2026-11-22 18:31:59 UTC


README

Storage-independent contracts and immutable value objects for generic shared item lists. The model has no knowledge of shopping, units, prices, or any other list-specific domain.

Purpose

This package defines item-list IDs, item and list DTOs, repository and service interfaces, access-policy and change-listener interfaces, and an in-memory repository. Applications can persist complete lists through their own repository adapters while keeping application logic independent of storage technology.

The adachsoft/item-list package provides the service implementation and default access policy.

Installation

composer require adachsoft/item-list-contracts

Requirements

  • PHP ^8.3.
  • adachsoft/reference-contracts ^0.1.

The reusable repository contract test is available when PHPUnit is installed in the consuming project's development dependencies.

Model overview

An ItemListDto is a complete aggregate containing:

  • an opaque ItemListId, a trimmed name, and an owning PrincipalReference;
  • a collection of other principals with access;
  • an ordered ItemDtoCollection whose item positions are contiguous and zero-based;
  • creation and update timestamps, an optimistic-concurrency version, and optional subject and JSON-serializable metadata.

Items contain generic text, optional free-text quantity and note, checked state, optional checker and timestamp, and JSON-serializable metadata. The PrincipalReference and SubjectReference types come from adachsoft/reference-contracts.

Repository contract

ItemListRepositoryInterface stores and retrieves complete ItemListDto values. A save is accepted only when the stored version equals the incoming list version minus one. New lists therefore start at version 1; a conflict raises ConcurrentModificationException without changing stored data.

findByPrincipals() matches exact principal references and does not resolve group membership. Callers pass the expanded principal set. findBySubject() selects lists attached to the supplied subject. Both queries return lists ordered by creation time ascending and then by list identifier.

InMemoryItemListRepository is a simple implementation suitable for tests and lightweight use. Durable storage adapters can verify their behavior by extending AdachSoft\ItemListContracts\Testing\AbstractItemListRepositoryContractTest and implementing createRepository():

final class SqlItemListRepositoryTest extends AbstractItemListRepositoryContractTest
{
    protected function createRepository(): ItemListRepositoryInterface
    {
        return new SqlItemListRepository(/* test dependencies */);
    }
}

The contract covers version checks, retrieval, removal, principal and subject queries, deterministic ordering, and round-tripping all DTO fields (date-times must keep their instant with microseconds; the time zone may change).

Access operations

ItemListOperationEnum distinguishes VIEW, EDIT, and MANAGE operations. ItemListAccessPolicyInterface lets an application decide whether a principal may perform an operation on a list. The service contract requires access checks for applicable operations and reports denied access with ItemListAccessDeniedException.

Change listener

An ItemListChangeListenerInterface receives the before and after list values after a successful change. A null before value represents creation; a null after value represents deletion. No notification is made for no-op operations.

Example

See Building a list with the in-memory repository for a complete DTO and repository example.