adachsoft / item-list
Generic shared item lists (shopping, packing, to-do): service with access policy based on principal membership, storage through repository adapters.
Requires
- php: ^8.3
- adachsoft/item-list-contracts: ^0.1
- adachsoft/principal-contracts: ^0.2
- adachsoft/reference-contracts: ^0.1
- psr/clock: ^1.0
Requires (Dev)
- adachsoft/php-code-style: ^0.7.3
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^13.4
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
adachsoft/item-list provides storage-independent operations for generic shared lists. The package treats entries as plain text and does not impose shopping-specific concepts such as prices, units, or product catalogs.
Installation
composer require adachsoft/item-list
Requirements
The package requires PHP and installs its runtime dependencies through Composer: adachsoft/item-list-contracts, adachsoft/principal-contracts, adachsoft/reference-contracts, and psr/clock.
Usage
Quick start
The factory uses the membership-based access policy, a system clock, a random identifier generator, and a no-op change listener by default. This example creates a shopping list, shares it with a group, adds entries, and checks an item:
<?php
declare(strict_types=1);
use AdachSoft\ItemList\ItemListServiceFactory;
use AdachSoft\ItemListContracts\InMemory\InMemoryItemListRepository;
use AdachSoft\PrincipalContracts\CompositeMembershipResolver;
use AdachSoft\ReferenceContracts\PrincipalReference;
require __DIR__ . '/vendor/autoload.php';
$service = ItemListServiceFactory::create(
new InMemoryItemListRepository(),
new CompositeMembershipResolver([]),
);
$owner = new PrincipalReference('account', 'alex');
$household = new PrincipalReference('group', 'household');
$list = $service->createList($owner, 'Shopping list');
$list = $service->share($owner, $list->id, $household);
$list = $service->addItem($owner, $list->id, 'Oats', 'one bag');
$list = $service->addItem($owner, $list->id, 'Apples', 'six');
$firstItem = $list->items->toArray()[0];
$list = $service->checkItem($owner, $list->id, $firstItem->id);
With an empty membership resolver, the owner can perform these operations directly. Configure a membership provider to let account members inherit access through a shared group. See the runnable group-sharing example.
Default access rules
The actor's membership set includes the actor and any principals that contain it. The default policy applies these rules:
| Operation | Allowed when |
|---|---|
VIEW | The actor's membership set contains the list owner or any shared principal. |
EDIT | The same principals allowed to VIEW may edit the list. |
MANAGE | The actor's membership set contains the list owner. |
A custom ItemListAccessPolicyInterface can define different rules.
No-op behavior
Operations that would not change a list return the existing list without saving it or notifying the listener. No-ops include renaming to the current trimmed name, sharing with the owner or an already-shared principal, unsharing a principal that is not shared, checking an already-checked item, unchecking an unchecked item, clearing a list with no checked items, and moving an item to its current position.
Change listener
Pass an ItemListChangeListenerInterface to the factory to receive successful changes. The listener receives the list before and after a change; creation has a null before value and deletion has a null after value. No-op operations do not notify it. When omitted, the service uses a no-op listener.
Storage adapters
Implement ItemListRepositoryInterface from adachsoft/item-list-contracts to store complete list aggregates. Verify an adapter by extending AdachSoft\ItemListContracts\Testing\AbstractItemListRepositoryContractTest, implementing createRepository(), and running the resulting test class with PHPUnit.
final class YourItemListRepositoryTest extends AbstractItemListRepositoryContractTest
{
protected function createRepository(): ItemListRepositoryInterface
{
return new YourItemListRepository(/* test dependencies */);
}
}
The contract test checks repository behavior such as version handling, retrieval, removal, principal and subject queries, ordering, and preservation of list data.
Custom components
The factory accepts custom listeners, clocks, and identifier generators:
$service = ItemListServiceFactory::create(
$repository,
$memberships,
listener: $listener,
clock: $clock,
idGenerator: $idGenerator,
);
Use a PSR clock through ClockInterface and implement IdGeneratorInterface for custom identifiers. To use a custom access policy, construct ItemListService directly with your ItemListAccessPolicyInterface, membership resolver, repository, identifier generator, clock, and optional listener.