README

Auto-generated PHP client for the Composio API v3.1.

This package is generated from Composio's OpenAPI document and is not maintained by Composio directly. The public PHP namespace remains BlockshiftNetwork\Composio.

Requirements

• PHP 8.1 or higher
• Composer
• PHP extensions: curl, json, mbstring

Installation

composer require blockshiftnetwork/composio-php

Authentication

<?php

require_once __DIR__ . '/vendor/autoload.php';

use BlockshiftNetwork\Composio\Configuration;

$config = Configuration::getDefaultConfiguration()
    ->setApiKey('x-api-key', 'YOUR_API_KEY')
    ->setHost('https://backend.composio.dev');

Supported auth keys generated from the OpenAPI document:

• x-api-key
• x-user-api-key
• x-org-api-key
• authToken cookie

Example

<?php

require_once __DIR__ . '/vendor/autoload.php';

use BlockshiftNetwork\Composio\Api\ToolkitsApi;
use BlockshiftNetwork\Composio\Configuration;
use GuzzleHttp\Client;

$config = Configuration::getDefaultConfiguration()
    ->setApiKey('x-api-key', 'YOUR_API_KEY');

$toolkits = new ToolkitsApi(new Client(), $config);
$response = $toolkits->getV31Toolkits();

print_r($response);

Generated endpoint documentation is available under docs/Api, and generated model documentation is available under docs/Model.

Regeneration

The SDK is generated from:

https://backend.composio.dev/api/v3.1/openapi.json

The upstream OpenAPI document currently needs a small normalization pass:

• three session_id path parameters are not marked required: true
• four toolkit_versions query parameters need deepObject metadata so PHP can preserve bracket notation such as toolkit_versions[gmail]=20250930_00

The normalizer preserves the API shape and only fixes invalid or underspecified OpenAPI metadata before code generation.

After generation:

• scripts/fix-generated-query-serialization.php patches the generated query serializer so map-like array<string,...> query values keep their keys for deepObject parameters.
• scripts/fix-generated-map-serialization.php patches JSON request serialization so empty map-like fields such as tool arguments are sent as {} instead of [].
• scripts/fix-generated-connected-account-state.php patches the generated connected-account state wrapper so real OAUTH2 state responses deserialize correctly instead of being constrained to the last inline oneOf branch.
• scripts/fix-generated-duplicates.php removes duplicate PHP methods that OpenAPI Generator can emit for inline schemas whose JSON fields converge to the same accessor name. Without this post-process, a few generated models/tests are not loadable by PHP.

Regenerate with:

composer run openapi:regenerate

For future OpenAPI/API-version updates, follow the maintained checklist in docs/MAINTAINING.md. It covers updating the upstream spec URL/version, reviewing normalizations and post-generation patches, running official docs verification, live read-only checks, live end-to-end tool execution, tests, lint, and release-level decisions.

Equivalent manual commands:

php scripts/update-openapi-spec.php
openapi-generator-cli validate -i openapi/composio-v3.1.openapi.json
php scripts/clean-generated.php
openapi-generator-cli generate -c openapi-generator-config.json --minimal-update
php scripts/fix-generated-query-serialization.php
php scripts/fix-generated-map-serialization.php
php scripts/fix-generated-connected-account-state.php
php scripts/fix-generated-duplicates.php

Verification

Use the official Composio reference check to compare the generated local OpenAPI snapshot against the public documentation:

composer run docs:verify

This downloads the current pages linked from https://docs.composio.dev/reference, extracts every documented /api/v3.1 endpoint, and verifies that each one exists in openapi/composio-v3.1.openapi.json with a generated PHP API method.

Run the generated tests and maintained smoke tests with:

composer test

The maintained smoke tests use Guzzle's mock handler to verify representative generated requests for authentication headers, query serialization, path parameter replacement, JSON request bodies, and response deserialization. They also cover PHP's empty-map edge case so request fields like arguments => [] serialize as JSON objects when the OpenAPI type is array<string,mixed>.

If .env contains COMPOSIO_API_KEY, run read-only live verification with:

composer run live:verify

This calls representative live GET endpoints and reports only HTTP status plus generic counts. It does not print credentials or response bodies.

For a release-gate end-to-end check against the live API, run:

composer run live:e2e

This uses the generated SDK to discover the no-auth read-only HACKERNEWS_GET_TOP_STORIES tool, fetch its schema, execute it through ToolsApi, create a Tool Router session, and execute the same tool through the session. It does not require connecting a third-party account, and it reports only statuses, model names, generic data types, and whether IDs are present.

Generation settings:

• OpenAPI Generator CLI: 7.22.0 via openapitools.json
• Generator: php
• Composer package: blockshiftnetwork/composio-php
• Invoker namespace: BlockshiftNetwork\Composio
• Variable naming convention: original
• API host: https://backend.composio.dev

Notes

• This release targets /api/v3.1 paths.
• The v3.1 OpenAPI surface generates 40 API classes and 449 model classes.
• Existing v3 generated model and method names may change because OpenAPI operation IDs now include V31.