PHP - Onlyform API

onlyform/onlyform-php is the official PHP 8.1+ package. It has no third-party runtime dependencies and includes a cURL transport. The current release targets API contract 2026-08-01.

Install

composer require onlyform/onlyform-php

Configure the client

use Onlyform\Client;

$onlyform = new Client(
    apiKey: $_ENV['ONLYFORM_API_KEY'],
);

The client uses https://api.onlyform.com by default. Use the optional baseUrl constructor argument only for private development environments.

Create a complete form

The create call accepts blocks, settings, and theme tokens inside definition.

$created = $onlyform->forms()->create(
    name: 'Product feedback',
    workspaceId: '507f1f77bcf86cd799439012',
    type: 'MULTI',
    definition: [
        'blocks' => [[
            'id' => 'rating',
            'type' => 'rating',
            'label' => 'How would you rate the product?',
            'description' => '',
            'required' => true,
            'properties' => ['max' => 5, 'icon' => 'star'],
        ]],
        'settings' => ['progressBar' => true],
        'theme' => [
            'font' => 'Inter',
            'colors' => ['primary' => '#3969D9'],
        ],
    ],
);

echo $created['id'];

See Form definitions, Block types, and Theme tokens for the complete accepted schema.

Add and remove blocks

Versioned form and block operations return a VersionedResponse. Pass its ETag back with ifMatch when editing blocks.

$current = $onlyform->forms()->retrieve('form_id');

$added = $onlyform->forms()->blocks()->create(
    formId: 'form_id',
    block: [
        'id' => 'email',
        'type' => 'email',
        'label' => 'Email address',
        'description' => 'Where should we reply?',
        'required' => true,
        'properties' => [],
    ],
    ifMatch: $current->etag,
);

$onlyform->forms()->blocks()->delete(
    formId: 'form_id',
    blockId: 'email',
    ifMatch: $added->etag,
);

Use replaceAll($formId, $blocks, $ifMatch) to atomically replace the complete ordered block collection.

Update a form

$current = $onlyform->forms()->retrieve('form_id');

$updated = $onlyform->forms()->update(
    formId: 'form_id',
    changes: [
        'name' => 'Customer feedback',
        'definition' => [
            'settings' => ['progressBar' => false],
            'theme' => ['font' => 'Georgia', 'colors' => ['primary' => '#3969D9']],
        ],
    ],
    ifMatch: $current->etag,
);

Cursor pagination

$cursor = null;

do {
    $page = $onlyform->forms()->list(limit: 100, cursor: $cursor);

    foreach ($page['items'] as $form) {
        echo $form['id'] . PHP_EOL;
    }

    $cursor = $page['page']['next_cursor'];
} while ($cursor !== null);

Other resources

$workspaces = $onlyform->workspaces()->list(limit: 50);
$submissions = $onlyform->forms()->submissions()->list('form_id', limit: 100);
$metrics = $onlyform->forms()->analytics()->metrics('form_id', period: '30d');
$webhooks = $onlyform->webhooks()->list();

Handle errors

use Onlyform\Exception\ApiException;
use Onlyform\Exception\TransportException;

try {
    $onlyform->forms()->retrieve('form_id');
} catch (ApiException $error) {
    error_log(sprintf(
        '%d %s request=%s',
        $error->status,
        $error->errorCode,
        $error->requestId ?? 'unknown',
    ));
} catch (TransportException $error) {
    error_log($error->getMessage());
}

​Install

​Configure the client

​Create a complete form

​Add and remove blocks

​Update a form

​Cursor pagination

​Other resources

​Handle errors