PHPackages                             anttiviljami/wp-libre-form - 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. anttiviljami/wp-libre-form

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

anttiviljami/wp-libre-form
==========================

Easy native HTML5 forms for WordPress

1.5.0.3(6y ago)664.5k↓27.5%27[4 issues](https://github.com/libreform/wp-libre-form/issues)[6 PRs](https://github.com/libreform/wp-libre-form/pulls)GPLv3PHPPHP >=5.3.0

Since Feb 21Pushed 5y ago7 watchersCompare

[ Source](https://github.com/libreform/wp-libre-form)[ Packagist](https://packagist.org/packages/anttiviljami/wp-libre-form)[ RSS](/packages/anttiviljami-wp-libre-form/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (8)Dependencies (2)Versions (28)Used By (0)

WP Libre Form
=============

[](#wp-libre-form)

[![Build Status](https://camo.githubusercontent.com/1f5c8a170dc9628aad7fd36f4bad67c2c49bfc371bd498574ec15320954cbadb/68747470733a2f2f7472617669732d63692e6f72672f6c69627265666f726d2f77702d6c696272652d666f726d2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/libreform/wp-libre-form) [![Latest Stable Version](https://camo.githubusercontent.com/9a79f194ef65c77677ce10f3ea93ed0011bbe546073cb948803d63435b5a1236/68747470733a2f2f706f7365722e707567782e6f72672f616e74746976696c6a616d692f77702d6c696272652d666f726d2f762f737461626c65)](https://packagist.org/packages/anttiviljami/wp-libre-form) [![Total Downloads](https://camo.githubusercontent.com/ed10018d70d62b0f47be72576614f62a8ee341afd56e7b911dfbc7063f52454a/68747470733a2f2f706f7365722e707567782e6f72672f616e74746976696c6a616d692f77702d6c696272652d666f726d2f646f776e6c6f616473)](https://packagist.org/packages/anttiviljami/wp-libre-form) [![Latest Unstable Version](https://camo.githubusercontent.com/ff734ecf1267b5fc560acac8050b9af71e65837075aed794d8a6a58177011164/68747470733a2f2f706f7365722e707567782e6f72672f616e74746976696c6a616d692f77702d6c696272652d666f726d2f762f756e737461626c65)](https://packagist.org/packages/anttiviljami/wp-libre-form) [![License](https://camo.githubusercontent.com/299edbf72b27bb0f529e3cf10b13fa09ac05566d5e13d665e87bcbc58b98d0b6/68747470733a2f2f706f7365722e707567782e6f72672f616e74746976696c6a616d692f77702d6c696272652d666f726d2f6c6963656e7365)](https://packagist.org/packages/anttiviljami/wp-libre-form)

Use standard HTML5 markup to create fully functional forms for WordPress

Features
--------

[](#features)

- Uses only HTML5 syntax to build forms. No GUIs, shortcodes, **no bullshit**
- Works with any valid HTML form. Just copy any form from any website and it will work. **It's magic!**
- Submissions are saved as custom post type posts. Form values are saved as custom fields.
- Validates required fields tagged with the native HTML5 `required` attribute.
- **It's hackable.** Add your own functionality with hooks and APIs.
- Email notifications of received form submissions
- Full file upload support to Media Library with input type=file
- Multilingual support with Polylang
- Predefined static HTML forms via filter hooks
- Dynamic values, like %USER\_EMAIL% for pre-populating form data

Why?
----

[](#why)

Modern HTML markup is already a great way to build forms. With Libre Form, there's no need to learn clunky form builders that are hard to customise.

Just use standard HTML inputs to build, or copy a form to your WordPress site that will just magically work. No need to touch PHP code if you don't want to.

Required field validation, email notifications, file uploads to WP gallery and lots more are included by default in the core of the plugin, but you can also add your own functionality with [hooks and APIs](#filter--action-api) provided by Libre Form.

Try it
------

[](#try-it)

[TryoutWP](https://gettryout.com/) has provided us with a live demo, [which you can find here](http://gettryout.com/new/?template=libreform&provider=demo&redirect=wp-admin%2Fpost.php%3Fpost%3D4%26action%3Dedit). It reflects the current release, not the master branch.

Screenshots
-----------

[](#screenshots)

### Editing a Form

[](#editing-a-form)

[![Form edit](/assets/screenshot-1.png)](/assets/screenshot-1.png)

### Form displayed in the default Twentysixteen theme

[](#form-displayed-in-the-default-twentysixteen-theme)

[![Submissions](/assets/screenshot-2.png)](/assets/screenshot-2.png)

### Submissions view

[](#submissions-view)

[![Submissions](/assets/screenshot-3.png)](/assets/screenshot-3.png)

### Single submission view

[](#single-submission-view)

[![Submissions](/assets/screenshot-4.png)](/assets/screenshot-4.png)

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

[](#installation)

### The Composer Way (preferred)

[](#the-composer-way-preferred)

Install the plugin via [Composer](https://getcomposer.org/)

```
composer require anttiviljami/wp-libre-form

```

Activate the plugin

```
wp plugin activate wp-libre-form

```

### The Old Fashioned Way

[](#the-old-fashioned-way)

This plugin is available on the [official WordPress.org plugin directory](https://wordpress.org/plugins/wp-libre-form/).

You can also install the plugin by directly uploading the zip file as instructed below:

1. [Download the plugin](https://github.com/anttiviljami/wp-libre-form/archive/master.zip)
2. Upload to the plugin to /wp-content/plugins/ via the WordPress plugin uploader or your preferred method
3. Activate the plugin

Filter / Action API
-------------------

[](#filter--action-api)

### Filter: wplf\_validate\_submission

[](#filter-wplf_validate_submission)

Used to add validation to your forms.

#### Form specific hooks

[](#form-specific-hooks)

This filter supports form specific hooks:

- `wplf_{form_id}_validate_submission`
- `wplf_{form_slug}_validate_submission`

These filters are only applied for the target form by ID or slug.

#### Example: Google ReCaptcha integration

[](#example-google-recaptcha-integration)

```
/**
 * ReCaptcha for WP Libre Form
 */
add_filter( 'wplf_validate_submission', 'wplf_recaptcha' );
function wplf_recaptcha( $return ) {
  // skip this validation if submission has already failed
  if ( ! $return->ok ) {
    return $return;
  }

  $secret = RECAPTCHA_KEY; // substitute with your own secret recaptcha key string
  $options = [
    'http' => [
      'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
      'method'  => 'POST',
      'content' => http_build_query([
        'secret' => $secret,
        'response' => $_POST['g-recaptcha-response'],
      ])
    ],
  ];

  $context  = stream_context_create( $options );
  $result = file_get_contents( 'https://www.google.com/recaptcha/api/siteverify', false, $context );

  $captcha_obj = json_decode( $result );

  if ( false === $captcha_obj->success ) {
    $return->ok = 0;
    $return->error = __("Please prove you're not a robot before submitting.");
  }

  return $return;
}
```

### Action: wplf\_post\_validate\_submission

[](#action-wplf_post_validate_submission)

Triggers after the form validation is done.

#### Form specific hooks

[](#form-specific-hooks-1)

This action supports form specific hooks:

- `wplf_{form_id}_post_validate_submission`
- `wplf_{form_slug}_post_validate_submission`

These actions are only run for the target form by ID or slug.

#### Example: Send a thank you email to the email in the submission

[](#example-send-a-thank-you-email-to-the-email-in-the-submission)

```
add_action( 'wplf_post_validate_submission', 'my_email_thankyou' );
function my_email_thankyou( $return ) {
  // recipient details from submission
  $name = sanitize_text_field( $_POST['name'] );
  $email = sanitize_email( $_POST['email'] );

  // email subject
  $subject = __( 'Thank You For Submitting A Form' );

  // text body of email
  $body = wp_sprintf( __('Thanks, %s for clicking Submit on this glorious HTML5 Form!'), $name );

  // send the email
  wp_mail( $email, $subject, $body );
}
```

### Filter: wplf\_disable\_validate\_additional\_fields

[](#filter-wplf_disable_validate_additional_fields)

Dynamically generated fields are disabled by default. If you want to allow fields that are not set in the form to be submitted you can use this filter.

#### Form specific hooks

[](#form-specific-hooks-2)

This filter supports form specific hooks:

- `wplf_{form_id}_disable_validate_additional_fields`
- `wplf_{form_slug}_disable_validate_additional_fields`

These filters are only applied for the target form by ID or slug.

Disabling additonal fields validation for all forms:

```
add_filter( 'wplf_disable_validate_additional_fields' , '__return_true' );
```

### Filter: wplf\_allowed\_additional\_form\_fields

[](#filter-wplf_allowed_additional_form_fields)

You can provide your own set of allowed field names, instead of disabling additional field validation entirely.

#### Form specific hooks

[](#form-specific-hooks-3)

This filter supports form specific hooks:

- `wplf_{form_id}_allowed_additional_form_fields`
- `wplf_{form_slug}_allowed_additional_form_fields`

These filters are only applied for the target form by ID or slug.

Disabling additonal fields validation for all forms:

```
add_filter( 'wplf_allowed_additional_form_fields' , ['dynamic-field-name'] );
```

### Filter: wplf\_dynamic\_values

[](#filter-wplf_dynamic_values)

Add or customize dynamic values available in forms.

#### Example: new value

[](#example-new-value)

```
add_filter('wplf_dynamic_values', function($values) {
  $values['SOMETHING'] = [
    'callback' => function() { return 'something'; },
    'labels' => [
      'name' => 'Something',
      'description' => 'Something really useful.'
    ],
  ];

  return $values;
});

//
```

### Filter: wplf\_uploaded\_file\_name

[](#filter-wplf_uploaded_file_name)

If you choose to not add uploaded files to the media library, you can change the file upload name.

```
add_filter('wplf_uploaded_file_name', function($name, $file, $id) {
  return "my_".$name;
}, 10, 3);
```

### Filter: wplf\_uploaded\_file\_path

[](#filter-wplf_uploaded_file_path)

If you choose to not add uploaded files to the media library, you can change the file upload path.

```
add_filter('wplf_uploaded_file_path', function($name, $file, $id) {
  return $name.".userfile";
}, 10, 3);
```

Plugins
-------

[](#plugins)

1.5 exposes a new function, `wplf()`. It simply returns the class instance of WP Libre Form.

It allows you to register your plugin as a WP Libre Form plugin, which in turn allows you to expose an API and a settings page for your plugin, should you want to.

```
$wplf = wplf();
$plugin = new YourPlugin();

$wplf->plugins->register([
  "name" => "YourPlugin", // The name you wish to show on the WPLF plugin page. Willl also be used to access public methods in your plugin
  "description" => "What your plugin does in a sentence or two",
  "link" => "https://toyourplugin.com", // Plugin URL. Can be wordpress.org or pretty much any URL where you can download the plugin
  "version" => YOUR_PLUGIN_VERSION, // Define a constant containing your plugin version
  "instance" => $plugin, // Your plugin, instantiated. Users can access your public methods
  "settings_page" => [$plugin, "render_settings_page"], // Function that renders your settings page, or a string that contains the link to it. Leave empty to disable.
]);
```

If you use spaces in the name, you can access the plugin instance like this:

`wplf()->plugins->{"Your plugin"}->somePublicMethod()`

Javascript API
--------------

[](#javascript-api)

### Client side callbacks

[](#client-side-callbacks)

WP Libre Form supports client side callbacks after form submission using window.wplf object. Example usage:

```
window.wplf.successCallbacks.push(res => alert('Form submission success: ' + res.form_id));
window.wplf.errorCallbacks.push(() => alert('Form submission failed!'));

```

These callbacks are executed in the order they appear.

To avoid running your JavaScript too early, add `wplf-form-js` to your enqueue dependencies:

```
wp_enqueue_script( "themejs", "/path/to/theme.js", array( "wplf-form-js" ), ... );
```

Otherwise you might run into errors like "Cannot read property 'push' of undefined".

REST API driven sites
---------------------

[](#rest-api-driven-sites)

You can get forms out of the REST API. Just use `/wp/v2/wplf-form` to retrieve forms. You can get a singular form by using filters:

`/wp/v2/wplf-form?slug=form-slug`

However, if you're sending forms from a different domain than WP site URL, you'll run across a CORS issue submitting the form, which you can get around with this:

```
add_action('wplf_pre_validate_submission', function() {
  $origin = $_SERVER['HTTP_ORIGIN'];
  header("Access-Control-Allow-Origin: $origin");
  header("Access-Control-Allow-Credentials: true");
});
```

Do note that the above code snippet opens your form submissions to the world.

You can also use the "official" JS bundle if you want to.

```
window.ajax_object = {
  ajax_url: `${WP.url}/wp-admin/admin-ajax.php`,
  ajax_credentials: 'include', // different origin
  wplf_assets_dir: `${WP.url}/wp-content/plugins/wp-libre-form/assets`,
}

await new Promise((resolve, reject) => {
  const script = document.createElement('script')
  const timeout = setTimeout(reject, 30000)
  script.src = `${WP.url}/wp-content/plugins/wp-libre-form/assets/scripts/wplf-form.js`
  script.onload = (e) => {
    clearInterval(timeout)
    resolve()
  }

  document.body.appendChild(script)
})
```

Multilingual
------------

[](#multilingual)

You can create multilingual forms using Polylang. WPLF will register and automatically fetch the translation when you use special template tags.

Example:

```

```

You can also disable this feature, and create your own middleware for WPML, if you'd like.

```
add_filter( 'wplf_load_polylang' , __return_false );
```

Adding extra classes to the form element
----------------------------------------

[](#adding-extra-classes-to-the-form-element)

You can use the xclass attribute inside the shortcode to add your own extra classes for CSS.

```
[libre-form id="1" xclass="extra"]

```

Adding extra attributes to the form element
-------------------------------------------

[](#adding-extra-attributes-to-the-form-element)

You can add any custom attributes to the form element easily by adding them to the shortcode

```
[libre-form id="1" data-custom-attr="contactme"]

```

The attribute will render as is on the `` element

```

```

Importing forms from a predefined HTML template
-----------------------------------------------

[](#importing-forms-from-a-predefined-html-template)

Sometimes a project might require static forms which are not supposed to be editable in the admin panel.

This plugin allows you to define HTML forms in your project source code and import them into the form admin for specific forms.

### Creating a static HTML template

[](#creating-a-static-html-template)

The simplest way is to create a HTML5 file and read its contents. Other options include using Twig to render HTML templates.

Remember: WPLF will insert `form` tags on its own, meaning you only have to create the markup which sits directly inside the `form` tags.

### Importing a template into WPLF

[](#importing-a-template-into-wplf)

Once you're done creating a form template, you need to inform WPLF about it. You can use the `wplf_import_html_template`filter hook for this:

```