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.
- Full name:
\PhalconKit\Provider\OpenAi\ServiceProvider - Parent class:
\PhalconKit\Provider\AbstractServiceProvider
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().