Skip to content

ServiceProvider

Registers the OpenAI API client service.

The provider builds an openai-php/client instance from the openai config section. Supported values include API key, organization, project, and base URI. The canonical config keys are apiKey, organization, project, and baseUri; legacy bootstrap aliases such as secretKey, organizationId, and projectId are accepted as fallbacks so older app config can keep resolving the shared service while it migrates.

Applications may register openAiHttpClient (PSR-18 ClientInterface) and openAiStreamHandler (callable accepting a PSR-7 request and returning a PSR-7 response) before first resolving openAi. Existing transport services are preserved. Defaults use a shared Guzzle client and send() with stream => true; a PSR-18-only replacement needs its own streaming handler when making streamed requests. Register callable handlers through a DI factory returning the callable so Phalcon does not invoke them as factories.


Properties

serviceName

Stable DI service name managed by this provider.

protected string $serviceName

This value is part of the provider contract because controllers, tasks, other injectables, and replacement providers resolve services by name. Concrete providers must set it to a non-empty value.


Methods

register

Register the shared openAi client and missing transport services.

public register(\PhalconKit\Di\DiInterface $di): void

Transport services are resolved lazily when the client is first used. Replace them before resolving openAi; an already resolved SDK client keeps its original transports. No network requests occur during registration.

Parameters:

Parameter Type Description
$di \PhalconKit\Di\DiInterface Container with a PhalconKit config service.

Throws:

On client resolution when a transport has the wrong type, or on streaming when a PSR-18-only client has no explicitly registered stream handler. - ServiceException


resolveHttpClient

private static resolveHttpClient(\PhalconKit\Di\DiInterface $di): \Psr\Http\Client\ClientInterface
  • This method is static. Parameters:
Parameter Type Description
$di \PhalconKit\Di\DiInterface

normalizeOpenAiConfig

Normalize supported OpenAI provider config aliases.

protected static normalizeOpenAiConfig(array<string,mixed> $openAiConfig): array{apiKey: string, organization: string|null, project: string|null, baseUri: string}

apiKey, organization, project, and baseUri are the canonical provider-facing keys. The legacy bootstrap keys are still read as fallbacks because applications may have copied the default secretKey or organizationId names before the provider contract was clarified.

  • This method is static. Parameters:
Parameter Type Description
$openAiConfig array Raw openai config section.

stringConfigOption

Return the first non-empty string value from a list of config aliases.

private static stringConfigOption(array<string,mixed> $config, list<string> $keys, string $default = ''): string

Canonical keys are passed first and legacy aliases follow them. Empty strings are ignored so partially migrated environment files can leave a canonical key blank while still relying on the older configured alias.

  • This method is static. Parameters:
Parameter Type Description
$config array Raw provider config.
$keys list Ordered config keys to inspect.
$default string

nullableStringConfigOption

Return an optional string config value from canonical and alias keys.

private static nullableStringConfigOption(array<string,mixed> $config, list<string> $keys): ?string
  • This method is static. Parameters:
Parameter Type Description
$config array Raw provider config.
$keys list Ordered config keys to inspect.

stringConfigValue

Cast a provider config value to the string expected by openai-php/client.

private static stringConfigValue(mixed $value): string
  • This method is static. Parameters:
Parameter Type Description
$value mixed

Inherited methods

__construct

Stores the DI container and prepares the provider for registration.

public __construct(\PhalconKit\Di\DiInterface $di): mixed

The constructor intentionally requires PhalconKit\Di\DiInterface so providers can rely on typed service helpers during configuration and registration.

Parameters:

Parameter Type Description
$di \PhalconKit\Di\DiInterface

Throws:

When a concrete provider does not define a non-empty service name. - LogicException


getName

Returns the DI service name managed by this provider.

public getName(): string

boot

Optional post-registration hook.

public boot(): void

The base implementation is intentionally empty. Custom bootstraps or application code may call this method for provider-specific startup work after all services have been registered.


configure

Optional provider-local configuration hook.

public configure(): void

This runs during construction after DI has been stored and before register() is called. Use it to normalize provider options or prepare lightweight state; service creation belongs in register().