README

Contracts and PSR dependencies for Flexi Framework - Central interface package that ensures a single point of dependency between different pieces of the Flexi Framework ecosystem.

Purpose

flexi/contracts exists to guarantee a unique dependency point between the various components of the Flexi Framework (core and modules). This package serves as the foundation for maintaining loose coupling and high cohesion across the entire framework architecture.

Key Benefits

🔗 Single Dependency Point: All framework components depend on contracts, not on concrete implementations
📦 Modular Architecture: Modules can be developed independently while sharing common interfaces
🎯 Loose Coupling: Core and modules communicate through well-defined contracts
✅ PSR Standards Compliance: Full compatibility with PHP-FIG PSR standards
🔄 Flexibility: Optional base classes and interfaces for common use cases

What's Included

This package includes:

PSR Standards Dependencies - Complete PSR compatibility out of the box
Framework Interfaces - Core contracts for the Flexi ecosystem
Base Classes - Optional abstract classes for common patterns
Value Objects - Reusable immutable value objects
Utility Traits - Helper traits for common functionality

Installation

composer require flexi/contracts

Package Contents

📋 Interfaces (26 contracts)

The package provides interfaces for all major framework components:

CQRS Pattern

BusInterface - Command/Query bus abstraction
HandlerInterface - Handler for commands and queries
DTOInterface - Data Transfer Object contract
CliDTOInterface - CLI-specific DTO contract
MessageInterface - Message contract for responses

Event Management

EventBusInterface - Event dispatcher abstraction
EventInterface - Event contract
EventListenerInterface - Event listener contract

Data Access

RepositoryInterface - Generic repository pattern
CriteriaInterface - Query criteria pattern
EntityInterface - Domain entity contract
CollectionInterface - Collection contract

Persistence & Caching

CacheInterface - Cache abstraction (PSR-16 compatible)
SessionStorageInterface - Session storage contract
LogRepositoryInterface - Log persistence contract
LogInterface - Log entity contract

Configuration

ConfigurationInterface - Configuration access contract
ConfigurationRepositoryInterface - Configuration repository contract
SecretProviderInterface - Secret/credential provider contract

Dependency Injection

ObjectBuilderInterface - Object builder/factory contract
ServiceDefinitionInterface - Service definition contract
FactoryInterface - Generic factory contract

UI & Templates

TemplateEngineInterface - Template rendering engine
TemplateInterface - Template representation
TemplateLocatorInterface - Template discovery

Foundation

ValueObjectInterface - Value object contract

🏗️ Base Classes (8 implementations)

Optional abstract and concrete classes for common patterns:

Collection - Generic collection implementation
ObjectCollection - Type-safe object collection
EventListener - Abstract event listener base
HttpHandler - Abstract HTTP request handler (PSR-15)
Log - Log entity implementation
PlainTextMessage - Simple message implementation
PsrLogger - PSR-3 logger adapter

Criteria Pattern

AnyCriteria - Null object pattern for criteria

💎 Value Objects (6 immutables)

Domain-driven value objects:

ID - Unique identifier
Version - Semantic version representation
LogLevel - PSR-3 log levels
CollectionType - Collection type descriptor
Order - Sort order (ASC/DESC)
Operator - Comparison operators

🛠️ Utility Traits (6 helpers)

Reusable functionality:

CacheKeyGeneratorTrait - Cache key generation
FileHandlerTrait - File system operations
GlobFileReader - Glob pattern file reading
JsonFileReader - JSON file parsing
InstalledModulesProviderTrait - Module discovery
OSDetectorTrait - Operating system detection

PSR Standards Included

This package includes and enforces compatibility with:

PSR-1: Basic Coding Standard
PSR-3: Logger Interface (via psr/log)
PSR-6: Caching Interface (via psr/cache)
PSR-7: HTTP Message Interface (via psr/http-message)
PSR-11: Container Interface (via psr/container)
PSR-14: Event Dispatcher (via psr/event-dispatcher)
PSR-15: HTTP Server Request Handlers (via psr/http-server-handler & psr/http-server-middleware)
PSR-16: Simple Cache (via psr/simple-cache)
PSR-17: HTTP Factories (via psr/http-factory)
PSR-18: HTTP Client (via psr/http-client)
PSR-20: Clock (via psr/clock)

Usage Philosophy

For Framework Core

The core should:

✅ Depend on contracts from this package
✅ Implement interfaces defined here
❌ Never create its own interfaces that modules need
❌ Never depend on module implementations

For Modules

Modules should:

✅ Depend on contracts from this package
✅ Implement interfaces defined here
✅ Use optional base classes if needed
❌ Never depend on the core directly
❌ Declare explicit dependency on other modules in composer.json to resolve automatically and avoid incompatibilities

Optional Usage

All base classes, value objects, and traits are optional. You can:

Use only the interfaces you need
Implement your own base classes
Create custom value objects
Skip utility traits if not needed

Example: Using Contracts

use Flexi\Contracts\Interfaces\HandlerInterface;
use Flexi\Contracts\Interfaces\DTOInterface;
use Flexi\Contracts\Interfaces\MessageInterface;
use Flexi\Contracts\Classes\PlainTextMessage;

class MyCommandHandler implements HandlerInterface
{
    public function handle(DTOInterface $command): MessageInterface
    {
        // Your business logic here
        return new PlainTextMessage('Command executed successfully');
    }
}

Example: Using Value Objects

use Flexi\Contracts\ValueObjects\ID;
use Flexi\Contracts\ValueObjects\Version;

$userId = new ID('user-123');
$appVersion = new Version(1, 5, 0);

echo $appVersion; // "1.5.0"

Example: Using Base Classes

use Flexi\Contracts\Classes\EventListener;
use Flexi\Contracts\Interfaces\EventInterface;

class MyEventListener extends EventListener
{
    public function handleEvent(EventInterface $event): void
    {
        // React to the event
        $data = $event->getData();
        // Process...
    }
}

Requirements

PHP 7.4 or higher
Composer

License

MIT License - see LICENSE file for details.

Contributing

This package is part of the Flexi Framework ecosystem. Contributions are welcome following these guidelines:

Interface Changes: Require careful consideration as they affect the entire ecosystem
New Interfaces: Should solve common problems across multiple modules
Base Classes: Should be optional and follow SOLID principles
PSR Compliance: Must maintain compatibility with PSR standards

Versioning

This package follows Semantic Versioning:

MAJOR: Breaking changes to interfaces
MINOR: New interfaces or optional features
PATCH: Bug fixes and documentation

Architecture

┌─────────────────────────────────────────┐
│         Flexi Framework Core            │
│     (Business Logic & Orchestration)    │
└─────────────┬───────────────────────────┘
              │ depends on
              ↓
┌─────────────────────────────────────────┐
│       flexi/contracts                   │
│  (Interfaces, Base Classes, PSR deps)   │
└─────────────┬───────────────────────────┘
              ↑ depends on
              │
┌─────────────┴───────────────────────────┐
│                                         │
│  ┌──────────────┐  ┌──────────────┐    │
│  │ Auth Module  │  │ Cache Module │    │
│  └──────────────┘  └──────────────┘    │
│  ┌──────────────┐  ┌──────────────┐    │
│  │  UI Module   │  │  Log Module  │    │
│  └──────────────┘  └──────────────┘    │
│         ... more modules ...            │
└─────────────────────────────────────────┘

Support

For questions and support:

Open an issue on GitHub
Check the Flexi Framework documentation

Made with ❤️ for the Flexi Framework ecosystem

flexi / contracts

Maintainers

Details