Download the PHP package kumwe/sequence without Composer

Kumwe Sequence

Portable numbering format, reset and scope values, and the allocator port. The host reserves the numbers; this package says what they mean.

Kumwe Sequence defines document numbering for the Kumwe family: the declaration an allocated-number field carries (NumberSequenceFormat, with its NumberSequenceReset and NumberSequenceScope vocabularies), the counter coordinates that declaration composes, the rendering of a reserved value into the number a person reads, and NumberSequenceAllocator, the storage-neutral port a host implements to reserve the next value inside its own transaction. The package ships no allocator implementation of any kind: the counter store, its locks, its deadlock retry and its database evidence all stay in the host that owns the store.

Responsibility and non-goals

This package owns:

• the declaration grammar and its bounds — scope, reset, prefix, padding and timezone, what each admits, what each refuses and what it defaults to;
• the counter coordinates a declaration composes for a record scope and an instant, and the period keys at their calendar boundaries in the declared zone;
• deterministic rendering of a reserved value, and the refusal of a value the format cannot hold;
• the allocator port with its gapless-on-commit promise stated exactly, and the one refusal an allocation answers with;
• their complete documentation, the three machine-readable manifests and the tests that pin all of it.

It does not own, and will refuse:

• any allocator implementation, counter store, transaction, lock, fence, unique-index arbitration or retry;
• business numbering policy — which documents are numbered, what an invoice or stock number is, repair;
• a fiscal calendar: a fiscal-period key is a posting period the host declared;
• site and organization authority: the record scope a counter is keyed by is the host's to resolve;
• container registration: there is no ConfigProvider, factory or alias here (see below);
• real-database evidence, which the host proves on the engines it supports.

Installation and supported platforms

PHP ^8.5 and nothing else: the runtime requirement is php alone, with no extension and no Composer dependency. While the package is pre-1.0 a consumer pins an exact version, as docs/releasing.md explains.

Canonical namespace

Kumwe\Sequence\ is the one canonical root, autoloaded PSR-4 from src/. Values live under Kumwe\Sequence\Value\, the port under Kumwe\Sequence\Contract\, the refusal under Kumwe\Sequence\Exception\. There is no alias, historical namespace or compatibility root.

Five-minute example

The service never sees a store. counter() names exactly one counter from the declaration, the record's organization and the instant; allocate() reserves its next value inside the transaction the caller already holds; render() turns that value into the printed number. A runnable version against an in-memory reference allocator is examples/allocate-and-render.php.

Dependency injection: no provider, by design

This is a value and port package. It exports three directly constructible values, one interface and one exception, and no runtime service with collaborators, so it ships no Laminas/Mezzio ConfigProvider, no factory and no alias: an empty provider would be ceremony, not integration. Values are built from a declaration with NumberSequenceFormat::fromConfiguration(); enums are used as cases; the refusal is thrown by an adapter. The host constructs its allocator adapter and binds it to the port identifier itself, as Kumwe App does in its composition root:

The adapter is request- or operation-supplied in the package standard's vocabulary: it is bound to one connection whose open transaction every allocation joins, and it must never be shared across threads or processes. resources/service-map/v1.json records the absence and its reason; docs/integration.md walks through the binding and what the host must prove.

Public surface

No factories, no aliases, no configuration keys, no defaults: there is nothing to configure. Every symbol and member is documented in docs/public-api.md and pinned in resources/public-api/v1.json, enum cases included; composer manifests refuses drift. Capabilities are recorded in resources/capabilities/v1.json.

Guarantees

• Errors and refusals. A declaration that is not in the grammar, a per-organization counter with no organization, a fiscal reset asked for a calendar key, a non-positive value, or a value the column cannot hold is refused with InvalidArgumentException — an argument error, exactly as the App refused it. The port declares one refusal, NumberSequenceUnavailable: the counter cannot be reserved now, nothing was consumed, replay. An adapter translates its driver's contention into that type and keeps the original reachable as the previous exception; it never lets a driver class escape the port.
• Mutability. NumberSequenceFormat is final readonly; the enums are cases; the exception carries nothing but its fixed message and the chained cause. Nothing in the package holds state between calls.
• Determinism. render() is a pure function of its arguments. counter() reads only the instant it is handed and the declared zone — never the process default zone, never a clock. The keys are the same on every replica for the same instant.
• Precision and canonicalization. Padding is a minimum width, never a truncation: a value wider than its padding renders in full until the column limit refuses it. Prefix and period key render verbatim.
• Bounds. Prefix up to 16 of A-Z 0-9 - /; padding 1 to 12 digits; the widest rendered number is 36 characters, and a host sizes its column to NumberSequenceFormat::MAXIMUM_LENGTH.
• Transaction expectations. allocate() runs inside the transaction the caller already opened and must not open its own; the reservation commits or rolls back with the command. Within one counter, committed records are numbered contiguously from one; a rolled-back command consumes nothing; a replayed idempotent command allocates nothing; numbers are never re-used, so a hard delete leaves a hole nothing fills.
• Concurrency and process safety. The values are immutable and safe to share. An adapter holds the counter exclusively until its transaction ends, so concurrent commands against one counter serialize — the price of contiguity, and the reason scope and reset are chosen deliberately. An adapter is bound to one connection and is not shared across threads or processes.

Extension and replacement points

NumberSequenceAllocator is the extension point: a host implements it once per store technology. The three values and the exception are final; a new scope or reset case is a reviewed change to this package with a new version, never a subclass or a host-side copy. A consumer that needs an in-memory allocator for its own tests writes one against the port, as the example and the suite do.

Core contract and compatibility

Kumwe\App\BusinessDefinition\Domain\NumberSequenceFormat, NumberSequenceReset and NumberSequenceScope become Kumwe\Sequence\Value\NumberSequenceFormat, NumberSequenceReset and NumberSequenceScope, with the reserved-key refusal described below. Kumwe\App\BusinessRecord\Application\BusinessNumberSequenceAllocator becomes Kumwe\Sequence\Contract\NumberSequenceAllocator with the same signature and parameter names; its @throws moves from the App's BusinessRecordTemporarilyUnavailable to the package's NumberSequenceUnavailable, so the App's adapter raises the package refusal and the App's record service translates it into its own retryable exception at the port boundary. The Doctrine adapter, the kernel binding, the definition validator, the posting-period calendar and every database test stay in the App. The release record preserves exact historical source mappings and consumer qualification requirements. Review drift against current Core before replacing old types. The reserved organization key - is rejected as of 0.2.0 to keep organization and site-wide counters disjoint.

Testing and clean-consumer commands

The lane is described in docs/architecture.md; the archive and clean-consumer proof in docs/releasing.md.

Release, compatibility, security and license

Releases are on the record: the newest ## X.Y.Z heading in CHANGELOG.md is the release a merge to main publishes, as docs/releasing.md describes. Compatibility follows semantic versioning with exact consumer pins while pre-1.0. Security policy and scope are in Apache License, Version 2.0.