PHPackages                             flexi/contracts - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PSR & Standards](/categories/psr-standards)
4. /
5. flexi/contracts

ActiveLibrary[PSR & Standards](/categories/psr-standards)

flexi/contracts
===============

Contracts and PSR dependencies for Flexi Framework - Central interface package

4.1.0(5mo ago)081[1 issues](https://github.com/Flexi-PHP/flexi-contracts/issues)1MITPHPPHP >=7.4

Since Nov 4Pushed 5mo agoCompare

[ Source](https://github.com/Flexi-PHP/flexi-contracts)[ Packagist](https://packagist.org/packages/flexi/contracts)[ RSS](/packages/flexi-contracts/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (12)Versions (8)Used By (1)

Flexi Contracts
===============

[](#flexi-contracts)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/7404ac2849f95f99ace60c4b949c4e57e3188dfc0d5df7a913378138ac571fb6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344372e342d626c7565)](https://php.net)[![PSR Compatible](https://camo.githubusercontent.com/0d6e097179084ace1aba9d14d15ada7bdaadc80c82f05539af55e9e23263825e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d436f6d70617469626c652d677265656e)](https://www.php-fig.org/psr/)

**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
-------

[](#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

[](#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
---------------

[](#whats-included)

This package includes:

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

Installation
------------

[](#installation)

```
composer require flexi/contracts
```

Package Contents
----------------

[](#package-contents)

### 📋 Interfaces (26 contracts)

[](#-interfaces-26-contracts)

The package provides interfaces for all major framework components:

#### **CQRS Pattern**

[](#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**

[](#event-management)

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

#### **Data Access**

[](#data-access)

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

#### **Persistence & Caching**

[](#persistence--caching)

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

#### **Configuration**

[](#configuration)

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

#### **Dependency Injection**

[](#dependency-injection)

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

#### **UI & Templates**

[](#ui--templates)

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

#### **Foundation**

[](#foundation)

- `ValueObjectInterface` - Value object contract

### 🏗️ Base Classes (8 implementations)

[](#️-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

[](#criteria-pattern)

- `AnyCriteria` - Null object pattern for criteria

### 💎 Value Objects (6 immutables)

[](#-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)

[](#️-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
----------------------

[](#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
----------------

[](#usage-philosophy)

### For Framework Core

[](#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

[](#for-modules)

Modules should:

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

### Optional Usage

[](#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
------------------------

[](#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
----------------------------

[](#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
---------------------------

[](#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
------------

[](#requirements)

- PHP 7.4 or higher
- Composer

License
-------

[](#license)

MIT License - see [LICENSE](LICENSE) file for details.

Contributing
------------

[](#contributing)

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

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

Versioning
----------

[](#versioning)

This package follows [Semantic Versioning](https://semver.org/):

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

Links
-----

[](#links)

- [Flexi Framework](https://github.com/CubaDevOps/flexi)
- [Documentation](https://github.com/CubaDevOps/flexi/tree/main/docs)
- [Report Issues](https://github.com/CubaDevOps/flexi-contracts/issues)

Architecture
------------

[](#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
-------

[](#support)

For questions and support:

- Open an issue on [GitHub](https://github.com/CubaDevOps/flexi-contracts/issues)
- Check the [Flexi Framework documentation](https://github.com/CubaDevOps/flexi/tree/main/docs)

---

Made with ❤️ for the Flexi Framework ecosystem

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance72

Regular maintenance activity

Popularity11

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 87.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~6 days

Total

7

Last Release

160d ago

Major Versions

v1.0.0 → v2.0.02025-11-04

v2.1.0 → v3.0.02025-12-02

v3.0.0 → v4.0.02025-12-04

### Community

Maintainers

![](https://www.gravatar.com/avatar/40b582c610d5d33636fea13fd72a9a8012820ed5c4d30afda8eeb5c4736382f4?d=identicon)[cbatista8a](/maintainers/cbatista8a)

---

Top Contributors

[![cbatista8a](https://avatars.githubusercontent.com/u/59052959?v=4)](https://github.com/cbatista8a "cbatista8a (14 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (2 commits)")

### Embed Badge

![Health badge](/badges/flexi-contracts/health.svg)

```
[![Health](https://phpackages.com/badges/flexi-contracts/health.svg)](https://phpackages.com/packages/flexi-contracts)
```

###  Alternatives

[symfony/symfony

The Symfony PHP framework

31.3k86.3M2.2k](/packages/symfony-symfony)[cakephp/cakephp

The CakePHP framework

8.8k18.5M1.6k](/packages/cakephp-cakephp)[windwalker/framework

The next generation PHP framework.

25639.1k1](/packages/windwalker-framework)[neos/flow

Flow Application Framework

862.0M451](/packages/neos-flow)[neos/flow-development-collection

Flow packages in a joined repository for pull requests.

144179.3k3](/packages/neos-flow-development-collection)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)