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