adachsoft / ai-image-proxy

v0.1.0 2026-11-07 09:07 UTC

Requires

• php: ^8.3
• adachsoft/ai-image-contract: ^0.3
• adachsoft/collection: ^3.0
• adachsoft/plugin-discovery: ^0.1

Requires (Dev)

• adachsoft/php-code-style: ^0.7.1
• friendsofphp/php-cs-fixer: ^3.95
• phpstan/phpstan: ^2.3
• phpunit/phpunit: ^13.4
• rector/rector: ^2.8
• symplify/phpstan-rules: ^14.9

MIT

• Arkadiusz Adach

• plugins
• composer
• ai
• image-generation
• image-proxy

Published on Packagist.org on 2026-11-07 11:48 UTC

README

adachsoft/ai-image-proxy provides an ImageGeneratorInterface implementation that delegates image generation to installed provider plugins. It discovers provider packages through Composer metadata, configures only providers for which parameters are available, and allows providers to be disabled without uninstalling them.

Installation

Install the proxy and the provider packages you want to use:

composer require adachsoft/ai-image-proxy adachsoft/ai-image-xai adachsoft/ai-image-openai

A provider package must implement ImageGeneratorPluginInterface and declare its plugin in its composer.json:

{
    "extra": {
        "adachsoft/ai-image-contract": {
            "plugins": {
                "xai": "AdachSoft\\AiImageXai\\XaiImagePlugin"
            }
        }
    }
}

Plugin identifiers must follow ^[a-z0-9]+(?:[._-][a-z0-9]+)*$, be no longer than 64 characters, and be unique across the Composer installation. A provider plugin must have no required constructor arguments. Provider packages should document the parameter names they require.

Usage

use AdachSoft\AiImageContract\Collections\ImageInputVoCollection;
use AdachSoft\AiImageContract\Models\GenerationRequestDto;
use AdachSoft\AiImageContract\ValueObjects\PromptVo;
use AdachSoft\AiImageProxy\ImageGeneratorProxyFactory;
use AdachSoft\AiImageProxy\Parameters\InMemoryPluginParametersProvider;

$generator = (new ImageGeneratorProxyFactory())->create(
    new InMemoryPluginParametersProvider([
        'xai' => ['api_key' => $xaiApiKey],
        'openai' => ['api_key' => $openAiApiKey],
    ]),
    defaultPluginId: 'xai',
    disabledPluginIds: ['minimax'],
);

$defaultResponse = $generator->generate(new GenerationRequestDto(
    new PromptVo('A mountain landscape at sunrise'),
    new ImageInputVoCollection([]),
));

$openAiResponse = $generator->generate(new GenerationRequestDto(
    new PromptVo('A quiet forest in autumn'),
    new ImageInputVoCollection([]),
    options: ['plugin_id' => 'openai'],
));

The plugin_id option selects a provider for one request. The proxy removes this option before forwarding the request to the provider; all other request data and options are preserved.

Configuration behavior

• A discovered provider without a parameter set is not activated.
• A disabled provider is excluded from discovery, even if its package is installed.
• The default provider must be installed, enabled, and configured when the proxy is created.
• A provider's create() method is called during proxy creation. Provider configuration failures are therefore reported immediately.
• The in-memory provider validates plugin identifiers and parameter names. Error messages never include parameter values.
• Applications can implement PluginParametersProviderInterface to load parameters from another source, such as an environment, secret vault, or configuration service.

Exceptions

• InvalidPluginParametersConfigurationException indicates an invalid application-supplied parameter map.
• PluginNotAvailableException indicates that the default or requested provider is unavailable.
• InvalidInputException from adachsoft/ai-image-contract indicates an invalid plugin_id request option.
• Provider and discovery exceptions are propagated without being wrapped.