How to Create Custom Forms in WordPress with PHP

Creating custom forms in WordPress with PHP gives you full control over form functionality, performance, and security. Unlike plugins, custom forms are lightweight and tailored to your needs, offering faster load times and advanced flexibility. Here’s what you’ll learn:

Why Use Custom Forms? Perfect for lead generation, job applications, event registrations, and more.
Advantages of PHP: Secure server-side validation, database integration, and custom logic.
Step-by-Step Guide:
- Build the form structure with HTML.
- Process and validate form data securely using PHP.
- Save submissions to the WordPress database.
- Add spam protection and user-friendly features like AJAX.

Quick Overview of Key Steps

Step	What You’ll Do
Form HTML	Create a secure form structure with `wp_nonce_field` and `admin-post.php`.
Data Processing	Sanitize inputs, validate data, and handle submissions with WordPress hooks.
Database Storage	Save submissions in a custom database table using `$wpdb`.
Spam Protection	Add honeypot fields, rate limits, and reCAPTCHA to prevent spam.
AJAX Submission	Enable dynamic form submission without page reloads for a smoother experience.

This guide will walk you through each step, ensuring your custom WordPress forms are secure, efficient, and tailored to your specific needs.

Custom Registration Form in WordPress without Plugins

Before You Start

Creating custom forms with PHP for WordPress requires a specific set of tools and knowledge. Here’s what you’ll need to get started.

Tools and Skills Needed

To build custom WordPress forms using PHP, make sure you have the following:

Requirement	Description	Purpose
PHP Knowledge	Understanding of variables, functions, and form handling	To process form submissions, validate inputs, handle `$_POST`/`$_GET`, and work with databases.
WordPress Skills	Familiarity with hooks, actions, and the database structure	To integrate forms into WordPress and add custom functionality.
Code Editor	Tools like VS Code, Sublime Text, or PHPStorm	To write and debug PHP code effectively.
Development Tools	Browser dev tools and PHP debugging extensions	To test and troubleshoot your form’s functionality.

Once you’re confident you have these skills and tools, it’s time to set up your local WordPress environment.

WordPress Local Setup Guide

To test your forms effectively, you’ll need a local WordPress environment. Here’s how to set it up:

Install Local Development Software
Download and install LocalWP. This tool provides everything you need, including an Apache/Nginx server, PHP 7.4 or later, MySQL, SSL support, and one-click WordPress installation.
Configure Your Environment
- Add the following lines to your wp-config.php file for debugging:
  define('WP_DEBUG', true);
  define('WP_DEBUG_LOG', true);
- Install the Query Monitor plugin for detailed debugging.
- Create a testing database for your development work.
Set Up Security Measures
- Adjust file permissions to 755 for directories and 644 for files.
- Implement a backup system for your testing database.
- Enable error logging to track issues during development.

For an easier setup, WP Winners suggests using their Local Development Toolkit. It includes pre-configured security settings and debugging tools tailored for custom form development.

With your local environment ready, you can dive into building your custom form.

Step 1: Create the Form HTML

Build Form Elements

Start with a simple contact form layout. Here’s the basic structure, complete with HTML5 validation:

<form method="post" action="<?php echo esc_url(admin_url('admin-post.php')); ?>" id="custom-contact-form">
    <?php wp_nonce_field('custom_form_submit', 'custom_form_nonce'); ?>
    <input type="hidden" name="action" value="custom_form_submission">

    <div class="form-group">
        <label for="name">Full Name *</label>
        <input type="text" id="name" name="name" required>
    </div>

    <div class="form-group">
        <label for="email">Email Address *</label>
        <input type="email" id="email" name="email" required>
    </div>

    <div class="form-group">
        <label for="message">Message *</label>
        <textarea id="message" name="message" rows="5" required></textarea>
    </div>

    <button type="submit">Send Message</button>
</form>

This form includes essential security measures:

wp_nonce_field(): Adds a verification token for WordPress security.
esc_url(): Sanitizes the action URL to prevent attacks.
admin-post.php: Ensures secure form data handling.

Add Form to WordPress

You can embed the form into your WordPress setup using these approaches:

Template Integration
Add the form directly to your theme’s template file:

<?php
function display_custom_form() {
    ob_start();
    include_once('path/to/form-template.php');
    return ob_get_clean();
}
add_shortcode('custom_contact', 'display_custom_form');

Shortcode Implementation
Create a shortcode for easy embedding:

function custom_form_shortcode() {
    ob_start();
    ?>
    <!-- Form HTML goes here -->
    <?php
    return ob_get_clean();
}
add_shortcode('custom_contact_form', 'custom_form_shortcode');

Dynamic Field Population
Use PHP to populate fields dynamically, such as a department dropdown:

<select name="department">
    <?php
    $departments = get_terms([
        'taxonomy' => 'department',
        'hide_empty' => false,
    ]);

    foreach($departments as $dept) {
        echo sprintf(
            '<option value="%s">%s</option>',
            esc_attr($dept->slug),
            esc_html($dept->name)
        );
    }
    ?>
</select>

Enhancing Form Functionality

You can add these attributes to improve the form’s behavior:

Attribute	Value	Purpose
`enctype`	`multipart/form-data`	Enables file uploads
`autocomplete`	`off`	Disables browser autofill
`novalidate`	–	Turns off HTML5 validation for custom rules

Once the form is integrated, the next step is handling the submitted data using PHP. Continue to the next section for details on processing the form data.

sbb-itb-77ae9a4

Step 2: Process Form Data with PHP

Get and Clean Form Data

To handle form submissions securely in WordPress, use the following approach:

add_action('admin_post_custom_form_submission', 'handle_form_submission');
add_action('admin_post_nopriv_custom_form_submission', 'handle_form_submission');

function handle_form_submission() {
    // Verify nonce for security
    if (!isset($_POST['custom_form_nonce']) || 
        !wp_verify_nonce($_POST['custom_form_nonce'], 'custom_form_submit')) {
        wp_die('Security check failed');
    }

    // Sanitize and collect form data
    $form_data = array(
        'name'    => sanitize_text_field($_POST['name']),
        'email'   => sanitize_email($_POST['email']),
        'message' => wp_kses_post($_POST['message'])
    );

    // Check if all required fields are filled
    if (empty($form_data['name']) || empty($form_data['email']) || empty($form_data['message'])) {
        wp_redirect(add_query_arg('submission', 'incomplete', wp_get_referer()));
        exit;
    }
}

Here’s a quick guide to essential sanitization functions for different input types:

Input Type	Sanitization Function	Use Case
Plain Text	`sanitize_text_field()`	Names, subjects, single-line inputs
Email	`sanitize_email()`	Email addresses
URL	`esc_url_raw()`	Website URLs, links
HTML Content	`wp_kses_post()`	Rich text areas, formatted content
Numbers	`absint()`	Positive integers
Floats	`floatval()`	Decimal numbers

After sanitizing the data, you can move on to storing the submissions in the database.

Save Form Submissions

To save the sanitized data into the WordPress database, use the following implementation:

function save_form_submission($form_data) {
    global $wpdb;
    $table_name = $wpdb->prefix . 'form_submissions';

    $result = $wpdb->insert(
        $table_name,
        array(
            'name'        => $form_data['name'],
            'email'       => $form_data['email'],
            'message'     => $form_data['message'],
            'created_at'  => current_time('mysql')
        ),
        array('%s', '%s', '%s', '%s')
    );

    if ($result === false) {
        error_log('Form submission failed: ' . $wpdb->last_error);
        return false;
    }

    return $wpdb->insert_id;
}

If you don’t already have a table for storing submissions, create one using this function:

function create_submissions_table() {
    global $wpdb;
    $charset_collate = $wpdb->get_charset_collate();
    $table_name = $wpdb->prefix . 'form_submissions';

    $sql = "CREATE TABLE IF NOT EXISTS $table_name (
        id mediumint(9) NOT NULL AUTO_INCREMENT,
        name varchar(100) NOT NULL,
        email varchar(100) NOT NULL,
        message text NOT NULL,
        created_at datetime DEFAULT CURRENT_TIMESTAMP,
        PRIMARY KEY  (id)
    ) $charset_collate;";

    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
    dbDelta($sql);
}

register_activation_hook(__FILE__, 'create_submissions_table');

User Feedback

You can display feedback messages to users based on the submission status:

function display_submission_message($type) {
    $messages = array(
        'success' => 'Thank you! Your message has been received.',
        'error'   => 'There was an error processing your submission.',
        'incomplete' => 'Please fill in all required fields.'
    );

    if (isset($messages[$type])) {
        echo '<div class="submission-message ' . esc_attr($type) . '">';
        echo esc_html($messages[$type]);
        echo '</div>';
    }
}

This approach ensures errors are logged, and users are notified about the status of their submissions.

Step 3: Add Form Validation

PHP Validation Methods

Use the following PHP function to validate your form data on the server side:

function validate_form_data($form_data) {
    $errors = array();

    // Validate name (2-50 characters, letters and spaces only)
    if (!preg_match('/^[a-zA-Z\s]{2,50}$/', $form_data['name'])) {
        $errors['name'] = 'Name must be 2-50 characters long and contain only letters.';
    }

    // Validate email using WordPress's built-in function
    if (!is_email($form_data['email'])) {
        $errors['email'] = 'Please enter a valid email address.';
    }

    // Validate message length (minimum 10 characters)
    if (strlen(trim($form_data['message'])) < 10) {
        $errors['message'] = 'Message must be at least 10 characters long.';
    }

    return $errors;
}

In your form processing function, handle these validation errors as follows:

function handle_form_submission() {
    // Perform security checks as usual

    $errors = validate_form_data($form_data);

    if (!empty($errors)) {
        set_transient('form_errors_' . wp_get_current_user_id(), $errors, 30);
        wp_redirect(add_query_arg('submission', 'error', wp_get_referer()));
        exit;
    }

    // Proceed with form processing if validation passes
}

Pair this with client-side validation for a better user experience.

JavaScript Form Checks

Enhance the user experience with real-time validation using JavaScript:

document.addEventListener('DOMContentLoaded', function() {
    const form = document.getElementById('custom-form');

    const validateField = {
        name: (value) => /^[a-zA-Z\s]{2,50}$/.test(value),
        email: (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
        message: (value) => value.trim().length >= 10
    };

    form.addEventListener('input', function(e) {
        const field = e.target;
        const fieldName = field.name;

        if (validateField[fieldName]) {
            const isValid = validateField[fieldName](field.value);
            field.classList.toggle('invalid', !isValid);

            // Display or hide error messages
            const errorElement = field.nextElementSibling;
            if (errorElement && errorElement.classList.contains('error-message')) {
                errorElement.style.display = isValid ? 'none' : 'block';
            }
        }
    });
});

Apply this CSS to provide clear visual feedback to users:

.form-field.invalid {
    border-color: #dc3545;
}

.error-message {
    color: #dc3545;
    font-size: 0.875rem;
    margin-top: 0.25rem;
}

Validation Comparison

The table below summarizes the purpose and timing of different validation types:

Validation Type	Timing	Purpose	Implementation
Client-side JS	Real-time	Instant user feedback	Input event listeners
Server-side PHP	On submission	Ensure data integrity	WordPress hooks
AJAX Validation	On field blur	Better user experience	wp_ajax actions

Additional Security Measures

To further protect your form, consider these steps:

// Add a honeypot field
echo '<input type="text" name="website" style="display:none">';

// Limit submission rate
if (get_transient('form_submission_' . get_client_ip())) {
    wp_die('Please wait 60 seconds before submitting again.');
}

Extra Form Features

Implement AJAX Submission

To improve the user experience, you can set up AJAX submission for your custom form. Start by registering an AJAX endpoint in your WordPress setup:

add_action('wp_ajax_submit_custom_form', 'handle_ajax_submission');
add_action('wp_ajax_nopriv_submit_custom_form', 'handle_ajax_submission');

function handle_ajax_submission() {
    check_ajax_referer('custom_form_nonce', 'nonce');

    $response = array(
        'success' => false,
        'message' => ''
    );

    $form_data = array(
        'name'    => sanitize_text_field($_POST['name']),
        'email'   => sanitize_email($_POST['email']),
        'message' => sanitize_textarea_field($_POST['message'])
    );

    $errors = validate_form_data($form_data);

    if (empty($errors)) {
        $post_id = wp_insert_post(array(
            'post_type'   => 'form_submission',
            'post_title'  => $form_data['name'],
            'post_status' => 'private'
        ));

        if ($post_id) {
            update_post_meta($post_id, '_form_email', $form_data['email']);
            update_post_meta($post_id, '_form_message', $form_data['message']);
            $response['success'] = true;
            $response['message'] = 'Form submitted successfully!';
        }
    } else {
        $response['message'] = $errors;
    }

    wp_send_json($response);
}

Next, set up the client-side script to handle the AJAX submission:

jQuery(document).ready(function($) {
    $('#custom-form').on('submit', function(e) {
        e.preventDefault();
        const formData = new FormData(this);
        formData.append('action', 'submit_custom_form');
        formData.append('nonce', customForm.nonce);

        $.ajax({
            url: customForm.ajaxUrl,
            type: 'POST',
            data: formData,
            processData: false,
            contentType: false,
            success: function(response) {
                if (response.success) {
                    $('#form-message').removeClass('error').addClass('success').html(response.message);
                    $('#custom-form').trigger('reset');
                } else {
                    $('#form-message').removeClass('success').addClass('error').html(response.message);
                }
            }
        });
    });
});

This approach ensures a smooth form submission process without reloading the page, improving usability.

Protect Against Spam

To keep your form secure, it’s essential to implement measures that prevent spam submissions. Add hidden fields and reCAPTCHA to your form for extra protection:

function add_form_protection() {
    $timestamp = time();
    echo '<input type="hidden" name="timestamp" value="' . $timestamp . '">';
    echo '<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>';
}

Then, validate the spam protection measures during form submission:

function verify_form_submission($form_data) {
    $timestamp = intval($form_data['timestamp']);
    $time_difference = time() - $timestamp;
    if ($time_difference < 3 || $time_difference > 3600) {
        wp_die('Invalid submission timing');
    }

    $recaptcha_response = wp_remote_post('https://www.google.com/recaptcha/api/siteverify', array(
        'body' => array(
            'secret'   => 'YOUR_SECRET_KEY',
            'response' => $form_data['g-recaptcha-response']
        )
    ));

    if (is_wp_error($recaptcha_response)) {
        wp_die('reCAPTCHA verification failed');
    }
}

These steps help block automated bots while maintaining a seamless experience for legitimate users. For more advanced tips and techniques, check out WP Winners at https://wpwinners.com.

Conclusion

Main Points Review

Custom PHP forms in WordPress offer tailored solutions for handling data effectively. This guide walked through key aspects like HTML structure, secure data handling, validation, AJAX functionality, and spam protection. Here’s a quick recap:

Form Structure: HTML forms integrated seamlessly with WordPress.
Data Processing: Secure handling of form data using PHP.
Validation: Checks performed with PHP on the server and JavaScript on the client.
Security Features: Nonce verification and data sanitization to prevent vulnerabilities.
AJAX Implementation: Smooth, dynamic form submissions.
Spam Protection: Tools like reCAPTCHA and timestamp checks to block spam.

When combined, these elements create a reliable and secure form system.

Learn More

Want to take your skills further? Dive into these advanced topics:

Advanced Form Features: Explore custom validations, file uploads, multi-step forms, and database optimization.
Security Upgrades: Learn about advanced spam prevention, data encryption, and ensuring GDPR compliance.

For in-depth guides on these subjects, check out WP Winners. Their resources cover everything from form creation and plugin development to security best practices, catering to WordPress developers of all experience levels.

WP Winners 🏆