Survey module

This module is responsible for different types of surveys or participation tools. It leverages the FormApi to allow users to build and render surveys. It handles storage of submissions and provides the framework for different survey types.

Survey types

Survey type plugins define how a survey might behave, fields available and background business logic. See Plugins/SurveyTypes for examples.

Submission storage

Multiple database tables (and associated models) are used for storage of submission data

  • submissions this is the metadata information for a submission, eg IP, user, date, etc. It does not store submission data as this is dynamic.
  • submission_data the raw fields for the submissions, this is one row for each field + delta combination. This is related back to the submission.
  • submission_cache the indexed and cached version of submission data, this table may be rebuilt at any time and contains the parsed and prepared submission data that may require expensive compute to build.

Submission data

This is the raw submission data and should not be mutable once saved. It should be the source of truth for submission data and is used to re-generate submission cache. As a general rule, try to use submission cache over this, that said submission data is great for basic filtering.

Filtering submissions via a handy scope whereDataValue example:

Survey::find(1)
  ->submissions()
  ->whereDataValue('favourite_colours', 'Blue');
// Or a bit more complex.
Survey::find(1)
  ->submissions()
  ->whereDataValue('favourite_colours', 'Blu%', 'LIKE')
  ->whereDataValue('favourite_colours', 'red', '=', 'or');

Submission cache

To provide optimal performance whilst allowing flexibility for parsing (now and in the future) a submission cache is used, this gets built via a background job whenever a survey submission is made and can be rebuilt at any time to add in additional computed data (eg adding NL processing results to a text field).

Cache data structure

All the parsed submission data is added to a Json data field on the SubmissionCache model which then can be queried.

A handy scope is available for filtering on submission data stored in cache whereCacheValue. Example:

Survey::find(1)
  ->submissions()
  ->whereCacheValue('favourite_colours', 'Blue');
// Or a pre-computed cached field
Survey::find(1)
  ->submissions()
  ->whereCacheValue('your_comment', 'negative', 'sentiment');

@todo future scopes:

NOTE: Whenever outputting submission data in lists (eg index/exports/etc) use submissionCache rather than submissionData as it is way faster.

Rebuilding cache data

It should be rare that this is required, but if it is, you can rebuild the submission cache for every survey with:

php artisan survey:rebuild-submission-cache

or just a single survey by providing the id:

php artisan survey:rebuild-submission-cache --survey-id=1