> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms client

> Retrieve Paubox Form schemas and submit form responses using the PHP SDK.

The Forms client does not require API credentials. Forms are identified by a UUID that you obtain from the Paubox dashboard.

## Instantiation

```php theme={null}
$forms = new Paubox\PauboxForms();
```

## Get a form

Retrieve a form's metadata, field schema, and rendered HTML/CSS:

```php theme={null}
$form = $forms->getForm("your-form-uuid");

echo $form->title . PHP_EOL;
echo $form->form_html . PHP_EOL;
print_r($form->form_json);
```

The returned `stdClass` includes:

| Property           | Description                               |
| ------------------ | ----------------------------------------- |
| `title`            | Display name of the form                  |
| `form_json`        | Parsed field schema                       |
| `form_html`        | Rendered HTML for embedding               |
| `form_css`         | Associated stylesheet                     |
| `active`           | Whether the form is accepting submissions |
| `submission_count` | Number of submissions received            |

`getForm` throws `\Exception` if the form is not found or the response is invalid.

## Submit a form

```php theme={null}
$submission = new Paubox\Forms\FormSubmission();
$submission->setFormData([
    "first_name" => "Jane",
    "last_name"  => "Smith",
    "email"      => "jane@example.com",
]);

$result = $forms->submitForm("your-form-uuid", $submission);
// $result === true on success
```

`submitForm` returns `true` on a successful submission (HTTP 201) and throws `\Exception` on failure with a message containing the HTTP status code and response body.

### Submitting with file attachments

The maximum total request size is 250 MB.

```php theme={null}
$attachment = new Paubox\Forms\FormAttachment();
$attachment->setName("consent.pdf");
$attachment->setContent(base64_encode(file_get_contents("/path/to/consent.pdf")));

$submission = new Paubox\Forms\FormSubmission();
$submission->setFormData(["first_name" => "Jane"]);
$submission->setAttachments([$attachment]);

$result = $forms->submitForm("your-form-uuid", $submission);
```

The `FormAttachment` fields:

| Field     | Description                   |
| --------- | ----------------------------- |
| `name`    | File name including extension |
| `content` | Base64-encoded file content   |

## Error handling

Wrap calls in a try/catch block:

```php theme={null}
try {
    $form = $forms->getForm("your-form-uuid");
    $result = $forms->submitForm("your-form-uuid", $submission);
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . PHP_EOL;
}
```