PHP

<?php

$runtimeUrl = getenv('FORMERIE_RUNTIME_URL') ?: 'https://forms.formerie.com';
// Your form. This is the only line that names it.
$form = getenv('FORMERIE_FORM') ?: 'acme/contact';

$curl = curl_init("$runtimeUrl/$form/submit");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'fields' => [
            'name' => 'Jane Example',
            'email' => 'jane@example.com',
            'message' => 'Hello from my server',
        ],
    ], JSON_THROW_ON_ERROR),
]);
$body = curl_exec($curl);
if ($body === false) {
    exit('Could not reach Formerie: ' . curl_error($curl) . "\n");
}
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
$result = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
echo $status, ' ', $result['ok'] ? $result['submissionUid'] : $result['error']['code'], "\n";

<?php

$runtimeUrl = getenv('FORMERIE_RUNTIME_URL') ?: 'https://forms.formerie.com';
// Your form. This is the only line that names it.
$form = getenv('FORMERIE_FORM') ?: 'acme/contact';

$curl = curl_init("$runtimeUrl/$form/submit");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        // Keep the key out of your code. A test is stored apart and emails nobody.
        'X-Formerie-Test-Key: ' . getenv('FORMERIE_TEST_KEY'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'fields' => ['name' => 'Jane Example', 'email' => 'jane@example.com', 'message' => 'Just a test'],
    ], JSON_THROW_ON_ERROR),
]);
$body = curl_exec($curl);
if ($body === false) {
    exit('Could not reach Formerie: ' . curl_error($curl) . "\n");
}
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
$result = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
echo $status, ' ', $result['ok'] ? $result['submissionUid'] : $result['error']['code'], "\n";

<?php

function formerieUrl(string $action): string
{
    $runtimeUrl = getenv('FORMERIE_RUNTIME_URL') ?: 'https://forms.formerie.com';
    // Your form. This is the only line that names it.
    $form = getenv('FORMERIE_FORM') ?: 'acme/contact';

    return "$runtimeUrl/$form/$action";
}

/** Checks answers and stores nothing. With no step, only the fields you send are checked. */
function checkAnswers(array $fields, ?string $step = null): array
{
    $payload = $step === null
        ? ['mode' => 'partial', 'fields' => $fields]
        : ['mode' => 'step', 'step' => $step, 'fields' => $fields];

    $curl = curl_init(formerieUrl('validate'));
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
    ]);
    $body = curl_exec($curl);
    if ($body === false) {
        throw new RuntimeException(curl_error($curl));
    }

    $result = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
    if (!$result['ok'] && $result['error']['code'] !== 'VALIDATION_FAILED') {
        throw new RuntimeException($result['error']['code']);
    }

    return $result;
}

<?php

function submitAnswers(array $fields): array
{
    $runtimeUrl = getenv('FORMERIE_RUNTIME_URL') ?: 'https://forms.formerie.com';
    // Your form. This is the only line that names it.
    $form = getenv('FORMERIE_FORM') ?: 'acme/contact';

    $curl = curl_init("$runtimeUrl/$form/submit");
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(['fields' => $fields], JSON_THROW_ON_ERROR),
    ]);
    $body = curl_exec($curl);
    if ($body === false) {
        throw new RuntimeException(curl_error($curl));
    }

    return json_decode($body, true, flags: JSON_THROW_ON_ERROR);
}

/** Finds the visitor's answer for a path such as contact.email, so the form can show it again. */
function answerAt(array $answers, string $path): string
{
    $value = $answers;
    foreach (explode('.', $path) as $part) {
        $value = is_array($value) ? ($value[$part] ?? '') : '';
    }

    return is_scalar($value) ? (string) $value : '';
}

/** One input with its answer kept and its first message under it. */
function renderField(string $path, array $answers, array $result): string
{
    $name = htmlspecialchars($path);
    $value = htmlspecialchars(answerAt($answers, $path));
    $message = $result['error']['fields'][$path][0]['message'] ?? null;
    $error = $message === null ? '' : '<p class="error">' . htmlspecialchars($message) . '</p>';

    return "<input name=\"$name\" value=\"$value\">$error";
}

<?php

const MAX_ATTEMPTS = 3;
const LONGEST_WAIT = 30;
const TEMPORARY_CODES = ['FORM_MAINTENANCE', 'QUEUE_FAILED', 'INTERNAL_ERROR'];

/** One attempt. Says what happened, and whether another attempt could help. */
function sendOnce(array $fields, string $key): array
{
    $runtimeUrl = getenv('FORMERIE_RUNTIME_URL') ?: 'https://forms.formerie.com';
    // Your form. This is the only line that names it.
    $form = getenv('FORMERIE_FORM') ?: 'acme/contact';
    $after = null;

    $curl = curl_init("$runtimeUrl/$form/submit");
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'fields' => $fields,
            'metadata' => ['idempotencyKey' => $key],
        ], JSON_THROW_ON_ERROR),
        CURLOPT_HEADERFUNCTION => function ($curl, string $header) use (&$after): int {
            if (preg_match('/^retry-after:\s*(\d+)\s*$/i', $header, $match)) {
                $after = (int) $match[1];
            }

            return strlen($header);
        },
    ]);
    $body = curl_exec($curl);
    if ($body === false) {
        return ['outcome' => 'retry-later', 'reason' => 'network', 'again' => true];
    }
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);

    // Only the short-term limit sends Retry-After. A form's own limit can last an hour, so don't wait for it.
    if ($status === 429) {
        return [
            'outcome' => 'retry-later',
            'reason' => 'rate-limited',
            'after' => $after,
            'again' => $after !== null && $after <= LONGEST_WAIT,
        ];
    }

    // Something in front of Formerie may answer without JSON, so look at the status first.
    $result = json_decode($body, true);
    if (!is_array($result)) {
        return ['outcome' => 'retry-later', 'reason' => 'bad-response', 'again' => in_array($status, [502, 503, 504], true)];
    }

    if ($result['ok']) {
        return ['outcome' => 'accepted', 'id' => $result['submissionUid']];
    }
    $error = $result['error'];
    if ($error['code'] === 'DUPLICATE_SUBMISSION') {
        // The first send worked, and only its answer was lost.
        return ['outcome' => 'accepted', 'duplicate' => true];
    }
    if (in_array($error['code'], TEMPORARY_CODES, true)) {
        return ['outcome' => 'retry-later', 'reason' => $error['code'], 'again' => true];
    }
    if ($error['code'] === 'VALIDATION_FAILED') {
        return ['outcome' => 'invalid', 'code' => $error['code'], 'issues' => $error['issues']];
    }

    return ['outcome' => 'rejected', 'code' => $error['code'], 'message' => $error['message']];
}

/** One key per submission, the same on every retry. Store it with the answers if you retry later. */
function submitWithRetries(array $fields, ?string $key = null): array
{
    $key ??= bin2hex(random_bytes(16));
    for ($attempt = 1; ; $attempt++) {
        $answer = sendOnce($fields, $key);
        $again = $answer['again'] ?? false;
        unset($answer['again']);
        if (!$again || $attempt === MAX_ATTEMPTS) {
            return $answer + ['key' => $key, 'attempts' => $attempt];
        }
        $backoff = random_int(0, min(250 * 2 ** $attempt, 4000)) / 1000;
        usleep((int) (max($answer['after'] ?? 0, $backoff) * 1_000_000));
    }
}

<?php

/** $posted is what your form sent, such as $_POST. $origin is $_SERVER['HTTP_ORIGIN'] ?? ''. */
function submitVerified(array $posted, string $origin): array
{
    $runtimeUrl = getenv('FORMERIE_RUNTIME_URL') ?: 'https://forms.formerie.com';
    // Your form. This is the only line that names it.
    $form = getenv('FORMERIE_FORM') ?: 'acme/contact';

    $token = $posted['cf-turnstile-response'] ?? '';
    unset($posted['cf-turnstile-response']);

    $headers = ['Content-Type: application/json'];
    // Without the visitor's Origin, the provider's hostname can't match, and the check fails.
    if ($origin !== '') {
        $headers[] = "Origin: $origin";
    }

    $curl = curl_init("$runtimeUrl/$form/submit");
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_POSTFIELDS => json_encode(['fields' => $posted, 'verificationToken' => $token], JSON_THROW_ON_ERROR),
    ]);
    $body = curl_exec($curl);
    if ($body === false) {
        throw new RuntimeException(curl_error($curl));
    }

    return json_decode($body, true, flags: JSON_THROW_ON_ERROR);
}

<?php

function submitWithMetadata(array $fields, DateTimeImmutable $startedAt, string $visitorId): array
{
    $runtimeUrl = getenv('FORMERIE_RUNTIME_URL') ?: 'https://forms.formerie.com';
    // Your form. This is the only line that names it.
    $form = getenv('FORMERIE_FORM') ?: 'acme/contact';

    $curl = curl_init("$runtimeUrl/$form/submit");
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'fields' => $fields,
            'metadata' => [
                'idempotencyKey' => bin2hex(random_bytes(16)),
                // When the visitor opened the form, for the minimum submit time check.
                'startedAt' => $startedAt->setTimezone(new DateTimeZone('UTC'))->format('Y-m-d\TH:i:s\Z'),
                'pageUrl' => 'https://www.example.com/contact',
                // Your own visitor ID, for a limit rule with the deviceToken scope.
                'deviceToken' => $visitorId,
            ],
        ], JSON_THROW_ON_ERROR),
    ]);
    $body = curl_exec($curl);
    if ($body === false) {
        throw new RuntimeException(curl_error($curl));
    }

    return json_decode($body, true, flags: JSON_THROW_ON_ERROR);
}

<?php

use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Route;

Route::post('/contact', function (Request $request) {
    $runtimeUrl = env('FORMERIE_RUNTIME_URL', 'https://forms.formerie.com');
    // Your form. This is the only line that names it.
    $form = env('FORMERIE_FORM', 'acme/contact');
    try {
        $answer = Http::timeout(10)->post("$runtimeUrl/$form/submit", [
            // Name the fields you send, so a visitor can't add others.
            'fields' => $request->only(['name', 'email', 'message']),
        ]);
    } catch (ConnectionException) {
        // No connection or a timeout. Keep the visitor's answers on screen.
        return response()->json(['code' => 'TRY_AGAIN'], 503);
    }
    $result = $answer->json();
    if (!is_array($result)) {
        // Something in front of Formerie answered without JSON.
        return response()->json(['code' => 'TRY_AGAIN'], 503);
    }
    if ($result['ok']) {
        return response()->json(['id' => $result['submissionUid']], 202);
    }
    $errors = array_map(fn (array $issues) => array_column($issues, 'message'), $result['error']['fields'] ?? []);

    return response()->json(['code' => $result['error']['code'], 'errors' => $errors], $answer->status());
});

composer require symfony/http-client

<?php

namespace App;

use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;

class ContactController
{
    public function __construct(private HttpClientInterface $client)
    {
    }

    public function __invoke(Request $request): JsonResponse
    {
        $runtimeUrl = getenv('FORMERIE_RUNTIME_URL') ?: 'https://forms.formerie.com';
        // Your form. This is the only line that names it.
        $form = getenv('FORMERIE_FORM') ?: 'acme/contact';
        try {
            $answer = $this->client->request('POST', "$runtimeUrl/$form/submit", [
                'timeout' => 10,
                'max_duration' => 10,
                // Name the fields you send, so a visitor can't add others.
                'json' => ['fields' => [
                    'name' => $request->request->getString('name'),
                    'email' => $request->request->getString('email'),
                    'message' => $request->request->getString('message'),
                ]],
            ]);
            // false, so a 422 is read and doesn't throw.
            $result = $answer->toArray(false);
        } catch (ExceptionInterface) {
            // No connection, a timeout, or an answer that isn't JSON. Keep the visitor's answers on screen.
            return new JsonResponse(['code' => 'TRY_AGAIN'], 503);
        }
        if ($result['ok']) {
            return new JsonResponse(['id' => $result['submissionUid']], 202);
        }
        $errors = array_map(fn (array $issues) => array_column($issues, 'message'), $result['error']['fields'] ?? []);

        return new JsonResponse(['code' => $result['error']['code'], 'errors' => $errors], $answer->getStatusCode());
    }
}