Skip to content

Beautiful Open-Source Form Builder

25.0 KB
Raw Blame
<?php

namespace App\Service\Forms;

use App\Models\Forms\Form;
use App\Models\Workspace;
use App\Rules\ComputedVariablesRule;
use App\Rules\CssOnlyRule;
use App\Rules\FormPropertiesRule;
use App\Rules\PublicMediaUrlRule;
use App\Service\Forms\AgentFormFieldCatalog as FieldCatalog;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
use Illuminate\Validation\ValidationException;
use JsonException;
use Stevebauman\Purify\Facades\Purify;

class AgentFormDefinition
{
    public const SCHEMA_VERSION = 1;

    public const MAX_DEFINITION_BYTES = 1_000_000;

    private const ALLOWED_TOP_LEVEL_KEYS = [
        'schema_version',
        'title',
        'visibility',
        'properties',
        'computed_variables',
        'language',
        'font_family',
        'theme',
        'presentation_style',
        'width',
        'size',
        'layout_rtl',
        'border_radius',
        'dark_mode',
        'color',
        'uppercase_labels',
        'no_branding',
        'transparent_background',
        'translations',
        'cover_picture',
        'cover_settings',
        'logo_picture',
        'custom_code',
        'custom_css',
        'submit_button_text',
        're_fillable',
        're_fill_button_text',
        'submitted_text',
        'redirect_url',
        'max_submissions_count',
        'max_submissions_reached_text',
        'editable_submissions',
        'editable_submissions_button_text',
        'confetti_on_submission',
        'show_progress_bar',
        'auto_save',
        'auto_focus',
        'enable_partial_submissions',
        'enable_ip_tracking',
        'can_be_indexed',
        'use_captcha',
        'captcha_provider',
        'seo_meta',
        'settings',
        'analytics',
    ];

    public function __construct(
        private readonly FormDataNormalizer $normalizer,
        private readonly FormValidationIssueMapper $issueMapper,
    ) {
    }

    public function normalizeAndValidate(array $definition, ?Workspace $workspace = null): array
    {
        $definition = $this->migrate($definition);
        $definition = array_replace($this->defaults(), $definition);
        $definition = $this->normalizer->normalize($definition, backfillPropertyIds: true);
        $definition['properties'] = collect($definition['properties'])->map(function ($property) {
            if (! is_array($property)) {
                return $property;
            }

            $property = array_replace([
                'help' => null,
                'hidden' => false,
                'required' => false,
                'placeholder' => null,
                'width' => 'full',
            ], $property);

            if (($property['type'] ?? null) === 'nf-text' && isset($property['content'])) {
                $property['content'] = Purify::clean((string) $property['content']);
            }

            return $property;
        })->values()->all();

        $this->validate($definition, $workspace);

        return Arr::only($definition, self::ALLOWED_TOP_LEVEL_KEYS);
    }

    public function validate(array $definition, ?Workspace $workspace = null): void
    {
        $unknownKeys = array_values(array_diff(array_keys($definition), self::ALLOWED_TOP_LEVEL_KEYS));

        if ($unknownKeys !== []) {
            throw ValidationException::withMessages([
                'definition' => ['Unknown top-level keys: '.implode(', ', $unknownKeys).'.'],
            ]);
        }

        try {
            $encodedDefinition = json_encode($definition, JSON_THROW_ON_ERROR);
        } catch (JsonException) {
            throw ValidationException::withMessages([
                'definition' => ['The form definition must contain valid JSON values.'],
            ]);
        }

        if (strlen($encodedDefinition) > self::MAX_DEFINITION_BYTES) {
            throw ValidationException::withMessages([
                'definition' => ['The form definition must not exceed 1 MB.'],
            ]);
        }

        $validator = Validator::make($definition, [
            'schema_version' => ['required', 'integer', Rule::in([self::SCHEMA_VERSION])],
            'title' => ['required', 'string', 'max:255'],
            'visibility' => ['required', Rule::in(Form::VISIBILITY)],
            'properties' => ['required', 'array', 'min:1', 'max:'.FormStructureValidator::MAX_PROPERTY_COUNT, new FormPropertiesRule($workspace)],
            'properties.*.help' => ['nullable', 'string'],
            'properties.*.image.url' => ['nullable', new PublicMediaUrlRule()],
            'computed_variables' => ['nullable', 'array', new ComputedVariablesRule()],
            'language' => ['required', Rule::in(Form::LANGUAGES)],
            'font_family' => ['nullable', 'string'],
            'theme' => ['required', Rule::in(Form::THEMES)],
            'presentation_style' => ['required', Rule::in(Form::PRESENTATION_STYLES)],
            'width' => ['required', Rule::in(Form::WIDTHS)],
            'size' => ['required', Rule::in(Form::SIZES)],
            'layout_rtl' => ['required', 'boolean'],
            'border_radius' => ['required', Rule::in(Form::BORDER_RADIUS)],
            'dark_mode' => ['required', Rule::in(Form::DARK_MODE_VALUES)],
            'color' => ['required', 'string'],
            'uppercase_labels' => ['required', 'boolean'],
            'no_branding' => ['required', 'boolean'],
            'transparent_background' => ['required', 'boolean'],
            'translations' => ['nullable', 'array'],
            'cover_picture' => ['nullable', new PublicMediaUrlRule()],
            'cover_settings' => ['nullable', 'array'],
            'cover_settings.focal_point' => ['sometimes', 'nullable', 'array'],
            'cover_settings.focal_point.x' => ['sometimes', 'nullable', 'numeric', 'min:0', 'max:100'],
            'cover_settings.focal_point.y' => ['sometimes', 'nullable', 'numeric', 'min:0', 'max:100'],
            'cover_settings.brightness' => ['sometimes', 'nullable', 'integer', 'min:-100', 'max:100'],
            'logo_picture' => ['nullable', new PublicMediaUrlRule()],
            'custom_code' => ['nullable', 'string'],
            'custom_css' => ['nullable', 'string', new CssOnlyRule()],
            'submit_button_text' => ['nullable', 'string', 'max:50'],
            're_fillable' => ['required', 'boolean'],
            're_fill_button_text' => ['nullable', 'string', 'max:50'],
            'submitted_text' => ['required', 'string', 'max:10000'],
            'redirect_url' => ['nullable', 'string'],
            'max_submissions_count' => ['nullable', 'integer', 'min:1'],
            'max_submissions_reached_text' => ['nullable', 'string'],
            'editable_submissions' => ['required', 'boolean'],
            'editable_submissions_button_text' => ['required', 'string', 'min:1', 'max:50'],
            'confetti_on_submission' => ['required', 'boolean'],
            'show_progress_bar' => ['required', 'boolean'],
            'auto_save' => ['required', 'boolean'],
            'auto_focus' => ['required', 'boolean'],
            'enable_partial_submissions' => ['required', 'boolean'],
            'enable_ip_tracking' => ['required', 'boolean'],
            'can_be_indexed' => ['required', 'boolean'],
            'use_captcha' => ['required', 'boolean'],
            'captcha_provider' => ['required', Rule::in(['recaptcha', 'hcaptcha'])],
            'seo_meta' => ['nullable', 'array'],
            'settings' => ['present', 'array'],
            'settings.navigation_arrows' => ['sometimes', 'boolean'],
            'settings.auto_next' => ['sometimes', 'boolean'],
            'analytics' => ['nullable', 'array'],
            'analytics.provider' => ['nullable', Rule::in(['meta_pixel', 'google_analytics', 'gtm'])],
            'analytics.tracking_id' => [
                'nullable',
                'string',
                'max:50',
                'regex:/^[A-Za-z0-9\-_\.]+$/',
                'required_if:analytics.provider,meta_pixel,google_analytics,gtm',
            ],
        ], [
            'theme.in' => 'theme must be one of: default, simple, notion, minimal, transparent.',
            'presentation_style.in' => 'presentation_style must be one of: classic, focused.',
            'width.in' => 'width must be one of: centered, full.',
            'size.in' => 'size must be one of: sm, md, lg.',
            'border_radius.in' => 'border_radius must be one of: none, small, full.',
            'dark_mode.in' => 'dark_mode must be one of: auto, light, dark.',
        ]);

        if ($validator->passes()) {
            return;
        }

        $errors = $validator->errors()->toArray();
        $pathErrors = $this->issueMapper->pathErrors($errors);

        throw ValidationException::withMessages($pathErrors !== [] ? $pathErrors : $errors);
    }

    public function defaults(): array
    {
        return [
            'schema_version' => self::SCHEMA_VERSION,
            'title' => 'Untitled Form',
            'visibility' => 'draft',
            'properties' => [],
            'computed_variables' => [],
            'language' => 'en',
            'font_family' => null,
            'theme' => 'default',
            'presentation_style' => 'classic',
            'width' => 'centered',
            'size' => 'md',
            'layout_rtl' => false,
            'border_radius' => 'small',
            'dark_mode' => 'auto',
            'color' => '#3B82F6',
            'uppercase_labels' => false,
            'no_branding' => false,
            'transparent_background' => false,
            'translations' => [],
            'cover_picture' => null,
            'cover_settings' => [],
            'logo_picture' => null,
            'custom_code' => null,
            'custom_css' => null,
            'submit_button_text' => null,
            're_fillable' => false,
            're_fill_button_text' => null,
            'submitted_text' => 'Amazing, we saved your answers. Thank you for your time and have a great day!',
            'redirect_url' => null,
            'max_submissions_count' => null,
            'max_submissions_reached_text' => 'This form has now reached the maximum number of allowed submissions and is now closed.',
            'editable_submissions' => false,
            'editable_submissions_button_text' => 'Edit submission',
            'confetti_on_submission' => false,
            'show_progress_bar' => false,
            'auto_save' => true,
            'auto_focus' => true,
            'enable_partial_submissions' => false,
            'enable_ip_tracking' => false,
            'can_be_indexed' => true,
            'use_captcha' => false,
            'captcha_provider' => 'recaptcha',
            'seo_meta' => [],
            'settings' => [],
            'analytics' => [],
        ];
    }

    /**
     * Return the canonical agent-editable portion of an existing form.
     */
    public function fromForm(Form $form): array
    {
        $definition = ['schema_version' => self::SCHEMA_VERSION];

        foreach (self::ALLOWED_TOP_LEVEL_KEYS as $key) {
            if ($key === 'schema_version') {
                continue;
            }

            if (array_key_exists($key, $form->getAttributes())) {
                $definition[$key] = $form->getAttribute($key);
            }
        }

        return $definition;
    }

    public function jsonSchema(): array
    {
        return [
            '$schema' => 'https://json-schema.org/draft/2020-12/schema',
            '$id' => 'https://opnform.com/schemas/agent-form-definition/v1.json',
            'title' => 'OpnForm Agent Form Definition v1',
            'type' => 'object',
            'additionalProperties' => false,
            'required' => ['schema_version', 'title', 'properties'],
            'properties' => [
                'schema_version' => ['const' => self::SCHEMA_VERSION],
                'title' => ['type' => 'string', 'minLength' => 1, 'maxLength' => 255],
                'visibility' => ['type' => 'string', 'enum' => Form::VISIBILITY, 'default' => 'draft'],
                'properties' => [
                    'type' => 'array',
                    'minItems' => 1,
                    'maxItems' => 500,
                    'items' => ['$ref' => '#/$defs/block'],
                ],
                'computed_variables' => [
                    'type' => 'array',
                    'maxItems' => ComputedVariablesRule::MAX_VARIABLE_COUNT,
                    'items' => ['$ref' => '#/$defs/computedVariable'],
                    'default' => [],
                    'description' => 'Calculated values available to other formulas and display logic. Formula references use braces, for example {budget} * 1.2.',
                ],
                'language' => ['type' => 'string', 'enum' => Form::LANGUAGES, 'default' => 'en'],
                'font_family' => ['type' => ['string', 'null']],
                'theme' => ['type' => 'string', 'enum' => Form::THEMES, 'default' => 'default'],
                'presentation_style' => ['type' => 'string', 'enum' => Form::PRESENTATION_STYLES, 'default' => 'classic'],
                'width' => ['type' => 'string', 'enum' => Form::WIDTHS, 'default' => 'centered'],
                'size' => ['type' => 'string', 'enum' => Form::SIZES, 'default' => 'md'],
                'layout_rtl' => ['type' => 'boolean', 'default' => false],
                'border_radius' => ['type' => 'string', 'enum' => Form::BORDER_RADIUS, 'default' => 'small'],
                'dark_mode' => ['type' => 'string', 'enum' => Form::DARK_MODE_VALUES, 'default' => 'auto'],
                'color' => ['type' => 'string', 'default' => '#3B82F6'],
                'uppercase_labels' => ['type' => 'boolean', 'default' => false],
                'no_branding' => ['type' => 'boolean', 'default' => false],
                'transparent_background' => ['type' => 'boolean', 'default' => false],
                'translations' => ['type' => ['object', 'array'], 'default' => (object) []],
                'cover_picture' => ['type' => ['string', 'null'], 'format' => 'uri', 'pattern' => '^https://'],
                'cover_settings' => ['type' => ['object', 'array'], 'default' => (object) []],
                'logo_picture' => ['type' => ['string', 'null'], 'format' => 'uri', 'pattern' => '^https://'],
                'custom_code' => ['type' => ['string', 'null']],
                'custom_css' => ['type' => ['string', 'null']],
                'submit_button_text' => ['type' => ['string', 'null'], 'maxLength' => 50],
                're_fillable' => ['type' => 'boolean', 'default' => false],
                're_fill_button_text' => ['type' => ['string', 'null'], 'maxLength' => 50],
                'submitted_text' => ['type' => 'string', 'maxLength' => 10000],
                'redirect_url' => ['type' => ['string', 'null']],
                'max_submissions_count' => ['type' => ['integer', 'null'], 'minimum' => 1],
                'max_submissions_reached_text' => ['type' => ['string', 'null']],
                'editable_submissions' => ['type' => 'boolean', 'default' => false],
                'editable_submissions_button_text' => ['type' => 'string', 'minLength' => 1, 'maxLength' => 50],
                'confetti_on_submission' => ['type' => 'boolean', 'default' => false],
                'show_progress_bar' => ['type' => 'boolean', 'default' => false],
                'auto_save' => ['type' => 'boolean', 'default' => true],
                'auto_focus' => ['type' => 'boolean', 'default' => true],
                'enable_partial_submissions' => ['type' => 'boolean', 'default' => false],
                'enable_ip_tracking' => ['type' => 'boolean', 'default' => false],
                'can_be_indexed' => ['type' => 'boolean', 'default' => true],
                'use_captcha' => ['type' => 'boolean', 'default' => false],
                'captcha_provider' => ['type' => 'string', 'enum' => ['recaptcha', 'hcaptcha'], 'default' => 'recaptcha'],
                'seo_meta' => ['type' => ['object', 'array'], 'default' => (object) []],
                'settings' => ['type' => ['object', 'array'], 'default' => (object) []],
                'analytics' => ['type' => ['object', 'array'], 'default' => (object) []],
            ],
            '$defs' => [
                'block' => [
                    'type' => 'object',
                    'required' => ['name', 'type'],
                    'additionalProperties' => true,
                    'properties' => [
                        'id' => [
                            'type' => 'string',
                            'description' => 'Stable technical block identifier. Omit it for new blocks so the server generates one. Never reuse it as visible label copy.',
                        ],
                        'name' => [
                            'type' => 'string',
                            'minLength' => 1,
                            'description' => 'Respondent-facing label in sentence case with natural spaces, such as Full name or Email address. Never use snake_case, kebab-case, database keys, or variable names.',
                        ],
                        'type' => ['type' => 'string', 'enum' => FieldCatalog::types()],
                        'content' => [
                            'type' => 'string',
                            'description' => 'For nf-text blocks only: sanitized HTML fragment, never Markdown. Example: <h1>Contact us</h1><p>How can we help?</p>.',
                        ],
                        'help' => ['type' => ['string', 'null']],
                        'hidden' => ['type' => 'boolean', 'default' => false],
                        'required' => ['type' => 'boolean', 'default' => false],
                        'placeholder' => ['type' => ['string', 'null']],
                        'width' => ['type' => 'string', 'enum' => ['full', '1/2', '1/3', '2/3', '1/4', '3/4'], 'default' => 'full'],
                        'image' => ['$ref' => '#/$defs/blockImage'],
                        'logic' => [
                            'anyOf' => [
                                ['$ref' => '#/$defs/displayLogic'],
                                ['type' => 'null'],
                            ],
                            'description' => 'Optional conditional behavior for this target block. Empty or safely invalid logic is removed during normalization.',
                        ],
                    ],
                ],
                'computedVariable' => [
                    'type' => 'object',
                    'additionalProperties' => true,
                    'required' => ['id', 'name', 'formula'],
                    'properties' => [
                        'id' => [
                            'type' => 'string',
                            'pattern' => '^cv_',
                            'description' => 'Unique technical identifier beginning with cv_. It must not duplicate a block ID.',
                        ],
                        'name' => ['type' => 'string', 'minLength' => 1, 'maxLength' => 100],
                        'formula' => [
                            'type' => 'string',
                            'minLength' => 1,
                            'maxLength' => 2000,
                            'description' => 'Expression referencing block or computed-variable IDs with braces, for example {budget} * 1.2.',
                        ],
                        'result_type' => ['type' => ['string', 'null'], 'enum' => ['number', 'text', 'auto', null]],
                    ],
                ],
                'displayLogic' => [
                    'type' => 'object',
                    'additionalProperties' => true,
                    'required' => ['conditions', 'actions'],
                    'properties' => [
                        'conditions' => ['$ref' => '#/$defs/logicCondition'],
                        'actions' => [
                            'type' => 'array',
                            'minItems' => 1,
                            'uniqueItems' => true,
                            'items' => ['type' => 'string', 'enum' => \App\Rules\PropertyValidators\LogicPropertyValidator::ACTIONS_VALUES],
                            'description' => 'Allowed actions depend on the target block state and type; validate_form_definition returns the exact path for an incompatible action.',
                        ],
                    ],
                ],
                'logicCondition' => [
                    'oneOf' => [
                        ['$ref' => '#/$defs/logicConditionGroup'],
                        ['$ref' => '#/$defs/logicLeafCondition'],
                    ],
                ],
                'logicConditionGroup' => [
                    'type' => 'object',
                    'additionalProperties' => true,
                    'required' => ['operatorIdentifier', 'children'],
                    'properties' => [
                        'operatorIdentifier' => ['type' => 'string', 'enum' => ['and', 'or']],
                        'children' => [
                            'type' => 'array',
                            'minItems' => 1,
                            'maxItems' => \App\Rules\PropertyValidators\LogicPropertyValidator::MAX_CONDITION_COUNT,
                            'items' => ['$ref' => '#/$defs/logicCondition'],
                        ],
                    ],
                ],
                'logicLeafCondition' => [
                    'type' => 'object',
                    'additionalProperties' => true,
                    'required' => ['identifier', 'value'],
                    'properties' => [
                        'identifier' => [
                            'type' => 'string',
                            'minLength' => 1,
                            'description' => 'ID of the referenced field or computed variable. It must match value.property_meta.id.',
                        ],
                        'value' => ['$ref' => '#/$defs/logicConditionValue'],
                    ],
                ],
                'logicConditionValue' => [
                    'type' => 'object',
                    'additionalProperties' => true,
                    'required' => ['operator', 'property_meta'],
                    'properties' => [
                        'operator' => [
                            'type' => 'string',
                            'enum' => FieldCatalog::logicOperators(),
                            'description' => 'Comparison operator compatible with property_meta.type. Consult operators_by_reference_type in the field catalog.',
                        ],
                        'property_meta' => [
                            'type' => 'object',
                            'additionalProperties' => true,
                            'required' => ['id', 'type'],
                            'properties' => [
                                'id' => ['type' => 'string', 'minLength' => 1],
                                'type' => [
                                    'type' => 'string',
                                    'enum' => array_keys(FieldCatalog::logicOperatorsByReferenceType()),
                                    'description' => 'Use computed when referencing a computed variable; otherwise use the referenced field type.',
                                ],
                            ],
                        ],
                        'value' => [
                            'description' => 'Comparison value. Omit only for operators such as is_empty, is_not_empty, is_checked, or is_not_checked.',
                        ],
                    ],
                ],
                'blockImage' => [
                    'type' => 'object',
                    'additionalProperties' => true,
                    'properties' => [
                        'url' => ['type' => ['string', 'null'], 'format' => 'uri', 'pattern' => '^https://'],
                        'alt' => ['type' => ['string', 'null'], 'maxLength' => 125],
                        'layout' => [
                            'type' => ['string', 'null'],
                            'enum' => ['between', 'left-small', 'right-small', 'left-split', 'right-split', 'background', null],
                        ],
                        'focal_point' => [
                            'type' => ['object', 'null'],
                            'properties' => [
                                'x' => ['type' => 'number', 'minimum' => 0, 'maximum' => 100],
                                'y' => ['type' => 'number', 'minimum' => 0, 'maximum' => 100],
                            ],
                        ],
                        'brightness' => ['type' => 'integer', 'minimum' => -100, 'maximum' => 100],
                        'fade' => ['type' => 'boolean'],
                    ],
                ],
            ],
            'x-opnform-max-bytes' => self::MAX_DEFINITION_BYTES,
        ];
    }

    private function migrate(array $definition): array
    {
        $version = $definition['schema_version'] ?? self::SCHEMA_VERSION;

        if ($version !== self::SCHEMA_VERSION) {
            throw ValidationException::withMessages([
                'schema_version' => ["Unsupported schema version [{$version}]. Current version is ".self::SCHEMA_VERSION.'.'],
            ]);
        }

        $definition['schema_version'] = self::SCHEMA_VERSION;

        return $definition;
    }

}