Beautiful Open-Source Form Builder
<?php
namespace App\Jobs\Form;
use App\Events\Forms\FormSubmitted;
use App\Http\Requests\AnswerFormRequest;
use App\Service\Storage\FileUploadPathService;
use App\Models\Forms\Form;
use App\Models\Forms\FormSubmission;
use App\Service\Billing\Feature;
use App\Service\Forms\FormAutoIncrementSequence;
use App\Service\Forms\FormLogicPropertyResolver;
use App\Service\Forms\SubmissionAttribution;
use App\Service\Storage\StorageFileNameParser;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;
use Stevebauman\Purify\Facades\Purify;
/**
* Job to store form submissions
*
* This job handles the storage of form submissions, including processing of metadata
* and special field types like files and signatures.
*
* The job accepts all data in the submissionData array, including metadata fields:
* - submission_id: ID of an existing submission to update (must be an integer)
* - completion_time: Time in seconds it took to complete the form
* - is_partial: Whether this is a partial submission (will be stored with STATUS_PARTIAL)
* - submitter_ip: IP address of the submitter (will be stored in meta if form has IP tracking enabled)
* If not specified, submissions are treated as complete by default.
*
* These metadata fields will be automatically extracted and removed from the stored form data.
*
* For partial submissions:
* - The submission will be stored with STATUS_PARTIAL
* - All file uploads and signatures will be processed normally
* - The submission can later be updated to STATUS_COMPLETED when the user completes the form
*/
class StoreFormSubmissionJob implements ShouldQueue
{
use Dispatchable;
use InteractsWithQueue;
use Queueable;
use SerializesModels;
private const AUTO_INCREMENT_ID_PLACEHOLDER = '__opnform_auto_increment_id__';
public ?int $submissionId = null;
/**
* When true, allows updating a completed submission (admin edit path only).
*/
public bool $allowCompletedUpdate = false;
private ?array $formData = null;
private ?int $completionTime = null;
private bool $isPartial = false;
private bool $isClientProvidedSubmissionId = false;
private ?string $submitterIp = null;
private array $attribution = [];
private array $storedMeta = [];
private array $prefilledFileCopies = [];
/**
* Create a new job instance.
*
* @param Form $form The form being submitted
* @param array $submissionData Form data including metadata fields (submission_id, completion_time, etc.)
* @return void
*/
public function __construct(public Form $form, public array $submissionData)
{
}
/**
* Execute the job.
*
* @return void
*/
public function handle()
{
$this->extractMetadata();
$this->formData = $this->getFormData();
$this->addHiddenPrefills($this->formData);
$this->storeSubmission($this->formData);
$this->formData['submission_id'] = $this->submissionId;
if (!$this->isPartial) {
FormSubmitted::dispatch($this->form, $this->formData, $this->storedMeta);
}
}
/**
* Extract metadata from submission data
*
* This method extracts and removes metadata fields from the submission data:
* - submission_id
* - completion_time
* - is_partial
* - submitter_ip
*/
private function extractMetadata(): void
{
$this->attribution = app(SubmissionAttribution::class)->sanitize(
$this->submissionData['tracking_parameters'] ?? null
);
unset($this->submissionData['tracking_parameters']);
if (isset($this->submissionData['completion_time'])) {
$this->completionTime = $this->submissionData['completion_time'];
unset($this->submissionData['completion_time']);
}
if (isset($this->submissionData['submission_id']) && $this->submissionData['submission_id']) {
if (is_numeric($this->submissionData['submission_id'])) {
$this->submissionId = (int)$this->submissionData['submission_id'];
$this->isClientProvidedSubmissionId = true;
}
unset($this->submissionData['submission_id']);
}
if (isset($this->submissionData['is_partial'])) {
$this->isPartial = (bool)$this->submissionData['is_partial'];
unset($this->submissionData['is_partial']);
}
if (isset($this->submissionData['submitter_ip'])) {
$this->submitterIp = $this->submissionData['submitter_ip'];
unset($this->submissionData['submitter_ip']);
}
}
/**
* Get the submission ID
*
* @return int|null
*/
public function getSubmissionId()
{
return $this->submissionId;
}
/**
* Resolve the record to update
*
* @param array $submissionData
* @return int|null
*/
private function resolveRecordToUpdate(array $submissionData)
{
if (!$this->form->workspace?->hasFeature(Feature::EDITABLE_SUBMISSIONS) || !isset($this->form->database_fields_update) || $this->submissionId) {
return null;
}
$propertyIds = $this->form->database_fields_update;
$properties = collect($this->form->properties)->filter(function ($property) use ($propertyIds) {
return in_array($property['id'], $propertyIds);
});
// Every configured match must have a value before running a lookup.
// An empty or partial predicate could overwrite an unrelated submission.
if ($properties->isEmpty() || $properties->count() !== count($propertyIds)) {
return null;
}
$query = $this->form->submissions();
foreach ($properties as $property) {
$fieldId = $property['id'];
if (!array_key_exists($fieldId, $submissionData)
|| $submissionData[$fieldId] === null
|| $submissionData[$fieldId] === ''
|| $submissionData[$fieldId] === []) {
return null;
}
$newValue = $submissionData[$fieldId];
if ($property['type'] === 'phone_number' && !($property['use_simple_text_input'] ?? false)) {
$newValue = substr($newValue, 2);
if ($newValue === '') {
return null;
}
}
$query->where("data->$fieldId", $newValue);
}
$record = $query->first();
if ($record) {
return $record->id;
}
return null;
}
/**
* Store the submission in the database
*
* @param array $formData
*/
private function storeSubmission(array &$formData)
{
DB::transaction(function () use (&$formData) {
if ($recordToUpdate = $this->resolveRecordToUpdate($this->submissionData)) {
$this->submissionId = $recordToUpdate;
$this->isClientProvidedSubmissionId = true;
}
if ($this->submissionId) {
$submission = $this->form->submissions()->lockForUpdate()->findOrFail($this->submissionId);
// Completed submissions are terminal for public/partial saves (prevents race overwrites)
if (
$this->isPartial
&& !$this->allowCompletedUpdate
&& $submission->status === FormSubmission::STATUS_COMPLETED
) {
return;
}
} else {
$submission = new FormSubmission();
$submission->form_id = $this->form->id;
}
$isNewSubmission = !$submission->exists;
if ($this->isPartial) {
foreach ($formData as $fieldId => $value) {
if ($value === self::AUTO_INCREMENT_ID_PLACEHOLDER) {
unset($formData[$fieldId]);
}
}
} elseif (in_array(self::AUTO_INCREMENT_ID_PLACEHOLDER, $formData, true)) {
$existingData = $submission->exists ? ($submission->data ?? []) : [];
$isCompletedEdit = $submission->exists && $submission->status === FormSubmission::STATUS_COMPLETED;
$generatedAutoIncrementId = null;
foreach ($formData as $fieldId => $value) {
if ($value !== self::AUTO_INCREMENT_ID_PLACEHOLDER) {
continue;
}
if (array_key_exists($fieldId, $existingData)) {
$formData[$fieldId] = $existingData[$fieldId];
continue;
}
if ($isCompletedEdit) {
unset($formData[$fieldId]);
continue;
}
$generatedAutoIncrementId ??= FormAutoIncrementSequence::allocateNext($this->form);
$formData[$fieldId] = $generatedAutoIncrementId;
}
}
$submission->data = $formData;
$submission->completion_time = $this->completionTime;
$submission->status = $this->isPartial
? FormSubmission::STATUS_PARTIAL
: FormSubmission::STATUS_COMPLETED;
if (!$this->submissionId) {
$submission->public_id = Str::uuid()->toString();
}
$existingMeta = $submission->meta ?? [];
$metaChanged = false;
if ($this->prefilledFileCopies !== []) {
$existingMeta['prefilled_files'] = array_replace($existingMeta['prefilled_files'] ?? [], $this->prefilledFileCopies);
$metaChanged = true;
}
if ($isNewSubmission && !empty($this->attribution)) {
$existingMeta['attribution'] = $this->attribution;
$metaChanged = true;
}
if ($this->form->enable_ip_tracking && $this->form->workspace->hasFeature('enable_ip_tracking') && $this->submitterIp) {
$existingMeta['ip_address'] = $this->submitterIp;
$metaChanged = true;
}
if ($metaChanged) {
$submission->meta = $existingMeta;
}
$submission->save();
$this->submissionId = $submission->id;
$this->storedMeta = $submission->meta ?? [];
});
}
/**
* Retrieve data from request object, and pre-format it if needed.
* - Replace notionforms id with notion field ids
* - Clean \ in select id values
* - Stores file and replace value with url
* - Generate auto increment id & unique id features for rich text field
*/
private function getFormData()
{
$data = $this->submissionData;
$finalData = [];
$properties = collect($this->form->properties);
foreach ($data as $answerKey => $answerValue) {
$field = $properties->where('id', $answerKey)->first();
if (!$field) {
continue;
}
// For editable submissions, always include empty values to clear fields
// For field-matching updates, respect the form's clear_empty_fields_on_update setting
$shouldSkipEmpty = !$this->isClientProvidedSubmissionId && !($this->form->clear_empty_fields_on_update ?? false);
if ($shouldSkipEmpty && (empty($answerValue) || is_null($answerValue)) && $answerValue !== 0 && $answerValue !== '0' && $answerValue !== false) {
continue;
}
// Sanitize only rich text; plain text fields are stored as-is and rendered safely in UI
if ($field['type'] === 'rich_text') {
if (is_string($answerValue)) {
// Ensure rich text is cleaned with strict allowlist (defense-in-depth)
$answerValue = Purify::clean($answerValue);
}
}
if (
($field['type'] == 'url' && isset($field['file_upload']) && $field['file_upload'])
|| $field['type'] == 'files'
) {
if (is_array($answerValue)) {
$processedFiles = [];
foreach ($answerValue as $fileItem) {
if (is_string($fileItem) && !empty($fileItem)) {
$singleStoredFile = $this->storeFile($fileItem, $field);
if ($singleStoredFile) {
$processedFiles[] = $singleStoredFile;
}
}
}
$finalData[$field['id']] = $processedFiles;
} else {
if (is_string($answerValue) && !empty($answerValue)) {
$singleFileResult = $this->storeFile($answerValue, $field);
$finalData[$field['id']] = $singleFileResult;
} else {
$finalData[$field['id']] = $this->storeFile($answerValue, $field); // Handles null/empty $answerValue by returning null
}
}
} else {
// Standard field processing (text, ID generation, etc.)
if (isset($field['generates_uuid']) && $field['generates_uuid'] && $field['type'] == 'text') {
if (empty($answerValue) || !Str::isUuid($answerValue)) {
$finalData[$field['id']] = $this->workspaceHasIdGenerationAccess() ? Str::uuid()->toString() : 'Please upgrade your OpenForm subscription to use our ID generation features';
} else {
$finalData[$field['id']] = $answerValue;
}
} elseif (isset($field['generates_auto_increment_id']) && $field['generates_auto_increment_id'] && $field['type'] == 'text') {
if (empty($answerValue) || !is_numeric($answerValue)) {
$finalData[$field['id']] = $this->autoIncrementIdPlaceholder();
} else {
$finalData[$field['id']] = $answerValue;
}
} else {
$finalData[$field['id']] = $answerValue;
}
}
// Special field types
if ($field['type'] == 'signature') {
$finalData[$field['id']] = $this->storeSignature($answerValue);
}
if ($field['type'] == 'phone_number' && $answerValue && ctype_alpha(substr($answerValue, 0, 2)) && (!isset($field['use_simple_text_input']) || !$field['use_simple_text_input'])) {
$finalData[$field['id']] = substr($answerValue, 2);
}
}
return $finalData;
}
// This is use when updating a record, and file uploads aren't changed.
private function isSkipForUpload($value)
{
$parser = StorageFileNameParser::parse($value);
$canonicalStoredName = $parser->getMovedFileName();
if (!$canonicalStoredName) {
return false; // Input $value couldn't be resolved to a canonical stored name format
}
$fullPathToCheck = FileUploadPathService::getFileUploadPath($this->form->id, $canonicalStoredName);
return Storage::exists($fullPathToCheck);
}
/**
* Custom Back-end Value formatting. Use case:
* - File uploads (move file from tmp storage to persistent)
*
* File can have 2 formats:
* - file_name-{uuid}.{ext}
* - {uuid}
*/
private function storeFile($value, ?array $field = null)
{
if (is_null($value) || empty($value)) {
return null;
}
// Re-check URLs here because partial submissions may skip request validation.
// Submission processing must never move shared form assets.
if (filter_var($value, FILTER_VALIDATE_URL) !== false) {
if ($assetName = FileUploadPathService::resolvePrefilledAssetUrl($value, $field)) {
if ($this->prefilledFileCopies === []) {
$existingSubmissionId = $this->submissionId ?? $this->resolveRecordToUpdate($this->submissionData);
if ($existingSubmissionId) {
$existingSubmission = $this->form->submissions()->findOrFail($existingSubmissionId);
$this->prefilledFileCopies = $existingSubmission->meta['prefilled_files'] ?? [];
}
}
$copyKey = hash('sha256', json_encode([$field['id'], $assetName]));
$existingCopy = $this->prefilledFileCopies[$copyKey] ?? null;
if ($existingCopy && Storage::exists(FileUploadPathService::getFileUploadPath($this->form->id, $existingCopy))) {
return $existingCopy;
}
$parser = StorageFileNameParser::parse($assetName);
$parser->uuid = (string) Str::uuid();
$newFileName = $parser->getMovedFileName();
if (!Storage::copy('assets/forms/' . $assetName, FileUploadPathService::getFileUploadPath($this->form->id, $newFileName))) {
throw new \RuntimeException('File storage failed.');
}
$this->prefilledFileCopies[$copyKey] = $newFileName;
return $newFileName;
}
return FileUploadPathService::resolveSubmissionFileUrl($value, $this->form->id);
}
$shouldSkip = $this->isSkipForUpload($value);
if ($shouldSkip) {
// File (based on canonical name derived from $value) already exists in permanent storage.
// Return its canonical name.
$parser = StorageFileNameParser::parse($value);
return $parser->getMovedFileName() ?? $value; // Fallback to $value if canonical somehow fails (defensive)
}
// Process as a new file upload (or one whose temp version needs to be moved)
$fileNameParser = StorageFileNameParser::parse($value); // $value is the temp file reference (e.g., originalname_uuid.ext or uuid)
if (!$fileNameParser || !$fileNameParser->uuid) {
return null; // Cannot derive UUID from the reference
}
$fileNameInTmp = FileUploadPathService::getTmpFileUploadPath($fileNameParser->uuid);
if (!Storage::exists($fileNameInTmp)) {
return null; // Temporary file not found
}
$movedFileName = $fileNameParser->getMovedFileName(); // This is the canonical name for storage
if (empty($movedFileName)) {
return null; // Canonical name generation failed
}
$completeNewFilename = FileUploadPathService::getFileUploadPath($this->form->id, $movedFileName);
if (!Storage::move($fileNameInTmp, $completeNewFilename)) {
throw new \RuntimeException('File storage failed.');
}
return $movedFileName;
}
private function storeSignature(?string $value)
{
// If $value looks like a filename (already processed, e.g. during skip or previous handling)
if ($value && preg_match('/^[\/\w\-. ]+$/', $value)) {
return $this->storeFile($value); // Re-run through storeFile for consistency / skip logic
}
// If $value is base64 data
if ($value == null || !isset(explode(',', $value)[1])) {
return null;
}
$fileName = 'sign_' . (string) Str::uuid() . '.png';
$completeNewFilename = FileUploadPathService::getFileUploadPath($this->form->id, $fileName);
if (!Storage::put($completeNewFilename, base64_decode(explode(',', $value)[1]))) {
throw new \RuntimeException('File storage failed.');
}
return $fileName;
}
/**
* Adds prefill from hidden fields
*
* @param AnswerFormRequest $request
*/
private function addHiddenPrefills(array &$formData): void
{
collect($this->form->properties)->filter(function ($property) {
return FormLogicPropertyResolver::isHidden($property, $this->submissionData, $this->form);
})->each(function (array $property) use (&$formData) {
// If a value is already set, we don't do anything for this property
if (array_key_exists($property['id'], $formData) && $formData[$property['id']] !== '' && $formData[$property['id']] !== [] && !is_null($formData[$property['id']])) {
return;
}
// Handle ID Generation for text fields
if ($property['type'] == 'text') {
if (isset($property['generates_uuid']) && $property['generates_uuid']) {
$formData[$property['id']] = $this->workspaceHasIdGenerationAccess() ? Str::uuid()->toString() : 'Please upgrade your OpenForm subscription to use our ID generation features';
return;
}
if (isset($property['generates_auto_increment_id']) && $property['generates_auto_increment_id']) {
$formData[$property['id']] = $this->autoIncrementIdPlaceholder();
return; // ID generated, so we skip prefill logic for this field.
}
}
// From here, it's prefill logic.
if (!isset($property['prefill']) || is_null($property['prefill'])) {
return;
}
if (in_array($property['type'], ['files']) || ($property['type'] == 'url' && isset($property['file_upload']) && $property['file_upload'])) {
return;
}
if ($property['type'] === 'date' && isset($property['prefill_today']) && $property['prefill_today']) {
$formData[$property['id']] = now()->format((isset($property['with_time']) && $property['with_time']) ? 'Y-m-d H:i' : 'Y-m-d');
} else {
$formData[$property['id']] = $property['prefill'];
}
});
}
/**
* Get the processed form data including the submission ID
*
* @return array
*/
public function getProcessedData(): array
{
if ($this->formData === null) {
$this->formData = $this->getFormData();
}
$data = $this->formData;
$data['submission_id'] = $this->submissionId;
return $data;
}
private function workspaceHasIdGenerationAccess(): bool
{
$workspace = $this->form->workspace;
if (!$workspace) {
return false;
}
return $workspace->hasFeature(Feature::ID_GENERATION);
}
private function autoIncrementIdPlaceholder(): string
{
if (!$this->workspaceHasIdGenerationAccess()) {
return 'Please upgrade your OpenForm subscription to use our ID generation features';
}
return self::AUTO_INCREMENT_ID_PLACEHOLDER;
}
}