README

Interface library providing domain foundation contracts for Domain-Driven Design (DDD) applications. This package contains strictly typed PHP 8.2+ interfaces defining the boundaries for bounded contexts, workflows, and domain-level abstractions.

Installation

composer require jardispsr/foundation

Requirements

PHP >= 8.2
jardispsr/dbconnection ^1.0
jardispsr/dbquery ^1.0
jardispsr/factory ^1.0
jardispsr/messaging ^1.0
jardispsr/validation ^1.0
psr/simple-cache ^3.0
psr/log ^3.0

Architecture Overview

This library provides the foundational contracts for implementing Domain-Driven Design patterns with a focus on type safety and clear separation of concerns.

Core Interfaces

DomainKernelInterface

Central service container providing access to infrastructure components:

Path Resolution: Application and domain root paths (getAppRoot(), getDomainRoot())
Environment: Configuration and environment variable access (getEnv(?string $key))
Services: Factory (getFactory()), Cache PSR-16 (getCache()), Logger PSR-3 (getLogger())
Infrastructure: Database service (getDatabase()), Data service (getDataService()), Messaging (getMessage())
Resource Registry: Optional external resource sharing via ResourceRegistryInterface

ResourceRegistryInterface

External resource management for legacy integration:

Purpose: Share existing connections (PDO, Redis, Kafka) with Foundation to avoid duplication
Operations: register(), has(), get(), unregister(), all()
Key Conventions:
- Database: connection.pdo.writer, connection.pdo.reader1
- Cache: connection.redis.cache
- Messaging: connection.redis.messaging, connection.kafka.producer, connection.amqp
- Logging: logger.handler.{name}
Use Case: Legacy applications can inject existing infrastructure instances into DomainKernel, ensuring consistent state across old and new code

BoundedContextInterface

Generic type-safe use case executor:

public function handle(string $className, mixed ...$parameters): mixed;

Instantiates and executes handlers within a bounded context, supporting dependency injection and flexible parameter passing.

WorkflowInterface + WorkFlowConfigInterface

Multi-step workflow orchestration:

Executes through BoundedContextInterface
Supports conditional branching (onSuccess/onFail handlers)
Node-based configuration for complex business processes

ResponseInterface

Standardized response contract for bounded contexts:

ResponseInterface features:

Message and error collection (recursive and non-recursive)
Domain event tracking (array<int, object>)
Nested sub-context response aggregation
Success/failure state management
Metadata summaries with full PHPStan Level 8 type coverage

Foundation Interfaces

DatabaseServiceInterface

Query builder pattern with connection pooling:

Fluent query builders (SELECT, INSERT, UPDATE, DELETE)
Connection pool management via jardispsr/dbconnection
Persist operations for entity storage

DataServiceInterface

Reflection-based entity management:

Hydration: From database rows and nested arrays
Change Tracking: Snapshot-based detection via getChanges(), hasChanges(), getChangedFields()
Operations: Clone entities, diff comparison, array conversion
Batch: Load multiple entities efficiently

Typical Application Flow

Request → BoundedContext.handle(UseCase)
                  ↓
            (optional) Workflow with WorkFlowConfig nodes
                  ↓
            Response with sub-contexts and events
                  ↓
            Infrastructure services accessed via DomainKernelInterface

Development

All development commands run inside Docker containers for consistent environments.

Available Commands

make install     # Install Composer dependencies
make update      # Update Composer dependencies
make autoload    # Regenerate autoload files
make phpstan     # Run PHPStan static analysis (Level 8)
make phpcs       # Run PHP_CodeSniffer (PSR-12)
make shell       # Access Docker container shell
make help        # Show all available commands

Code Quality Standards

PHPStan Level 8 - Maximum strictness with full type coverage
PSR-12 coding standard with 120-character line limit
Strict types required in all PHP files (declare(strict_types=1))
Pre-commit hooks validate branch naming and run phpcs on staged files

Branch Naming Convention

Branches must follow this pattern:

(feature|fix|hotfix)/[1-7 digits]_[alphanumeric-_]+

Example: feature/123_add-workflow-interface

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Email: jardisCore@headgent.dev

Authors

Jardis Core Development

jardispsr / foundation

Maintainers

Details