Add SelfHandlingOptimizer for optimizers without a binary

[mathiasgrimm]

Add SelfHandlingOptimizer for optimizers without a binary

Problem

OptimizerChain assumes every optimizer produces a getCommand() string that it runs through a Symfony Process. There is no way to write an optimizer that has no binary and no shell command, for example one that sends the image to an external optimization API.

Solution

A new SelfHandlingOptimizer interface (extending Optimizer) with a single handle() method. When the chain encounters one, it delegates execution to handle() instead of building and running a process, passing the chain's logger so the optimizer can log its own progress:

use Psr\Log\LoggerInterface;
use Spatie\ImageOptimizer\Image;
use Spatie\ImageOptimizer\Optimizers\BaseSelfHandlingOptimizer;

class ApiOptimizer extends BaseSelfHandlingOptimizer
{
    public function canHandle(Image $image): bool
    {
        return $image->mime() === 'image/jpeg';
    }

    public function handle(Image $image, LoggerInterface $logger): void
    {
        // Optimize $image->path() however you like (e.g. call an API),
        // write the result back to that path, and throw on failure.
        // Use $logger to record progress.
    }
}

Add it to a chain with addOptimizer() like any other optimizer. BaseSelfHandlingOptimizer reduces it to implementing just canHandle() and handle().

Backwards compatibility

Fully additive, no breaking changes:

• SelfHandlingOptimizer extends Optimizer, so instances satisfy every existing Optimizer type hint.
• OptimizerChain only gains a branch inside runOptimizer()'s body. No method signature changes, so any subclass overriding the protected methods (applyOptimizer, runOptimizer, handleException) stays compatible.
• The Optimizer interface, BaseOptimizer, the bundled optimizers, and composer.json are untouched.

The only cost of staying non-breaking: a SelfHandlingOptimizer inherits getCommand()/binaryName() from Optimizer. They are never called (the chain branches before getCommand()), and BaseSelfHandlingOptimizer implements them as documented no-ops.

Logging & error handling

The self-handling flow mirrors the binary flow's logging. For each optimizer the chain logs the class name, then an "executing" line, followed by the optimizer's own log lines:

Using optimizer: `App\ApiOptimizer`
Executing `App\ApiOptimizer`
... your own log lines from handle() ...

A failing handle() emits an error: line, just like a failing binary, and flows through the same throws() mechanism from #241: by default it is logged and the chain continues; throws() (or a callable) lets you abort or inspect it.

Tests

Adds tests/SelfHandlingOptimizerTest.php (8 tests): delegation + image/logger passed, skip when canHandle() is false, default-continue, throws() abort, custom-handler routing, temp-file cleanup (including when handle() throws), and a mixed binary + self-handling chain proving the binary optimizer flow is unchanged. Full suite: 40 passing.

🤖 Generated with Claude Code

[freekmurze]

Thanks for the contribution, @mathiasgrimm! Merged and released in 1.10.0.