README

Shared kernel value objects and domain abstractions for building domain-driven PHP applications.

📦 Installation

Require the package via Composer:

composer require schorts/shared-kernel

Composer will autoload classes under the namespace:

Schorts\SharedKernel\

For example, classes in src/ValueObjects/ are available under:

use Schorts\SharedKernel\ValueObjects\EmailValue;

🧩 Features

Value Objects

Immutable primitives with validation and equality logic:
- ArrayValue
- BooleanValue
- CoordinatesValue
- DateValue
- EmailValue
- EnumValue
- FloatValue
- IntegerValue
- ObjectValue
- PhoneValue
- SlugValue
- StringValue
- URLValue
- UUIDValue
Domain Events
- DomainEvent base class with metadata and primitives serialization.
- DomainEventMetadata and DomainEventPrimitives DTOs.
Entities
- Entity base class with identity and domain event recording.
Aggregate Roots
- AggregateRoot abstract class with versioning, uncommitted-change tracking, domain-event recording / pulling (with sequence numbers), snapshots and fromPrimitives / fromSnapshot factory methods.
DAO Abstraction
- DAO contract for persistence operations with support for UnitOfWork and delete modes.
CQRS – Queries
- Query interface and AbstractQuery base class with metadata, correlation/causation IDs, headers and context.
- QueryMetadata and QueryPrimitives DTOs.
- Built-in error types:
  - QueryNotRegistered
  - QueryAlreadyRegistered
CQRS – Query Handlers
- QueryHandler interface (validate → authorize → execute pipeline).
- AbstractQueryHandler with optional caching, logging and metrics support.
- QueryHandlerOptions and QueryHandlerContext DTOs.
- Pluggable Cache and Logger contracts.
- Built-in error types:
  - QueryAuthorizationError
  - QueryExecutionError
  - QueryValidationError
CQRS – Query Bus
- QueryBus interface for registering handlers and dispatching queries.
- InMemoryQueryBus implementation with middleware support.
- QueryBusMiddleware, QueryBusContext and QueryBusConfig.
- Bulk dispatch (dispatchMany) with AggregateError on partial failures.
i18n
- TranslationResolver contract for localised messages.

🚀 Usage

Example: Creating a Value Object

use Schorts\SharedKernel\ValueObjects\EmailValue;

class UserEmail extends EmailValue {
  public function getAttributeName(): string {
    return 'user_email';
  }
}

$email = new UserEmail('test@example.com');

if ($email->isValid()) {
  echo "Valid email: " . $email;
}

Example: Defining a Domain Event

use Schorts\SharedKernel\DomainEvent\DomainEvent;

class UserRegisteredEvent extends DomainEvent {
  public function getEventName(): string {
    return 'user.registered';
  }
}

Example: Entity with Domain Events

use Schorts\SharedKernel\Entity\Entity;
use Schorts\SharedKernel\ValueObjects\ValueObject;
use Schorts\SharedKernel\Model\Model;

class UserEntity extends Entity {
  public function toPrimitives(): Model {
    // return DTO representation
  }
}

Example: Aggregate Root

use Schorts\SharedKernel\AggregateRoot\AggregateRoot;
use Schorts\SharedKernel\ValueObjects\UUIDValue;
use Schorts\SharedKernel\DomainEvent\DomainEvent;

final class UserId extends UUIDValue
{
  public function getAttributeName(): string
  {
    return 'user_id';
  }
}

final class UserRegistered extends DomainEvent
{
  public function getEventName(): string
  {
    return 'user.registered';
  }
}

/**
 * @extends AggregateRoot<UserId>
 */
final class User extends AggregateRoot
{
  private string $email;
  private string $name;

  public function __construct(UserId $id, string $email, string $name, int $version = 0)
  {
    parent::__construct($id, $version);

    $this->email = $email;
    $this->name = $name;
  }

  public static function register(UserId $id, string $email, string $name): self
  {
    $user = new self($id, $email, $name);
    $user->recordDomainEvent(new UserRegistered(/* … */));

    return $user;
  }

  public function toPrimitives(): array
  {
    return [
      'email' => $this->email,
      'name' => $this->name,
    ];
  }

  protected function restoreFromPrimitives(array $data): void
  {
    $this->email = $data['email'];
    $this->name = $data['name'];
  }
}

// Create & record events
$user = User::register(new UserId('…'), 'john@example.com', 'John');

// Pull events (with sequence numbers) and clear the internal buffer
$events = $user->pullDomainEvents();

// Snapshot / restore
$snapshot = $user->toSnapshot();
$restored = User::fromSnapshot($snapshot);

Example: Defining a Query

use Schorts\SharedKernel\Query\AbstractQuery;

final class GetUserByIdQuery extends AbstractQuery
{
  public function __construct(
    public readonly string $userId,
    string $correlationId,
    ?array $customMetadata = null,
  ) {
    parent::__construct($correlationId, $customMetadata);
  }

  public function getType(): string
  {
    return 'user.get_by_id';
  }

  public function toPrimitives(): \Schorts\SharedKernel\Query\QueryPrimitives
  {
    $primitives = parent::toPrimitives();
    // You can enrich payload here if needed
    return $primitives;
  }
}

Example: Implementing a Query Handler

use Schorts\SharedKernel\Query\AbstractQueryHandler;
use Schorts\SharedKernel\Query\QueryHandlerContext;

/**
 * @extends AbstractQueryHandler<GetUserByIdQuery, array>
 */
final class GetUserByIdHandler extends AbstractQueryHandler
{
  public function execute(Query $query, QueryHandlerContext $context): mixed
  {
    /** @var GetUserByIdQuery $query */
    // Fetch user from repository / DAO …
    return [
      'id' => $query->userId,
      'name' => 'John Doe',
    ];
  }

  // Optional overrides:
  // public function validate(Query $query): void { … }
  // public function authorize(Query $query): void { … }
  // public function getCacheKey(Query $query): ?string { … }
}

Example: Using the Query Bus

use Schorts\SharedKernel\Query\InMemoryQueryBus;
use Schorts\SharedKernel\Query\QueryBusConfig;

$bus = new InMemoryQueryBus();

$bus->register('user.get_by_id', new GetUserByIdHandler(
  new \Schorts\SharedKernel\Query\QueryHandlerOptions(
    cache: true,
    cacheTtl: 300_000, // 5 minutes
    logging: true,
  )
));

// Optional middleware
$bus->use(new class implements \Schorts\SharedKernel\Query\QueryBusMiddleware {
  public function beforeDispatch(Query $query, \Schorts\SharedKernel\Query\QueryBusContext $context): void
  {
    // e.g. start timer, add tracing span
  }

  public function afterDispatch(Query $query, mixed $result, \Schorts\SharedKernel\Query\QueryBusContext $context): void
  {
    // e.g. record metrics
  }

  public function onError(Query $query, \Throwable $error, \Schorts\SharedKernel\Query\QueryBusContext $context): void
  {
    // e.g. log / alert
  }
});

$query = new GetUserByIdQuery(
  userId: 'user-123',
  correlationId: 'corr-abc-123',
);

$result = $bus->dispatch($query);

Example: Bulk Dispatch

$results = $bus->dispatchMany([
  new GetUserByIdQuery('user-1', 'corr-1'),
  new GetUserByIdQuery('user-2', 'corr-2'),
]);

📜 License

LGPL-3.0-or-later

schorts / shared-kernel

Maintainers

Package info

Statistics

Security