Hierone Contracts

A comprehensive set of PHP abstractions extracted from the Hierone framework components. This package provides standardized interfaces, traits, and contracts that enable interoperability between different components and libraries in the Hierone ecosystem.

Features

• Domain-Specific Contracts: Organized by functionality areas with clear separation of concerns
• Modern PHP: Built for PHP 8.2+ with strict types and modern language features
• PSR Compliance: Follows PSR standards where applicable
• Battle-Tested: All contracts have proven implementations in production
• Backward Compatible: Maintains stability with semantic versioning

Available Contracts

Translation & Internationalization (Recap)

• TranslatorInterface: Core translation service contract
• LocaleAwareInterface: Locale management capabilities
• TranslatableInterface: Objects that can be translated
• TranslatorTrait: Common translation functionality

Deprecation Management (Depreciation)

• Helper functions for handling deprecations gracefully
• Support for marking deprecated functions, methods, and classes

Installation

composer require hierone/contracts

Usage

Translation Contracts

use Hierone\Contracts\Recap\TranslatorInterface;

class MyTranslator implements TranslatorInterface
{
    public function trans(string $key, array $parameters = [], ?string $locale = null): string
    {
        // Your implementation
    }
    
    // ... other required methods
}

Deprecation Helpers

// Mark a function as deprecated
trigger_deprecation('my-package', '2.1', 'Use newFunction() instead');

// Mark a method as deprecated  
deprecated_method('my-package', '2.1', 'MyClass', 'oldMethod', 'Use newMethod() instead');

Principles

• Domain Separation: Contracts are split by domain, each in their own sub-namespaces
• Interface-First: Contracts are sets of PHP interfaces, traits, and informative docblocks
• Proven Implementation: All contracts must have proven implementations in real-world usage
• Backward Compatibility: Must maintain backward compatibility following semantic versioning
• Interoperability: Designed to work seamlessly across different implementations

Integration

Packages that implement specific contracts should list them in the "provide" section of their composer.json:

{
    "provide": {
        "hierone/recap-contracts": "^1.0",
        "hierone/depreciation-contracts": "^1.0"
    }
}

Contributing

This package follows the Hierone framework contribution guidelines. All contracts must:

1. Have at least one proven implementation
2. Include comprehensive documentation
3. Follow modern PHP practices and type declarations
4. Maintain backward compatibility

License

This project is licensed under the MIT License - see the LICENSE file for details.