Contracts

All interfaces of the Jardis platform, one package, zero implementations.

Introduction

In a hexagonal architecture, everything depends on interfaces: domain code imports only contracts, adapters implement them, and wiring happens at boot time. When these interfaces are scattered across dozens of packages, circular dependencies and release chaos arise.

jardissupport/contracts solves this radically: a single package contains all interfaces, enums, Value Objects and exceptions of the entire Jardis platform. Not a single implementation. Every Jardis package (whether Core, Adapter, Support or Tools) imports jardissupport/contracts and finds its contracts there.

• Zero implementations — interfaces, enums and base exceptions only
• Single source of truth — one dependency instead of dozens
• PSR-first — PSR-3 (Log), PSR-11 (Container), PSR-14 (Events), PSR-16 (Cache), PSR-18 (HTTP) where standards exist
• Interface Segregation — Reader/Writer separation, granular query builder interfaces

Installation

composer require jardissupport/contracts

GitHub: jardisSupport/contracts

This package is automatically installed as a dependency of all Jardis packages.

AI

AI assistance included

This package ships an AI skill. Run composer require --dev jardis/dev-skills — and your agent knows the API.

Learn more about Jardis Skills →

Namespace Structure

All interfaces live under JardisSupport\Contract\:

JardisSupport\Contract\
├── Auth\              ← Authentication, RBAC, sessions, tokens
├── ClassVersion\      ← Versioned class resolution
├── Connection\        ← Base lifecycle (connect/disconnect)
├── Data\              ← Hydration, identity, FieldMapper
├── DbConnection\      ← PDO connections, connection pool
├── DbQuery\           ← SQL query builder
├── DbSchema\          ← Schema analysis
├── DotEnv\            ← Environment variables
├── EventListener\     ← Event listener registration
├── Filesystem\        ← Filesystem abstraction
├── Kernel\            ← DDD kernel, BoundedContext, responses
├── Mailer\            ← Email sending
├── Messaging\         ← Multi-transport messaging
├── Repository\        ← Generic CRUD
├── Scheduling\        ← Cron and task scheduling
├── Secret\            ← Encryption
├── Validation\        ← Object validation
└── Workflow\          ← Multi-step processes

Interface Overview by Domain

Kernel

The heart of the DDD architecture:

Interface	Description
DomainKernelInterface	Service locator for BoundedContexts — nullable PSR services + Jardis services
BoundedContextInterface	handle(className, ...params): mixed — pass-through resolver, inherits payload+version. context(className, payload, version): mixed — fresh BC entry point, accepts only BC subclasses
ContextResponseInterface	Mutable carrier for data, events, errors and sub-results
DomainResponseInterface	Immutable final response with HTTP-like status

Auth

Interface / Enum	Description
AuthenticatorInterface	authenticate(Credential): AuthResult
GuardInterface	check(session, permission): bool, authorize(session, permission): void
SessionInterface	Authenticated session with identity and metadata
PasswordHasherInterface	hash(), verify()
TokenStoreInterface	Token persistence: store(), find(), revoke(), revokeAllForSubject()
HashedTokenInterface	Stored token hash
CredentialInterface	Login credential (password, API key, token)
CredentialType	Enum: Password, ApiKey, Token
TokenType	Enum: Access, Refresh, ApiKey, Verification, PasswordReset

Data

Interface	Description
HydrationInterface	Entity hydration, change tracking, clone, diff, toArray
IdentityInterface	UUID v4/v5/v7, NanoID
FieldMapperInterface	Bidirectional key translation

Repository

Interface / Class	Description
RepositoryInterface	insert(), update(), delete(), findById(), findByQuery(), exists()
PkStrategy	Enum: AUTOINCREMENT, INTEGER, NONE
PersistException	Exception on write errors
RecordNotFoundException	Exception when record is not found

DbConnection

Interface	Description
DbConnectionInterface	PDO wrapper with transactions and reconnect
ConnectionPoolInterface	Read/write splitting with health checks
DatabaseConfigInterface	DSN, credentials, options

DbQuery

Granular interfaces for the SQL builder:

Interface	Description
DbQueryBuilderInterface	SELECT (CTE, window, subquery, union, ...)
DbInsertBuilderInterface	INSERT
DbUpdateBuilderInterface	UPDATE + WHERE
DbDeleteBuilderInterface	DELETE + WHERE
DbWhereConditionInterface	WHERE, AND, OR, JSON conditions
DbQueryConditionBuilderInterface	Comparison operators
DbJoinInterface	INNER/LEFT JOIN
DbOrderLimitInterface	ORDER BY, LIMIT, OFFSET
DbWindowBuilderInterface	Window functions
DbSqlGeneratorInterface	toSql(), getBindings()

Filesystem

Interface	Description
FilesystemInterface	Combines reader + writer
FilesystemReaderInterface	read(), readStream(), exists(), size(), mimeType(), listContents()
FilesystemWriterInterface	write(), writeStream(), delete(), copy(), move(), createDirectory()
FilesystemServiceInterface	Factory for filesystem instances
FileInfoInterface	DTO for directory listing

Messaging

Interface / Class	Description
MessagingServiceInterface	Facade: publish() + consume()
MessagePublisherInterface	Publisher
MessageConsumerInterface	Consumer
MessageHandlerInterface	Callback contract
MessageException	Base exception
ConnectionException	Broker connection error
PublishException	Publish error
ConsumerException	Consume error

Further Domains

Domain	Interfaces
Scheduling	ScheduleInterface, ScheduledTaskInterface, CronExpressionInterface, ConstraintInterface, ScheduleViolation
Validation	ValidatorInterface, ValueValidatorInterface, ValidationResult
Workflow	WorkflowInterface, WorkflowBuilderInterface, WorkflowNodeBuilderInterface, WorkflowConfigInterface, WorkflowContextInterface, WorkflowResultInterface
Mailer	MailerInterface, MailMessageInterface, MailTransportInterface, MailerExceptionInterface
DotEnv	DotEnvInterface
Secret	SecretResolverInterface, SecretResolutionException
ClassVersion	ClassVersionInterface, ClassVersionConfigInterface
Connection	ConnectionInterface (base lifecycle)
EventListener	EventListenerRegistryInterface (gap in PSR-14: listener registration)

Design Principles

PSR-first

DomainKernelInterface injects PSR interfaces directly:

• PSR-3 LoggerInterface for logging
• PSR-11 ContainerInterface for service resolution
• PSR-14 EventDispatcherInterface for events
• PSR-16 CacheInterface for caching
• PSR-18 ClientInterface for HTTP

Jardis contracts only exist where no PSR standard applies.

Nullable Services

All infrastructure services in the kernel are nullable:

$cache = $kernel->cache();           // ?CacheInterface
$logger = $kernel->logger();          // ?LoggerInterface
$mailer = $kernel->mailer();          // ?MailerInterface

Domain code must check availability. No service is guaranteed.

Reader/Writer Separation

// Read-only BoundedContext receives only the reader
public function __construct(
    private readonly FilesystemReaderInterface $storage,
) {}

// Full-access service receives both
public function __construct(
    private readonly FilesystemInterface $storage,
) {}

Enum-based Strategies

use JardisSupport\Contract\Repository\PrimaryKey\PkStrategy;

$repository->insert('users', 'id', $values, PkStrategy::NONE);

Instead of string constants, all strategies and types use PHP 8.1+ enums.

Dependency Direction

JardisTools   → JardisAdapter → JardisSupport → JardisCore
                    |                |               |
          JardisSupport\Contract ←←←←←←←←←←←←←←←←←←

All arrows point inward toward the contract package. Domain code never imports adapter code directly.