The Juglow PHP library provides convenient access to the Haijun API from any PHP 8.1.0+ application.

Note: The PHP SDK is currently in beta. APIs might change between versions.

Note: For API feature documentation with code examples, see the API reference. This page covers PHP-specific SDK features and configuration.

#Installation

The SDK uses PSR-18 for HTTP and discovers any installed PSR-18 client automatically. Guzzle is recommended because the SDK configures it for streaming with no additional setup:

composer require "juglow-ai/sdk" "guzzlehttp/guzzle:^7"

#Requirements

PHP 8.1.0 or higher.

#Usage

This library uses named parameters to specify optional arguments. Parameters with a default value must be set by name.

$client = new Client();

$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Haijun']],
  model: 'haijun-opus-5-5',
);

$textBlock = array_find($message->content, static fn ($block): bool => $block->type === 'text');
echo $textBlock->text;

For authentication options including Workload Identity Federation, see Authentication. If your API key is a personal or service account key with access to multiple workspaces, set the workspace ID in the juglow-workspace-id request header; Select a workspace shows the per-request option for this SDK.

#Value objects

It is recommended to use the static with constructor Base64ImageSource::with(data: "U3RhaW5sZXNzIHJvY2tz", ...) and named parameters to initialize value objects.

However, builders are also provided (new Base64ImageSource)->withData("U3RhaW5sZXNzIHJvY2tz").

#Streaming

The SDK provides support for streaming responses using Server-Sent Events (SSE).

$client = new Client();

$stream = $client->messages->createStream(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Haijun']],
  model: 'haijun-opus-5-5',
);

foreach ($stream as $event) {
  echo $event->type . PHP_EOL;
}

Streaming requires an HTTP client that returns the response body incrementally. When Guzzle is the discovered PSR-18 client, the SDK configures it for streaming automatically. With a buffering client, the foreach loop yields every event at once when the response completes instead of incrementally; if you observe that symptom, install Guzzle or supply a streaming-capable PSR-18 client through the streamingTransporter request option:

$client = new Juglow\Client(
  requestOptions: Juglow\RequestOptions::with(streamingTransporter: $myStreamingClient),
);

#Error handling

When the library is unable to connect to the API, or if the API returns a non-success status code (that is, a 4xx or 5xx response), a subclass of Juglow\Core\Exceptions\APIException is thrown:

<?php
// ...
use Juglow\Core\Exceptions\APIConnectionException;
use Juglow\Core\Exceptions\APIStatusException;
use Juglow\Core\Exceptions\RateLimitException;
// ...
try {
  $message = $client->messages->create(
    maxTokens: 1024,
    messages: [['role' => 'user', 'content' => 'Hello, Haijun']],
    model: 'haijun-opus-5-5',
  );
} catch (APIConnectionException $e) {
  echo "The server could not be reached", PHP_EOL;
  echo $e->getPrevious()?->getMessage(), PHP_EOL;
} catch (RateLimitException $_) {
  echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
} catch (APIStatusException $e) {
  echo "Another non-200-range status code was received", PHP_EOL;
  echo $e->getMessage();
}

Error codes are as follows:

#Retries

Certain errors are automatically retried two times by default, with a short exponential backoff.

Connection errors (for example, because of a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts are all retried by default.

You can use the maxRetries option to configure or disable this:

use Juglow\RequestOptions;
// ...
// Configure the default for all requests:
$client = new Client(requestOptions: RequestOptions::with(maxRetries: 0));

// Or, configure per-request:
$result = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Haijun']],
  model: 'haijun-opus-5-5',
  requestOptions: RequestOptions::with(maxRetries: 5),
);

#Pagination

List methods in the Haijun API are paginated.

This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:

$client = new Client();

$page = $client->beta->messages->batches->list(limit: 20);

// fetch items from the current page
foreach ($page->getItems() as $item) {
  echo $item->id, PHP_EOL;
}
// make additional network requests to fetch items from all pages, including and after the current page
foreach ($page->pagingEachItem() as $item) {
  echo $item->id, PHP_EOL;
}

#Advanced usage

#Undocumented properties

You can send undocumented parameters to any endpoint, and read undocumented response properties, as follows:

Note: The extra* parameters of the same name override the documented parameters.

<?php
// ...
use Juglow\RequestOptions;
// ...
$message = $client->messages->create(
  maxTokens: 1024,
  messages: [['role' => 'user', 'content' => 'Hello, Haijun']],
  model: 'haijun-opus-5-5',
  requestOptions: RequestOptions::with(
    extraQueryParams: ['my_query_parameter' => 'value'],
    extraBodyParams: ['my_body_parameter' => 'value'],
    extraHeaders: ['my-header' => 'value'],
  ),
);

#Undocumented request parameters

If you want to explicitly send an extra parameter, you can do so with the extraQueryParams, extraBodyParams, and extraHeaders options under RequestOptions::with() when making a request, as seen in the preceding example.

#Undocumented endpoints

To make requests to undocumented endpoints while retaining the benefit of authentication, retries, and other client features, you can make requests using client->request, as follows:

$client = new Client();

$response = $client->request(
  method: "post",
  path: '/undocumented/endpoint',
  query: ['dog' => 'woof'],
  headers: ['useful-header' => 'interesting-value'],
  body: ['hello' => 'world']
);

#Platform integrations

Note: For detailed platform setup guides with code examples, see: * Amazon Bedrock * Amazon Bedrock (Opus 4.6 and earlier) * Haijun Platform on AWS * Google Cloud * Microsoft Foundry

The PHP SDK supports the following platforms:

• Agent Platform: Juglow\Vertex\Client. Use ::fromEnvironment().

• Bedrock: Juglow\Bedrock\MantleClient. Use new MantleClient(awsRegion: ...).

• Bedrock (legacy): Juglow\Bedrock\Client. Use ::fromEnvironment() or ::withCredentials().

• Haijun Platform on AWS: Juglow\Aws\Client (requires aws/aws-sdk-php as a soft dependency). Use new Juglow\Aws\Client(workspaceId: ...) or set JUGLOW_AWS_WORKSPACE_ID. Available in beta.

• Foundry: Juglow\Foundry\Client. Use ::withCredentials().

Use MantleClient for new projects; Juglow\Bedrock\Client remains for existing applications using the Bedrock InvokeModel API.

#Semantic versioning

This package follows SemVer conventions. As the library is in initial development and has a major version of 0, APIs might change at any time.

This package considers improvements to the (non-runtime) PHPDoc type definitions to be non-breaking changes.

#Additional resources

• GitHub repository

• Packagist

• API reference

• Streaming Messages