PHPackages                             craftcms/guest-entries - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. craftcms/guest-entries

ActiveCraft-plugin[Utility & Helpers](/categories/utility)

craftcms/guest-entries
======================

This plugin allows you to save guest entries from the front-end of your website.

4.0.1(1y ago)10693.0k↑12.5%24[10 issues](https://github.com/craftcms/guest-entries/issues)[2 PRs](https://github.com/craftcms/guest-entries/pulls)3MITPHPCI passing

Since Jul 14Pushed 1y ago8 watchersCompare

[ Source](https://github.com/craftcms/guest-entries)[ Packagist](https://packagist.org/packages/craftcms/guest-entries)[ RSS](/packages/craftcms-guest-entries/feed)WikiDiscussions 4.x Synced 1mo ago

READMEChangelog (2)Dependencies (4)Versions (23)Used By (3)

Guest Entries for Craft CMS
===========================

[](#guest-entries-for-craft-cms)

Allow guests to create entries from your site’s front end.

Requirements
------------

[](#requirements)

*Guest Entries* requires Craft CMS 4.0.0+ or 5.0.0+.

Installation
------------

[](#installation)

You can install *Guest Entries* from the [Plugin Store](https://plugins.craftcms.com/guest-entries) or with Composer.

### From the Plugin Store

[](#from-the-plugin-store)

Go to the **Plugin Store** in your project’s control panel (in an environment that allows [admin changes](https://craftcms.com/docs/4.x/config/general.html#allowadminchanges)), search for “Guest Entries,” then click **Install**.

### With Composer

[](#with-composer)

Open your terminal and run the following commands:

```
# Navigate to your project directory:
cd /path/to/my-project

# Require the plugin package with Composer:
composer require craftcms/guest-entries -w

# Install the plugin with Craft:
php craft plugin/install guest-entries
```

Settings
--------

[](#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
-----

[](#usage)

A basic guest entry template should look something like this:

```
{# Macro to help output errors: #}
{% macro errorList(errors) %}
    {% if errors %}
        {{ ul(errors, { class: 'errors' }) }}
    {% endif %}
{% endmacro %}

{# Default value for the `entry` variable: #}
{% set entry = entry ?? null %}

    {# Hidden inputs required for the form to work: #}
    {{ csrfInput() }}
    {{ actionInput('guest-entries/save') }}

    {# Custom redirect URI: #}
    {{ redirectInput('success') }}

    {# Section for new entries: #}
    {{ hiddenInput('sectionHandle', 'mySectionHandle') }}

    {# Entry properties and custom fields: #}
    Title
    {{ input('text', 'title', entry ? entry.title, { id: 'title' }) }}
    {{ entry ? _self.errorList(entry.getErrors('title')) }}

    Body
    {{ tag('textarea', {
        text: entry ? entry.body,
        id: 'body',
        name: 'fields[body]',
    }) }}
    {{ entry ? _self.errorList(entry.getErrors('body')) }}

    {# ... #}

    Publish

```

> **Note**
> The process of submitting data and handling success and error states is outlined in the [controller actions](https://craftcms.com/docs/4.x/dev/controller-actions.html) documentation.

### Supported Params

[](#supported-params)

The following parameters can be sent with a submission:

NameNotesRequired`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()`](https://docs.craftcms.com/api/v4/craft-helpers-datetimehelper.html#method-todatetime)`expiryDate`Value should be processable by [`DateTimeHelper::toDateTime()`](https://docs.craftcms.com/api/v4/craft-helpers-datetimehelper.html#method-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](#sending-custom-fields) you want guests to be able to populate.### Form Tips

[](#form-tips)

#### Specifying a Section + Entry Type

[](#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](https://craftcms.com/docs/4.x/project-config.html#ids-uuids-and-handles) 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:

```
{% set targetSection = craft.app.sections.getSectionByHandle('resources') %}
{% set entryTypes = targetSection.getEntryTypes() %}

{# Select a single type, identified by its handle: #}
{% set targetEntryType = collect(entryTypes).firstWhere('handle', 'document') %}

{{ hiddenInput('sectionId', targetSection.id) }}
{{ hiddenInput('typeId', targetEntryType.id) }}
```

#### Sending Custom Fields

[](#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](https://craftcms.com/docs/4.x/fields.html#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](#events) to clear values or reject submissions.

#### Validation Errors

[](#validation-errors)

If there are validation errors on the entry, the page will be reloaded with the populated [`craft\elements\Entry`](https://docs.craftcms.com/api/v4/craft-elements-entry.html) 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()`](http://www.yiiframework.com/doc-2.0/yii-base-model.html#getErrors()-detail), [`getFirstError()`](http://www.yiiframework.com/doc-2.0/yii-base-model.html#getFirstError()-detail), or [`getFirstErrors()`](http://www.yiiframework.com/doc-2.0/yii-base-model.html#getFirstErrors()-detail).

> **Note**
> The `entry` variable can be renamed with the “Entry Variable Name” [setting](#settings) 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

[](#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](https://craftcms.com/docs/4.x/dev/functions.html#redirectinput). The path is evaluated as an [object template](https://craftcms.com/docs/4.x/dev/controller-actions.html#after-a-post-request), and can include properties of the saved entry in `{curlyBraces}`.

### Submitting via Ajax

[](#submitting-via-ajax)

If you submit your form [via Ajax](https://craftcms.com/docs/4.x/dev/controller-actions.html#ajax) with an `Accept: application/json` header, a JSON response will be returned with the following keys:

- `success` *(boolean)* – Whether the entry was saved successfully
- `errors` *(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

[](#viewing-entries)

Using a [`redirect`](#redirection) 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

[](#enabled-by-default)

Entries in sections with URLs can be viewed immediately, with this `redirect` param:

```
{{ redirectInput('{url}') }}
```

#### Disabled by Default

[](#disabled-by-default)

In order to display an entry that is *disabled*, you will need to set up a custom [route](https://craftcms.com/docs/4.x/routing.html#advanced-routing-with-url-rules)…

```