The Cloud Stash Plugin is an extension for Grav CMS. Stash your users' form data in a secure cloud repository.
You might want this plugin if your users submit sensitive information you don't want to store on your web server. If you use specific cloud storage services, you can send your users' data there using credentials that are limited to dropping items and don't allow reads. In so doing, if your web server is compromised, attackers will not be able to access your users' sensitive data.
This could be handy for:
Installing the Cloud Stash plugin can be done in one of three ways: The GPM (Grav Package Manager) installation method lets you quickly install the plugin with a simple terminal command, the manual method lets you do so via a zip file, and the admin method lets you do so via the Admin Plugin.
This plugin requires the Form plugin to provide anything useful.
The Snappygrav plugin (>= v1.9.1) is also listed as a dependency, though you won't strictly need this if you don't need to stash PDF documents.
If you use this plugin without producing PDFs (Snappygrav), you could install it manually according to the instructions below.
Note that Snappygrav requires you to either install or make sure you have a PDF creation library available on your server.
To install the plugin via the GPM, through your system's terminal (also called the command line), navigate to the root of your Grav-installation, and enter:
bin/gpm install cloud-stash
This will install the Cloud Stash plugin into your /user/plugins
-directory within Grav. Its files can be found under /your/site/grav/user/plugins/cloud-stash
.
To install the plugin manually, download the zip-version of this repository and unzip it under /your/site/grav/user/plugins
. Then rename the folder to cloud-stash
. You can find these files on GitHub or via GetGrav.org.
You should now have all the plugin files under
/your/site/grav/user/plugins/cloud-stash
NOTE: This plugin is a modular component for Grav which may require other plugins to operate, please see its blueprints.yaml-file on GitHub.
If you use the Admin Plugin, you can install the plugin directly by browsing the Plugins
-menu and clicking on the Add
button.
Before configuring this plugin, you should copy the user/plugins/cloud-stash/cloud-stash.yaml
to user/config/plugins/cloud-stash.yaml
and only edit that copy.
Here is the default configuration and an explanation of available options:
enabled: true
stashes:
AWS:
region: '' # AWS BUCKET REGION
key: '' # AWS KEY
secret: '' # AWS PASSWORD
# domain: # e.g. 'backblazeb2.com' for Backblaze B2 (see https://www.backblaze.com/b2/docs/s3_compatible_api.html and below)
# e.g. 'linodeobjects.com' for Linode Object Storage stashes
# defaults:
# target: 'fave-bucket'
bucket
parameter. This allows different bucket targets per environment without needing to vary the form's YAML, so .. useful!Note that if you use the Admin Plugin, a file with your configuration named cloud-stash.yaml will be saved in the user/config/plugins/
-folder once the configuration is saved in the Admin.
At present the plugin only supports Amazon Web Services S3 buckets and S3-compatible API service buckets/objects, but has been developed to facilitate adding support for other service providers.
The plugin defines two new form actions for Grav forms. Place these as required under the process
form YAML property.
stash
saves a form data file, and optionally file field attachments uploaded through the form, to a remote storage location that you specify.stash_pdf
saves a formatted PDF file based on form input, and optionally file fields uploaded through the form, to a remote storage location that you specify.If you use both of these actions, you probably only want to specify that file fields be stashed in one of those actions. If you specify any field twice, its attachment will be overwritten. This is mostly harmless except for the extra traffic and time taken.
stash
actionThe parameters fileprefix
, filepostfix
, dateformat
, dateraw
, filename
, extension
, and body
are available and function identically to the form plugin's bundled 'save' action parameters.
Just like the 'save' action, if you omit the body
parameter, your output will be formatted using the 'forms/data.html.twig' template from your theme, Form plugin, or other location in your Twig path.
stash
specifies the stash name as configured under stashes
in this plugin's configuration.
provider
deprecated for stash
, will be interpreted as stash
if provided in lieu of stash
. It's ignored if you provide it as well.
bucket
is S3-specific and may be deprecated for a more service-agnostic term in the near future. It specifies the name of the S3-compatible bucket into which you want to stash your form data.
add_uploads
is a YAML list of file field names from the form, which indicates that you would like those files to be uploaded to the remote stash as well.
operation
is not supported and is ignored. Documents/objects are always created.
…
process:
…
- stash:
filename: "{{ 'questionnaire-' ~ form.value['timestamp']|date('Ymd-His') ~ '-' ~ form.value['respondent-name']|e|split(' ')|last|lower ~ '.yaml' }}"
foldername: "{{ form.value['timestamp']|date('Ymd-His') ~ '-' ~ form.value['respondent-name']|e|split(' ')|last|lower }}"
extension: yaml
body: "{% include 'forms/data.txt.twig' %}"
stash: AWS # old property 'provider' still supported, don't use it though
bucket: MY.BUCKET.NAME
add_uploads:
- attachments
- supporting_documents
…
stash_pdf
actionAs per the stash
action except that extension
will be ignored and set to ".pdf".
…
process:
…
- stash_pdf:
filename: "{{ 'application-' ~ form.value['timestamp']|date('Ymd-His') ~ '-' ~ form.value['applicant-name']|e|split(' ')|last|lower ~ '.pdf' }}"
foldername: "{{ form.value['timestamp']|date('Ymd-His') ~ '-' ~ form.value['applicant-name']|e|split(' ')|last|lower }}"
body: "{% include 'forms/application-print.html.twig' %}"
stash: B2 # old property 'provider' still supported, don't use it though
bucket: MY.BUCKET.NAME
…
This plugin makes use of a bunch of wonderful open source software and requires the Snappygrav plugin to produce PDFs for uploading/stashing.
Many thanks to Matt Marsh (@marshmn) and @robertorubioguardia for S3 advice and mentoring.
TODO: more credits
The most important TODOs have been added as repository issues for now. FIXME
Dropbox support is not a priority because it doesn't support write-only permissions, despite its name. It may, however, have value for its ability to provide seamless mount points to the user's local file system.