Contracts and Interfaces

This document provides reference documentation for the core contracts and interfaces in the Hypervel Console package. These contracts define the integration points for the console system, scheduling system, and concurrency control mechanisms.

Overview

The package defines four primary contracts that establish boundaries between system components and enable extensibility through dependency injection:

Contract	Purpose	Primary Use Case
Application	Console runtime interface	Command registration and execution
EventMutex	Per-event lock management	Prevent overlapping task executions
SchedulingMutex	Server-level coordination	Single-server task execution
CacheAware	Cache store configuration	Runtime cache backend selection

These contracts enable testing, dependency injection, and custom implementations while maintaining loose coupling between components.

Contract Architecture

Contract Hierarchy and Relationships:

Sources: src/Contracts/Application.php src/Contracts/EventMutex.php src/Contracts/CacheAware.php

Application Contract

The Application contract (src/Contracts/Application.php14-65) defines the interface for the console application runtime. It bridges Symfony Console functionality with Hyperf's dependency injection container.

Interface Definition

Lifecycle Methods

Method	Purpose	Parameters	Return Type
starting(Closure $callback)	Register application bootstrapper	Closure callback	void
forgetBootstrappers()	Clear all registered bootstrappers	None	void
run(?InputInterface $input, ?OutputInterface $output)	Execute the console application	Optional input/output interfaces	mixed

Container Integration

Method	Purpose	Parameters	Return Type
getContainer()	Get the DI container instance	None	ContainerContract
setContainerCommandLoader()	Enable lazy command loading from container	None	static

Command Management

Method	Purpose	Parameters	Return Type
add(Command $command)	Register a command instance	Command instance	mixed
all(?string $namespace)	Get all registered commands	Optional namespace filter	mixed
resolve(Command|string $command)	Resolve command from container	Command class or instance	?SymfonyCommand
resolveCommands($commands)	Resolve multiple commands at once	Array of commands	static

Command Execution

Method	Purpose	Parameters	Return Type
call(string $command, array $parameters, ?OutputInterface $outputBuffer)	Execute command by name	Command name, parameters, optional output buffer	int
output()	Get output from last executed command	None	string

Usage Example Flow

Application Execution Pattern:

The Application contract is implemented by Hypervel\Console\Application (src/Application.php) and serves as the primary entry point for console command execution.

Sources: src/Contracts/Application.php14-65

EventMutex Contract

The EventMutex contract (src/Contracts/EventMutex.php9-25) provides per-event lock management to prevent overlapping executions of the same scheduled task. This is used when an event is configured with withoutOverlapping().

Interface Definition

Method	Purpose	Parameters	Return Type
create(Event $event)	Attempt to acquire a lock for the event	Event instance	bool
exists(Event $event)	Check if a lock exists for the event	Event instance	bool
forget(Event $event)	Release the lock for the event	Event instance	void

Lock Lifecycle

EventMutex Lock Management Pattern:

Default Implementation

The default implementation is Hypervel\Console\Scheduling\CacheEventMutex, which uses the cache system to store locks. Lock keys are generated by hashing the event's cron expression and command using the event's mutexName() method.

Usage Context

The EventMutex is used by the Event class in two methods:

• shouldSkipDueToOverlapping() - checks if execution should be skipped
• withoutOverlapping() - configures mutex usage and expiry time

Sources: src/Contracts/EventMutex.php9-25

SchedulingMutex Contract

The SchedulingMutex contract provides server-level coordination to ensure scheduled events run on only one server in a distributed environment. This is used when an event is configured with onOneServer().

Interface Definition

The SchedulingMutex interface is structurally similar to EventMutex but serves a different purpose:

Method	Purpose	Parameters	Return Type
create(Event $event)	Attempt to acquire server-level lock	Event instance	bool
exists(Event $event)	Check if server-level lock exists	Event instance	bool
forget(Event $event)	Release server-level lock	Event instance	void

Multi-Server Coordination

SchedulingMutex Server Selection Pattern:

Default Implementation

The default implementation is Hypervel\Console\Scheduling\CacheSchedulingMutex, which uses a shared cache backend (typically Redis or Memcached) to coordinate between servers.

Usage Context

The SchedulingMutex is used by the Schedule class in the dueEvents() method to filter events when onOneServer() is configured. Only the server that acquires the lock will execute the event.

Sources: Referenced in Diagram 6 of system architecture

CacheAware Contract

The CacheAware contract (src/Contracts/CacheAware.php8-13) enables runtime configuration of the cache store for mutex implementations.

Interface Definition

Method	Purpose	Parameters	Return Type
useStore(string $store)	Specify the cache store to use	Store name	static

Purpose

Both CacheEventMutex and CacheSchedulingMutex implement this contract, allowing different events to use different cache backends:

Cache Store Selection

The contract allows the mutex implementations to delegate storage to specific cache drivers configured in the application's cache configuration. This enables flexibility in choosing appropriate backends for different deployment scenarios.

Sources: src/Contracts/CacheAware.php8-13

Contract Implementations

Default Implementations

The package provides default implementations for all contracts:

Contract	Default Implementation	Location
Application	Hypervel\Console\Application	src/Application.php
EventMutex	Hypervel\Console\Scheduling\CacheEventMutex	src/Scheduling/CacheEventMutex.php
SchedulingMutex	Hypervel\Console\Scheduling\CacheSchedulingMutex	src/Scheduling/CacheSchedulingMutex.php

Both mutex implementations also implement CacheAware to enable cache store configuration.

Custom Implementations

To provide custom implementations, bind the contracts in the dependency injection container:

Framework Integration Pattern

The contracts and interfaces work together to provide integration between Hyperf framework, Symfony Console, and the application's dependency injection container:

Sources: src/Contracts/Application.php src/ContainerCommandLoader.php src/HasPendingCommand.php

Extension Points

These contracts define the primary extension points for the console framework:

• Application Contract: Extend console application behavior and command registration
• Mutex Contracts: Implement custom concurrency control mechanisms
• CacheAware Contract: Integrate with different caching backends and strategies

The contract system enables testing, dependency injection, and framework extensibility while maintaining clean separation between interface and implementation.

Sources: src/Contracts/Application.php src/Contracts/CacheAware.php src/Contracts/EventMutex.php src/Contracts/SchedulingMutex.php