Newsletter general usage

Setup information

You will need to publish the config files

php artisan vendor:publish --tag enso-newsletter

To use this package, you will need to create one or more handlers. These should implement the Yadda\Enso\Newsletter\Contracts\NewsletterHandlerContract contract.

The handle function should perform any action you wish to take upon receiving a form submission, such as saving to the database or sending an email etc. If this function returns a response, that will be returned by the controller. If it does not, a generic success message will be returned if the submission was made via xhr, otherwise a redirect back will be returned.

Use the rules and messages functions provide validation, which will be merged with the default 'email => ['required', 'email'] validation.

Once you have made a handler, you will need to register it. To do so, add a new keyed item to the config at enso.newsletter.newsletters. A basic contact form handler definition might look like:

'newsletters' => [
    // ...

    'contact' => [
        'handler' => `\App\Enso\Newsletter\ContactFormHandler`,
    ],

    // ...
],

If you need to keep additional data in order to handle the form (such as a Mailchimp list_id for signing up a user), this array is the place to store that information.

Creating a form

Form submissions should be made to the newsletters.store endpoint, and are expected to made as POST requests. This endpoint should respond to either HTTP or XHR requests equally well.

For a bare minimum request, you are expected to provide two fields:

  • A hidden type field which references one of the newsletter types you have set up by key, such as contact in the earlier example.
  • An email field, which should be a valid email.

By default, the request type (HTTP vs XHR) will determine the response type.

If an XHR request is made, it will be responded to with a Illuminate\Http\JsonResponse which will be either:

  • A 400 response, with a message property descibing the issue.
  • Standard Laravel validation errors
  • A 200 response will a value of ok.

If an HTTP request is made, a redirect back will occur. Responses are either:

  • With the input (for re-filling filled fields) and a message variable describing the issue.
  • With the input (for re-filling filled fields) and standard Laravel validation output.
  • With nothing extra.

Customization

Bindings

Both the model an controller are bound to interfaces, enabling you to override or replace them. They are bound to:

Yadda\Enso\Newsletter\Contracts\NewsletterControllerContract;
Yadda\Enso\Newsletter\Contracts\NewsletterModelContract;

Routes

You can customize routes by passing arguments to the route generator.

EnsoNewsletter::routes($path, $name);