README

Official PHP client library for interacting with the FormPanel API. Submit form data programmatically from your PHP applications with full type safety, retry logic, and error handling.

Requirements

PHP 8.2 or higher
Composer

Installation

Install the package via Composer:

composer require formpanel/formpanel-php

Quick Start

use Formpanel\FormClient;

// Initialize the client with your API key and form slug
$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
);

// Submit form data
$result = $client->submit([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'message' => 'Hello from PHP!',
]);

echo "Submission ID: " . $result->id;

Configuration

Basic Configuration

use Formpanel\FormClient;

// Default configuration
$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
);

// Custom base URL
$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
    baseUrl: 'https://custom-api.example.com/api/v1',
);

// Custom timeout (default: 30 seconds)
$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
    timeout: 60,
);

Retry Configuration

The client includes automatic retry with exponential backoff for transient errors:

use Formpanel\FormClient;
use Formpanel\Http\RetryConfig;

// Custom retry configuration
$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
    retryConfig: new RetryConfig(
        maxRetries: 5,           // Maximum retry attempts (default: 3)
        baseDelayMs: 500,        // Base delay in ms (default: 1000)
        maxDelayMs: 60000,       // Maximum delay in ms (default: 30000)
        multiplier: 2.0,         // Exponential multiplier (default: 2.0)
    ),
);

// Disable retries
$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
    retryConfig: RetryConfig::noRetries(),
);

Logging

Enable PSR-3 compatible logging for debugging:

use Formpanel\FormClient;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('formpanel');
$logger->pushHandler(new StreamHandler('php://stdout', Logger::DEBUG));

$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
    logger: $logger,
);

Usage

Submit Form Data

use Formpanel\FormClient;
use Formpanel\Exceptions\ValidationException;
use Formpanel\Exceptions\FormpanelException;

$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
);

try {
    $result = $client->submit([
        'name' => 'Jane Doe',
        'email' => 'jane@example.com',
        'message' => 'I would like more information.',
    ]);

    if ($result->success) {
        echo "Form submitted successfully!\n";
        echo "Submission ID: {$result->id}\n";
        echo "Message: {$result->message}\n";
    }
} catch (ValidationException $e) {
    echo "Validation failed:\n";
    foreach ($e->getErrors() as $field => $errors) {
        echo "  - {$field}: " . implode(', ', $errors) . "\n";
    }
} catch (FormpanelException $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Get Form Details

Retrieve form configuration and field definitions:

$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
);

$form = $client->get();

echo "Form: {$form->name}\n";
echo "Status: {$form->status}\n";
echo "Fields:\n";

foreach ($form->fields as $field) {
    echo "  - {$field->name} ({$field->type})";
    echo $field->required ? " [required]" : "";
    echo "\n";
}

Error Handling

The library provides specific exception classes for different error scenarios:

Exception Hierarchy

FormpanelException (base exception)
├── ParseException (response parsing errors)
└── ApiException (API errors with status codes)
    ├── AuthenticationException (401)
    ├── NotFoundException (404)
    ├── ValidationException (422)
    └── RateLimitException (429)

Handling Specific Exceptions

use Formpanel\FormClient;
use Formpanel\Exceptions\AuthenticationException;
use Formpanel\Exceptions\ValidationException;
use Formpanel\Exceptions\NotFoundException;
use Formpanel\Exceptions\RateLimitException;
use Formpanel\Exceptions\FormpanelException;

$client = new FormClient(
    apiKey: 'your-api-key',
    formSlug: 'contact-form',
);

try {
    $result = $client->submit($data);

} catch (AuthenticationException $e) {
    // Invalid API key (401)
    echo "Authentication failed: " . $e->getMessage();

} catch (NotFoundException $e) {
    // Form not found (404)
    echo "Form not found: " . $e->getMessage();

} catch (ValidationException $e) {
    // Validation errors (422)
    echo "Validation failed: " . $e->getMessage();

    foreach ($e->getErrors() as $field => $messages) {
        echo "  {$field}: " . implode(', ', $messages) . "\n";
    }

} catch (RateLimitException $e) {
    // Rate limit exceeded (429)
    echo "Rate limit exceeded. Retry after: " . $e->getRetryAfter() . " seconds";

} catch (FormpanelException $e) {
    // Other errors (network issues, parsing errors, etc.)
    echo "Error: " . $e->getMessage();
}

Response Objects

SubmissionResult

Returned by $client->submit():

$result = $client->submit($data);

$result->id;       // string - Submission UUID
$result->success;  // bool - Whether submission was successful
$result->message;  // string - Success/error message

Form

Returned by $client->get():

$form = $client->get();

$form->id;          // string - Form UUID
$form->name;        // string - Form name
$form->slug;        // string - Form slug
$form->description; // ?string - Form description
$form->status;      // string - Form status (e.g., 'active')
$form->fields;      // FormField[] - Array of field definitions
$form->createdAt;   // DateTimeImmutable
$form->updatedAt;   // DateTimeImmutable

FormField

foreach ($form->fields as $field) {
    $field->name;        // string - Field name/identifier
    $field->label;       // string - Display label
    $field->type;        // string - Field type
    $field->required;    // bool - Whether field is required
    $field->placeholder; // ?string - Placeholder text
    $field->helpText;    // ?string - Help text
    $field->config;      // array - Additional configuration
}

Testing

The client supports dependency injection for testing:

use Formpanel\FormClient;
use Formpanel\Http\HttpClientInterface;

// Create a mock HTTP client
$mockHttpClient = new class implements HttpClientInterface {
    public function get(string $uri): array {
        return ['id' => 'test', 'name' => 'Test Form', /* ... */];
    }

    public function post(string $uri, array $data): array {
        return ['submission_id' => 'test-123', 'success' => true, 'message' => 'OK'];
    }
};

// Inject mock client
$client = new FormClient(
    apiKey: 'test-key',
    formSlug: 'test-form',
    httpClient: $mockHttpClient,
);

Run the test suite:

composer install
composer test

Run static analysis:

composer analyse

Run both:

composer check

Security

Always keep your API key secure
Never commit API keys to version control
Use environment variables for API keys

$client = new FormClient(
    apiKey: getenv('FORMPANEL_API_KEY'),
    formSlug: 'contact-form',
);

Support

GitHub: github.com/formpanel/formpanel-php
Documentation: formpanel.com/docs
Email: support@formpanel.com

License

MIT License. See LICENSE file for details.

formpanel / formpanel-php

Maintainers

Details