README

A collection of interfaces and contracts for the SoloPHP ecosystem. This package provides standardized contracts that enable interoperability between different SoloPHP components and allow developers to create custom implementations.

Requirements

PHP 8.1 or higher

Installation

Install the package via Composer:

composer require solophp/contracts

Available Contracts

Router

RouterInterface - Framework-agnostic interface for HTTP routing implementations.

use Solo\Contracts\Router\RouterInterface;

class MyRouter implements RouterInterface
{
    public function addRoute(string $method, string $path, $handler, array $options = []): object
    {
        // Your implementation
        return $this; // Enables fluent interface
    }

    public function match(string $method, string $uri): array|false
    {
        // Your implementation
    }
}

Job Queue

JobInterface - Interface for executable job classes.

use Solo\Contracts\JobQueue\JobInterface;

class SendEmailJob implements JobInterface
{
    public function handle(): void
    {
        // Job execution logic
    }
}

JobQueueInterface - Interface for job queue implementations with support for scheduling, retries, bulk insert, stats, reclaim and operational helpers.

use Solo\Contracts\JobQueue\JobInterface;
use Solo\Contracts\JobQueue\JobQueueInterface;

class DatabaseJobQueue implements JobQueueInterface
{
    public function push(JobInterface $job, ?string $type = null, ?DateTimeImmutable $scheduledAt = null, ?DateTimeImmutable $expiresAt = null): int
    {
        // Add job to queue
    }

    // Also implement:
    //   pushMany, addJob, getPendingJobs, getFailedJobs, getStats,
    //   processJobs (returns int — number of jobs executed),
    //   reclaimStuck, retry, markCompleted, markFailed.
}

JobQueueListener - Observability hook for queue events. Implement to ship metrics (Datadog, Prometheus), open tracing spans, or enrich log context per job.

use Solo\Contracts\JobQueue\JobQueueListener;

class MetricsListener implements JobQueueListener
{
    public function onClaimed(int $jobId, string $jobClass): void { /* ... */ }
    public function onCompleted(int $jobId): void { /* ... */ }
    public function onFailed(int $jobId, \Throwable|string $error, bool $permanent): void { /* ... */ }
    public function onReclaimed(int $requeuedCount, int $permanentlyFailedCount): void { /* ... */ }
}

Validator

ValidatorInterface - Interface for data validation implementations.

use Solo\Contracts\Validator\ValidatorInterface;

class MyValidator implements ValidatorInterface
{
    public function validate(array $data, array $rules): array
    {
        // Validation logic
        // Returns structured errors: ['field' => [['rule' => 'required', 'params' => [...]], ...]]
        return $errors;
    }
}

Container

WritableContainerInterface - Extends PSR-11 ContainerInterface with write capability for service registration.

use Solo\Contracts\Container\WritableContainerInterface;

class MyContainer implements WritableContainerInterface
{
    public function set(string $id, callable $factory): void
    {
        // Register service factory
    }

    public function get(string $id): mixed
    {
        // Retrieve service
    }

    public function has(string $id): bool
    {
        // Check if service exists
    }
}

Http

EmitterInterface - Interface for HTTP response emitters that send PSR-7 responses to the client.

use Solo\Contracts\Http\EmitterInterface;

class SapiEmitter implements EmitterInterface
{
    public function emit(ResponseInterface $response): void
    {
        // Emit headers and body to client
    }
}

Usage

{
    "require": {
        "solophp/contracts": "^1.4"
    }
}

Benefits

Interoperability - Components built on these contracts work together seamlessly
Flexibility - Swap implementations without changing dependent code
Type Safety - Strong typing ensures contract compliance
Framework Agnostic - Use in any PHP project

License

MIT

solophp / contracts

Maintainers

Package info

Statistics

Security