Skip to main content

Console Commands

Freeform includes several console commands to allow you to run cleanup tasks and other tasks.

​Generate Fake Submissions5.1.14+

If you ever need to generate fake submission data for testing purposes, you can do so with the freeform/submissions/generate CLI command.

Freeform will attempt to automatically generate content and select options for all of your form fields. For example, it will know that an Email field should contain an email address, a Number field should contain a number, a Date field will contain a valid date, a field with the word name in it should contain a name, it should check a few options in a Checkboxes field, etc. Please note that some of these checks like name may rely more on the English language. The creation date defaults to today but can be overridden. However, the times are always random within the specified period.

​Options

The following arguments are available:

  • --author-id, -a
    • The user ID to be assigned as the author of the generated submissions. Defaults to none (guest).
    • E.g. --author-id=1, -a=12
  • --count=10, -c
    • The number of submissions to generate. Defaults to 1.
    • E.g. --count=10, -c=100.
  • --dry-run
    • Displays a sample generated submission inside the CLI without actually creating the submissions in Freeform/Craft, allowing you to get a rough idea of what it will generate. Defaults to off.
  • --form, -f *required
    • The handle or ID of the form you wish to generate submissions for.
    • E.g. --form=contactForm, --form=12, -f=2.
  • --locale, -l
    • The locale to use when generating submissions. Defaults to en_US.
    • E.g. --locale=fr, --locale=fr_FR, -l=de.
  • --range-start, -rs
    • The starting date period to generate submissions between. Can also use relative wording, e.g. 3 weeks ago. Defaults to today.
    • E.g. --range-start="2024-03-01", --range-start="-1 week", --range-start="3 weeks ago".
  • --range-end, -re
    • The ending date period to generate submissions between. Can also use relative wording. Defaults to today.
    • E.g. --range-end="2024-12-31", --range-end="+1 week", --range-end="2 days".
  • --spam
    • Flags all submissions as spam so they appear in the Freeform Spam Folder.
  • --status, -s
    • The handle of ID of the status(es) to be used when generating submissions. Can be set to multiple comma-separated statuses. Defaults to using the default status set inside the form builder for the form.
    • E.g. --status="open,pending,closed", --status="testing", -s=pending.
  • --verbose, -v
    • Displays in the CLI all of the generated submission data that it created in Freeform/Craft. Defaults to off.

​Examples

Generate 10 spam submissions in French to the contactForm form:

php craft freeform/submissions/generate --form=contactForm --spam --count=10 --locale=fr

​Purge Commands

Freeform automatically attempts to routinely execute all of the below commands as Craft jobs, but they are available in the event you need to correct or troubleshoot an issue.

​Purge SubmissionsPro

Allows you to purge all submissions older than a specific number of days. Freeform automatically attempts to execute this service based on the specified number of days for the Automatically Purge Submission Data setting.

php craft freeform/purge/submissions --age-in-days=30

​Purge Spam
LitePro

Allows you to purge all spam submissions older than a specific number of days. Freeform automatically attempts to execute this service based on the specified number of days for the Automatically Purge Spam Submissions setting.

php craft freeform/purge/spam --age-in-days=30

​Purge Unfinalized Assets

Allows you to purge all unfinalized assets older than a specific number of minutes. Freeform automatically attempts to execute this service every 3 hours.

php craft freeform/purge/unfinalized-assets --age-in-minutes=180

​Cleanup Utilities

Freeform includes several cleanup utilities designed to resolve edge-case issues that may occasionally occur on some sites.

​Check Database Integrity5.16.6+

If you need to investigate a database warning in Freeform's Diagnostics page, you can run the following command from your Craft project directory:

php craft freeform/database/check-integrity

This checks Freeform's database structure and relationships, along with orphaned records and potential duplicates. An orphaned record is one whose parent record, such as a submission or form, no longer exists.

The command is read-only and does not change your database. If it reports an issue, the results can help your developer identify the next steps. Checks may take some time on larger sites.

​Delete Orphaned Data5.17.1+

The freeform/database/delete-orphans command cleans up orphaned Freeform records that can prevent missing foreign keys from being restored. It checks Freeform's expected relationships, including per-form submission content tables and dependent records whose parents are also orphaned.

Start with a preview from your Craft project directory:

php craft freeform/database/delete-orphans --dry-run=1

Running the command without options also performs a dry run. The results show the rows to delete and broken references to clear for each table. Deleted rows are counted once per table, even if more than one parent is missing. Cleared references are counted per relationship, so one retained row can have multiple references cleared.

Valid nullable references are preserved. If a broken relationship is defined to become NULL when its parent is deleted, cleanup clears the reference and keeps the owning record. For example, a form whose creator no longer exists is kept, with its creator reference cleared.

Applying cleanup permanently deletes orphaned Freeform data and its dependent rows. Review the preview and take a database backup first. Pause site writes, queue workers, and scheduled purges while applying cleanup and repairing keys.

Apply the cleanup after reviewing the preview:

php craft freeform/database/delete-orphans --apply=1

Then run the existing foreign-key repair command to restore missing keys:

php craft freeform/database/repair-foreign-keys --apply=1

Cleanup and foreign-key repair are separate commands. Cleanup does not restore keys, and repair does not delete orphaned data. If no orphaned records block restoration, you can run the repair command directly.

​Options

  • --dry-run=1
    • Previews cleanup without changing data. This is the default behavior. If supplied with --apply=1, the command still performs a dry run.
  • --apply=1
    • Permanently deletes orphaned rows and clears broken references defined as SET NULL.

Cleanup checks the schema before writing and applies its changes in a transaction. If an operation fails, cleanup changes are rolled back. Missing tables or columns, conflicting keys, or unsupported relationships require developer review before cleanup can proceed. Duplicate records and other structural issues also require separate review.

A preview exits with status 1 if cleanup work is found and 0 if there is nothing to clean. An applied cleanup exits with status 0 when successful. Errors return status 1.

​Repair Database Foreign Keys5.16.6+

Freeform uses foreign keys to maintain relationships between database records and help remove related data when submissions or forms are deleted. If Diagnostics reports missing foreign keys, you can inspect and restore them with the freeform/database/repair-foreign-keys command.

First, check the relationships and any orphaned records without making changes:

php craft freeform/database/repair-foreign-keys --dry-run=1

Running the command without options also performs a dry run. The results show which keys are missing and whether they can be restored. If orphaned records block restoration, preview and apply orphan cleanup before retrying the repair. Orphan counts from the repair command are per relationship and can include the same row more than once.

To restore missing keys, review the results and take a database backup. Run the repair while site writes, queue workers, and scheduled purges are paused:

php craft freeform/database/repair-foreign-keys --apply=1

This restores missing keys where the required tables and columns exist and no orphaned records block the repair. Existing matching keys are preserved, and submission data is not deleted or changed. Any conflicting keys or other issues are reported for your developer to review.

​Options

  • --dry-run=1
    • Checks the relationships without making changes. This is the default behavior. If supplied with --apply=1, the command still performs a dry run.
  • --apply=1
    • Restores missing foreign keys that can be safely added.

The Diagnostics page also offers Scan for orphaned submissions and Scan related data and duplicates for checking existing records. A clean scan means no issues were found in the records checked; it does not confirm that the foreign keys are present. Updating Freeform does not automatically restore missing keys.

​Resave SubmissionsNew in 5.1.13+, Improved in 5.10.13+ and 5.14.7+

If you need to resave all Freeform submissions, you can do so with the freeform/submissions/resave CLI command. If you need to also update the Craft Search Index, be sure to add --update-search-index.

  • --batch 5.14.7+
    • Specify the number of submissions that should be processed at a time.
    • E.g. --batch=100.
  • --dryRun 5.14.7+
    • Perform a dry run of the command to see how many submissions will be affected without actually making the changes. Defaults to off.
  • --siteId 5.10.13+
    • Specify a Site ID. When not used, defaults to all sites.
    • E.g. --siteId=3, --siteId=2 --siteId=3.
  • --status 5.10.13+
    • Specify a Status. When not used, defaults to all statuses.
    • E.g. --status=open, --status=open --status=pending.
  • --updateSearchIndex
    • Specifying this will also update the Craft Search Index. Defaults to off.
  • --verbose 5.14.7+
    • Displays in the CLI more information about the progress. Helpful with seeing --batch progress. Defaults to off.

Resaves all Freeform submissions. Updates the Craft Search Index as well.

php craft freeform/submissions/resave --updateSearchIndex

​Fix Submission Database Table Names5.14.10+

In Craft 5.9+, a breaking change in the Stringy library affects how Freeform generates database table names for form submissions. Freeform includes migrations that automatically correct this, but if your site is still affected, you can manually resolve the issue by running the following command:

php craft freeform/submissions/fix-table-names

​Migrate Craft 4 Element Titles5.1.13+

If you have upgraded your Craft 4 site to Craft 5, please note that the Craft migration process does not automatically migrate submission Element titles. In Craft 5, Element titles are now stored in the elements_sites table, and the content table which used to store Element titles is no longer used.

While most plugins could include a separate migration script to handle this, Freeform 5 supports both Craft 4 and Craft 5, making this path impossible. Instead, a CLI command has been included that needs to be executed once after upgrading from Craft 4 to Craft 5.

This CLI command is only applicable to sites that have migrated from Craft 4 to Craft 5 while Freeform was installed.

php craft freeform/submissions/fix-titles

​Convert Form Handles and Field Handles5.9.11+

This console command is available in the event you need to convert all form handles and field handles to camelCase or under_scores. This allows you to correct your data from much older versions of Freeform where dashes were allowed inside of form handles and field handles.

Common reasons for using this command would be:

  • To correct compatibility with GraphQL.
  • Dashes in forms and field handles are now considered invalid for Craft.
  • You want all of your forms and field handles to be more uniform.

After running this command, please review all templates and email notification templates to ensure that any hard-coded form handles and field handles are updated to match their new converted values.

​Options

The following arguments are available:

  • --case, -c
    • Convert dashes to underscores instead of camelCase. When not used, defaults to camelCase.
    • E.g. --case=underscores, -c=undercores.
  • --dry-run
    • Displays a list of all of the form and field handles that will be converted, as well as what they will be converted to inside the CLI without actually making the changes, allowing you to know what to expect. Defaults to off.

​Examples

Convert all forms and field handles with dashes to camelCase, e.g. my-field becomes myField, My_other_field becomes myOtherField.

php craft freeform/freeform/convert-handles
Page Feedback