Closure Commands

Purpose and Scope

This document explains the ClosureCommand class, which enables command definition using closures instead of dedicated command classes. Closure commands provide a lightweight alternative for simple command implementations, supporting parameter mapping from command inputs to closure parameters and integration with the task scheduling system.

For information about the base Command class and its execution lifecycle, see page 4. For details on scheduling closure commands with cron expressions, see page 7.

---

Overview

The ClosureCommand class extends the base Command class and wraps a closure for execution. It is defined in src/ClosureCommand.php

Key Characteristics

Feature	Implementation
Base Class	Extends Command
Closure Binding	Stores closure passed to constructor
Parameter Mapping	Uses reflection to map inputs to closure parameters
Dependency Injection	Leverages container's call() method for DI
Scheduling Integration	Supports scheduling via schedule() method
Method Proxying	Forwards unknown method calls to scheduled events

Class Diagram: ClosureCommand Structure

Sources: src/ClosureCommand.php1-97

---

Command Definition

A ClosureCommand is instantiated with three components:

1. Container: The dependency injection container
2. Signature: Command signature string defining name, arguments, and options
3. Callback: The closure to execute

The constructor is defined at src/ClosureCommand.php25-33

Constructor Signature

public function __construct(
 protected ContainerContract $container,
 string $signature,
 protected Closure $callback
)

The signature string follows Symfony Console conventions and is stored in the $signature property inherited from the base Command class.

Typical Usage Pattern

While the file doesn't show registration code, closure commands are typically registered through the application's command registration system, where the signature defines the command's interface and the closure contains the execution logic.

Sources: src/ClosureCommand.php25-33

---

Parameter Mapping

The handle() method implements automatic parameter mapping between command inputs and closure parameters using PHP's reflection API.

Parameter Mapping Flow

Sources: src/ClosureCommand.php38-60

Implementation Details

The mapping process, implemented at src/ClosureCommand.php40-48 performs the following steps:

1. Input Collection: Merges arguments and options from $this->input into a single array
2. Reflection: Creates ReflectionFunction instance for the callback closure
3. Parameter Iteration: Iterates through closure parameters via getParameters()
4. Name Matching: For each parameter, checks if an input exists with matching name
5. Parameter Building: Builds $parameters array with matched values

Closure Binding and Execution

At src/ClosureCommand.php51-54 the closure is bound to the ClosureCommand instance before execution:

return (int) $this->container->call(
 $this->callback->bindTo($this, $this),
 $parameters
);

This binding enables the closure to access $this and reference the command instance, providing access to output methods like $this->info() or $this->error().

The container's call() method provides additional dependency injection, resolving type-hinted parameters not found in the $parameters array.

Error Handling

The execution is wrapped in a try-catch block src/ClosureCommand.php50-59 that catches ManuallyFailedException and returns static::FAILURE exit code after displaying the error message.

Parameter Resolution Priority

Sources: src/ClosureCommand.php38-60

---

Description Methods

The ClosureCommand class provides two methods for setting command descriptions:

purpose() Method

Defined at src/ClosureCommand.php65-68 the purpose() method is an alias for describe():

public function purpose(string $description): static
{
 return $this->describe($description);
}

describe() Method

Defined at src/ClosureCommand.php73-78 the describe() method sets the command description:

public function describe(string $description): static
{
 $this->setDescription($description);
 return $this;
}

Both methods return static to enable fluent chaining.

Sources: src/ClosureCommand.php65-78

---

Scheduling Closure Commands

The ClosureCommand class integrates with the task scheduling system through the schedule() method and magic method proxying.

schedule() Method

The schedule() method, defined at src/ClosureCommand.php83-86 creates a scheduled event for the closure command:

public function schedule(array $parameters = []): Event
{
 return Schedule::command($this->name, $parameters);
}

This method delegates to the Schedule facade's command() method, passing the command name and optional parameters array. The method returns an Event instance that can be configured with timing and execution attributes.

Scheduling Integration Architecture

Sources: src/ClosureCommand.php83-86

Magic Method Proxying

The __call() magic method, defined at src/ClosureCommand.php93-96 enables fluent scheduling syntax by forwarding method calls to scheduled events:

public function __call(string $method, array $parameters)
{
 return $this->forwardCallTo($this->schedule(), $method, $parameters);
}

This implementation uses the ForwardsCalls trait (imported at src/ClosureCommand.php9) to forward unrecognized method calls to a newly created Event instance.

Usage Pattern

The magic method proxying enables this fluent syntax:

$closureCommand->daily()->at('13:00')->withoutOverlapping();

Each chained method call:

1. Triggers __call() if method doesn't exist on ClosureCommand
2. Creates new Event via schedule()
3. Forwards method call to the Event instance
4. Returns the Event for further chaining

This pattern is documented in the mixin annotation at src/ClosureCommand.php16:

/**
 * @mixin \Hypervel\Console\Scheduling\Event
 */

The @mixin annotation enables IDE autocompletion for all Event methods when working with ClosureCommand instances.

Method Call Flow

Sources: src/ClosureCommand.php9-96

---

Class Dependencies

The ClosureCommand class depends on several components from the Hypervel ecosystem:

Dependency	Purpose	Import Location
Closure	Built-in PHP type for callback storage	src/ClosureCommand.php8
ContainerContract	Dependency injection interface	src/ClosureCommand.php11
ForwardsCalls	Trait for method proxying	src/ClosureCommand.php9
Event	Scheduled task representation	src/ClosureCommand.php10
Schedule	Facade for schedule registry	src/ClosureCommand.php12
ReflectionFunction	PHP reflection for parameter inspection	src/ClosureCommand.php13

Sources: src/ClosureCommand.php1-13

---

Summary

The ClosureCommand class provides a lightweight mechanism for defining console commands using closures. Key features include:

• Automatic Parameter Mapping: Uses reflection to map command inputs to closure parameters by name
• Dependency Injection: Leverages container's call() method for additional DI support
• Closure Binding: Binds closure to command instance, enabling access to output methods
• Scheduling Integration: Provides schedule() method for task scheduling
• Fluent API Proxying: Forwards method calls to scheduled events via __call() magic method
• Error Handling: Catches ManuallyFailedException and returns appropriate exit codes

The class serves as a bridge between simple closure-based command definitions and the full command execution and scheduling infrastructure.

Sources: src/ClosureCommand.php1-97