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.