Download the PHP package shanginn/openai-sdk without Composer

OpenAI SDK PHP

A modern, strongly-typed PHP SDK for interacting with the OpenAI API, focusing initially on the Chat Completions endpoint. Built with asynchronous capabilities in mind using amphp/http-client and robust serialization/deserialization via crell/serde.

Features

• Access to the OpenAI Chat Completions API (/v1/chat/completions).
• Strongly-Typed Objects: Uses PHP classes for Requests, Responses, Messages, Tools, and Schemas, providing better IDE autocompletion and type safety.
• Tool Calling: Define and use tools (functions) that the OpenAI models can invoke. Includes automatic deserialization of tool arguments into PHP objects based on class definitions with attributes like Spiral\JsonSchemaGenerator\Attribute\Field.
• JSON Schema Mode: Force the model to output JSON conforming to a specific structure defined by your PHP classes implementing JsonSchemaInterface, utilizing attributes like Spiral\JsonSchemaGenerator\Attribute\Field for detailed schema generation.
• Image Input: Supports sending images along with text prompts using UserMessage and ImageContentPart (compatible with models like GPT-4o).
• Asynchronous Client: Leverages amphp/http-client for non-blocking I/O (though the current OpenaiClient implementation buffers the full response).
• Serialization: Uses crell/serde and symfony/serializer for mapping between PHP objects and OpenAI's JSON format.
• Simplified Wrapper: Includes an OpenaiSimple class for common use cases like simple text generation, JSON object generation, and tool calling with less boilerplate.
• Custom Exceptions: Provides specific exceptions for different API error conditions (e.g., OpenaiErrorResponseException, OpenaiNoChoicesException, OpenaiWrongSchemaException).

Installation

Install the package via Composer:

Usage

Simple Text Generation (OpenaiSimple)

This is the easiest way to get a text response for a simple prompt.

Basic Completion (Openai Core Class)

If you need more control over the request parameters or want to handle the response object directly.

Advanced Usage

Tool Calling

Define a tool class implementing ToolInterface (often by extending AbstractTool and using #[OpenaiToolSchema]) and detail its parameters using #[Field] attributes from spiral/json-schema-generator. The SDK will attempt to deserialize the model's arguments into an instance of your tool class.

1. Define the Tool Schema:

2. Call the Tool using OpenaiSimple:

This simplifies the process of forcing a specific tool call and getting the parsed arguments.

3. Call the Tool using Core Openai Class:

This gives you more control over the request and access to the full response, including the tool call ID.

JSON Schema Output

Force the model to generate a JSON object conforming to your predefined PHP class structure. Define the schema class implementing JsonSchemaInterface (often by extending AbstractJsonSchema and using #[OpenaiSchema]) and detail its properties using #[Field] attributes.

1. Define the JSON Schema Class:

2. Generate JSON using OpenaiSimple:

This simplifies getting the deserialized schema object directly.

3. Generate JSON using Core Openai Class:

Provides access to the full response, including the raw JSON string before deserialization.

Image Input

Provide an array of ContentPartInterface objects (TextContentPart, ImageContentPart) to the UserMessage constructor. Requires a vision-capable model like gpt-4o.

Error Handling

The SDK throws specific exceptions found in the Shanginn\Openai\Exceptions namespace for easier error management.

• OpenaiErrorResponseException: Wraps an ErrorResponse object returned directly by the OpenAI API (e.g., invalid API key, rate limit exceeded). Access the details via $e->response.
• OpenaiRefusedResponseException: Thrown by OpenaiSimple when the model explicitly refuses to answer (contains a refusal message). Access via $e->refusal and $e->response.
• OpenaiNoChoicesException: Thrown when the API returns a valid response but with an empty choices array. Access the original response via $e->response.
• OpenaiNoContentException: Thrown by OpenaiSimple when a choice exists but has no content. Access via $e->response.
• OpenaiWrongSchemaException: Thrown by OpenaiSimple or potentially during core Openai processing if JSON schema/tool calling was requested, but the response didn't conform as expected (e.g., deserialization failed). Access via $e->response.
• OpenaiInvalidResponseException: Base class for response validation issues like NoChoices, NoContent, WrongSchema.
• OpenaiException: Base exception for all SDK-specific errors.

Dependencies

• amphp/http-client: For asynchronous HTTP requests.
• crell/serde: For robust serialization and deserialization between PHP objects and JSON.
• symfony/serializer: Used alongside crell/serde for normalization, particularly handling enums, snake_case, and custom normalizers.
• spiral/json-schema-generator: (Recommended) Used internally and via attributes (#[Field]) to generate detailed JSON Schema definitions from PHP classes for Tool Calling and JSON Schema mode.

Contributing

Contributions are welcome! Please follow these general steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix (git checkout -b feature/my-new-feature).
3. Make your changes.
4. Add tests for your changes.
5. Ensure tests pass (vendor/bin/phpunit).
6. Ensure code style compliance (e.g., using PHP CS Fixer or Rector with provided config, if any).
7. Commit your changes (git commit -am 'Add some feature').
8. Push to the branch (git push origin feature/my-new-feature).
9. Create a new Pull Request.

License

This project is licensed under the MIT License