Download the PHP package craftcms/guest-entries without Composer
On this page you can find all versions of the php package craftcms/guest-entries. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package guest-entries
Guest Entries for Craft CMS
Allow guests to create entries from your site’s front end.
Requirements
Guest Entries requires Craft CMS 4.0.0+ or 5.0.0+.
Installation
You can install Guest Entries from the Plugin Store or with Composer.
From the Plugin Store
Go to the Plugin Store in your project’s control panel (in an environment that allows admin changes), search for “Guest Entries,” then click Install.
With Composer
Open your terminal and run the following commands:
Settings
From the plugin settings page, you can configure…
- …which sections should allow guest entry submissions;
- …the default entry authors and statuses;
- …and whether submissions should be validated before being accepted.
Usage
A basic guest entry template should look something like this:
Note
The process of submitting data and handling success and error states is outlined in the controller actions documentation.
Supported Params
The following parameters can be sent with a submission:
Name | Notes | Required |
---|---|---|
sectionHandle |
Determines what section the entry will be created in. | ✓ |
sectionUid |
Can be sent in lieu of sectionHandle . |
|
sectionId |
Can be sent in lieu of sectionHandle . |
|
typeId |
Entry type ID to use. This may affect which custom fields are required. When absent, the first configured type for the specified section is used. | |
title |
Optional if the section has automatic title formatting enabled. | ✓ |
slug |
Explicitly sets the new entry’s slug. | |
postDate |
Value should be processable by DateTimeHelper::toDateTime() |
|
expiryDate |
Value should be processable by DateTimeHelper::toDateTime() |
|
parentId |
Nest this entry under another. Invalid for channels and structures with a maximum depth of 1 . |
|
siteId |
Create the entry in a specific site. | |
enabledForSite |
Whether the entry should be enabled in this site. The global enabled setting is configurable by administrators, so this alone will not immediately publish something. |
|
fields[...] |
Any custom fields you want guests to be able to populate. |
Form Tips
Specifying a Section + Entry Type
The plugin determines what section the new entry is created in by looking for a sectionHandle
, sectionUid
, or sectionId
param, in this order. Entry types, on the other hand, can only be defined by a typeId
param—but because IDs can be unstable between environments, you must look them up by a known identifier.
Granted you will already have a section (or at least a section handle), the easiest way to do this is via the section model:
Sending Custom Fields
Custom field data should be nested under the fields
key, with the field name in [squareBrackets]
:
If entries in the designated section are enabled by default, validation will occur on all custom fields, meaning those marked as required in the entry type’s field layout must be sent with the submission. Refer to the field types documentation to learn about the kinds of values that Craft accepts.
Warning
Omitting a field from your form does not mean it is safe from tampering! Clever users may be able to modify the request payload and submit additional field data. If this presents a problem for your site, consider using an event to clear values or reject submissions.
Validation Errors
If there are validation errors on the entry, the page will be reloaded with the populated craft\elements\Entry
object available under an entry
variable. You can access the posted values from that object as though it were a normal entry—or display errors with getErrors()
, getFirstError()
, or getFirstErrors()
.
Note
Theentry
variable can be renamed with the “Entry Variable Name” setting in the control panel. This might be necessary if you want to use a form on an entry page that already injects a variable of that name.
Redirection
Send a redirect
param to send the user to a specific location upon successfully saving an entry. In the example above, this is handled via the redirectInput('...')
function. The path is evaluated as an object template, and can include properties of the saved entry in {curlyBraces}
.
Submitting via Ajax
If you submit your form via Ajax with an Accept: application/json
header, a JSON response will be returned with the following keys:
success
(boolean) – Whether the entry was saved successfullyerrors
(object) – All of the validation errors indexed by field name (if not saved)id
(string) – the entry’s ID (if saved)title
(string) – the entry’s title (if saved)authorUsername
(string) – the entry’s author’s username (if saved)dateCreated
(string) – the entry’s creation date in ISO 8601 format (if saved)dateUpdated
(string) – the entry’s update date in ISO 8601 format (if saved)postDate
(string, null) – the entry’s post date in ISO 8601 format (if saved and enabled)url
(string, null) – the entry’s public URL (if saved, enabled, and in a section that has URLs)
Viewing Entries
Using a redirect
param allows you to show a user some or all of the content they just submitted—even if the entry is disabled, by default.
Warning
Take great care when displaying untrusted content on your site, especially when subverting moderation processes!
Enabled by Default
Entries in sections with URLs can be viewed immediately, with this redirect
param:
Disabled by Default
In order to display an entry that is disabled, you will need to set up a custom route…
…and direct users to it by including {{ redirectInput('submissions/confirmation/{uid}') }}
in the entry form. Your template (_submissions/confirmation.twig
) will be responsible for looking up the disabled entry and displaying it, based on the entryUid
route token that Craft makes available:
This query selects only disabled
entries so that the “preview” is invalidated once the entry goes live. This “confirmation” URI does not need to match the actual URI of the entry.
Events
Guest Entries augments the normal events emitted during the entry lifecycle with a few of its own, allowing developers to customize the submission process.
The following snippets should be added to your plugin or module’s init()
method, per the official event usage instructions.
The beforeSaveEntry
event
Plugins can be notified before a guest entry is saved, using the beforeSaveEntry
event. This is also an opportunity to flag the submission as spam, and prevent it being saved:
The afterSaveEntry
event
Plugins can be notified after a guest entry is saved, using the afterSaveEntry
event:
The afterError
event
Plugins can be notified right after a submission is determined to be invalid using the afterError
event: