What is the ContactEtc Contact Form For Laravel Package?

It is a customisable contact form that will email you (you can define who it emails). You can change the fields and other options. All views/routes/controllers are built in.

If you think this might be useful for you in the future, please go to github and star it or watch it :)

View on Github
View on Github View on Packagist

#Go straight to the 5 min install guide..

Minimum Requirements

Laravel 5.7.

There are a few requirements in the composer.json file, but it should work with all Laravel 5.7 or higher installations.

What it is suitable for / what it is not suitable for

If you want one or more contact forms on your Laravel site, then install this and you can have it up and running within a few minutes!

Screenshots of BlogEtc Laravel Blog Package

The contact form

Laravel contact form
Laravel contact form

By default it will show these fields, however you can easily add an unlimited amount of fields. It supports normal input, textarea, select and checkboxes. Oh, and anti captcha (with reCaptcha). It is easy to add your own though.

3 Minute Install Guide

  1. Install via Composer (Find details on Composer here).
    Run this command:
  2. The package will install, and it uses the Laravel Auto Discovery to automatically register the service provider so you don't need to add the service provider to app.php..
  3. You must run the following command to copy the config/contactetc.php over to your app:
  4. Next you need to create the config file for each of your contact forms (note: this is not the same one as in /config/contactetc.php. Every contact form that must have its own config file, which says what fields it should have, who it should email, etc).

    You can have multiple contact forms (see section below for details, the rest of this install guide assumes that you will have only one contact form).

    Run the following command (you can change the last param from MainContactForm to whatever you want to call it, but if you have just one form I recommend just copy/pasting the command exactly as it is as it will be a bit quicker to setup) and it will create a dummy contact form config file in /app/ContactEtcForms
  5. You should now have a file in /app/ContactEtcForms/MainContactForm.php. We will come back to this in a sec.
  6. You must edit the main config file config/contactetc.php and make sure that you include the newly created file in the 'contact_forms' array. If you copy/pasted exactly (i.e. the file is ContactEtcForms/MainContactForm.php) then you probably won't have to edit the config file, as the default should work!


    See this screenshot how it should look
  7. Ok, now if you go back to the file you just created (ContactEtcForms/MainContactForm.php or whatever you called it) you should see a whole bunch of options. It should be easy to figure out - work through the file. You can find more details in the section below ("The field types") .
  8. If you uncomment the recaptcha parts, you must scroll down in this guide to the info about recaptcha, as you must set up a couple of bits.
  9. All done! Visit http://yoursite.com/contact-us (or whatever you defined the slug as in the config file). If you want to add more than one contact form, please scroll down. (View [layouts.app] not found error? scroll down to the known issues for a fix)

The field types

Inside your files in app/ContactEtcForms/, the ->addFields(...) part contains an array of fields. These can be found in /vendor/webdevetc/contactetc/src/FieldTypes. You can also make your own custom fields - extend BaseFieldType. You will probably want to make a custom blade file too.

Here are the different included types.

  • Checkbox - a checkbox. Tip: use this with ->markAsRequiredField()
  • Email - an email field.
  • Text - normal text input
  • Textarea - textarea
  • Select - select dropdown. Use ->setOptions($array_of_options) to set the dropdown options. The first one will be the default.
  • RecaptchaV2Invisible - google captcha.

You should add items to that array like this:

  1. /*... in the middle of your file in /app/ContactEtcForms/YourFile.php ... */
  2. ->addFields(
  3.  
  4. [
  5.     // first field:
  6.     Text::newNamed("your_name")// field name (<input name=$field_name>)
  7.     ->setLabelName("Your name") // the <label>$label_name</label> value
  8.         ->markAsRequiredField() // required in the Request validation + <input required >
  9.         ->setAsReplyToName(), // if you want to email 'reply to name' to this value
  10.  
  11.     // second field:
  12.     Email::newNamed("email") // the field name <input name='email'>
  13.         ->setLabelName("Your email address") // the <label>Your email address</label>
  14.         ->setPlaceholderValue("[email protected]") // the default placeholder value (<input placeholder=$placeholder>)
  15.         ->markAsRequiredField() // makes it required, in the Request validation and also in the HTML with <input required>
  16.         ->max(200)// max length (via request validation rule)
  17.         ->min(4)// min length (via request validation rule)
  18.         ->setAsReplyToAddress(), // mark the email's "reply to" as this value
  19.  
  20.  
  21.     Textarea::newNamed("message")
  22.             ->setLabelName("Your message")
  23.             ->setDescription("Please give as much detail as possible") // an optional bit of text that is displayed below the field
  24.             ->markAsRequiredField()
  25.             ->max(5000),
  26.  
  27.     ]
  28.  
  29.  
  30.     )

Sorry that it is a bit messy when displaying it here. It is probably easier to just read the file in your IDE.

Available methods on the fields:

  • ::newNamed($field_name) - used to instantiate the field type. Use this, then chain any of the following methods
  • ->setLabelName("Your name") - This is used for a human-readable label -<label>Your Name</label>
  • ->setPlaceholderValue("Some name") - This is used for a placeholder attribute in the input <input placeholder='Some Name'>
  • ->setDescription("Enter your full name here") - a place to add a description under the field
  • ->markAsRequiredField() - makes the field required. It adds a required attribute to the field's <input required> (or <textarea required></textarea>, and also adds a 'required' validation rule for Laravel's request validation rules.
  • ->markAsOptional() - the opposite of the above one! It isn't needed, as all fields are optional unless marked required.
  • ->setAsFromAddress() - if you run this on a field, and it has a submitted value then it will set the "from email" as this value. Only available on Email field types.
  • ->setAsFromName() - if you run this on a field, and it has a submitted value then it will set the "from name" as this value. It will only work if the email also has a "from email address" set (from above method)
  • ->setAsReplyToAddress() (only available on Email field types) will set the email's reply to address to this field's value (if there was any submitted value)
  • ->setAsReplyToName() similar to setAsFromName(), but for the reply to.
  • ->setOptions($array_of_options) - (only available on Select) - provide an array of options for the select dropdown
  • ->min($int) and ->max($int) - if set, it will pass these values as validation rules for min/max. It only checks the values aren't under the min/over the max when submitted - there are no HTML/js checks (todo?)

Config Options

(remember to do php artisan vendor:publish --tag=contactetc to get the contactetc.php file in your config directory. If you haven't done this, scroll up to the install instructions!)

There are a few options here, all with sane defaults.

The important one is the 'contact_forms' part. This should be an array of file paths of each of your contact form config files (use something like app_path('ContactEtcForms/your-file.php'))

To create the config files please run php artisan make:contactetcform MainContactForm and edit the file (comments should make it obvious what to do) and then edit the config/contactetc.php file to include that file path in the 'contact_forms' array.

How to have multiple contact forms

  • php artisan make:contactetcform AnotherContactForm
  • In app/ContactEtcForms/AnotherContactForm.php (or whatever file it is), edit the form. Make sure that the value you pass in return ContactForm::newContactForm("THISVALUE") is unique! And remember it!
  • In config/contactetc.php, in the 'contact_forms' array, add the file path that you just created. Use app_path() to make the full file path.
  • In your web.php file, add the following (edit as required):
  • In the snippet from above (put that in your routes/web.php file):
    • change the prefix from alt-contact-us-slug to whatever you want. As it is, you could see the form by going to http://yoursite.com/alt-contact-us-slug
    • change $contact_field_group_name to the same value as what is in your new contact form (i.e. the value in ContactForm::newContactForm("THISVALUE")
    • Link to it with route("contactetc.form.$contact_field_group_name") ($contact_field_group_name in the example above is set to 'someotherform' so you would use route("contactetc.form.someotherform")
  • You can have as many forms as you want. Just repeat the process.

Guide to customising the blog views/template

You will probably want to edit the view files. When you run the vendor:publish command (see install guide above), it will copy the default view files over to resources/views/vendor/contactetc. Edit them there :)

Linking to the contact form

You can easily link to the various types of pages:

  • route('contactetc.form.main_contact_form') is the default route (which should, if you don't edit the config, link to http://yoursite.com/contact-us. You can edit the slug in the config file

Events

You can find all the events that are fired by looking in the /src/Events directory.

Add these (and an Event Listener) to your EventServiceProvider.php file to make use of these events when they fire.

Testing

Tests are included. Please see the tests directory for details. They must be run in a Laravel installation (cd vendor/webdevetc/contactetc/; ../../bin/phpunit;)

Captcha / recaptcha

You can include a recaptcha field. It uses the buzz/laravel-google-captcha package. Please follow the install instructions from here.

Reporting Bugs / Security Issues

Please just send me an email via the contact form, I'll get back to you ASAP.

Known issues/notes

View [layouts.app] not found. - You need a /resources/views/layouts/app.blade.php file that has @yield('content') in it. You can run php artisan make:auth to automatically generate this file (but also, it will generate other files associated with authentication)

Expected response code 250 but got code "530", with message "530 5.7.1 Authentication required " - check your Laravel's config/mail.php settings. This isn't a bug from my script :) It is a problem with your mail driver's settings.