WordPress Contact Form 7 Hook Unofficial Developer Documentation and Examples

by
on September 21, 2012
(21 minute read)

There is a lot of confusion around the Internet on how to properly configure action hooks in Contact Form 7. A few days ago I spent a few hours developing a plugin to customize and enable some intelligent detection of the forms data and I got it to work. From what I’ve seen around the Internet, there is no official documentation and most of the forum questions and threads are not answered so in this developers’ tutorial I’ll try to answer all these questions here.

Things I’m buying on Amazon this week

IMPORTANT: Please note that some things have changed in the latest version (3.9) of the plugin, I will update this post ASAP, see Andrew’s comment for the changes. Documentation below is valid for v3.8 and below.

This post is not dedicated to solve errors like “Emails not getting sent”, “How to increase textbox size” and so on, that’s a server missconfiguration or some CSS code, here we’ll just go through the Contact Form 7 action hook provided and how to code your own WordPress plugin to improve WPCF7. I’ll start with the basics so everyone can follow this and then move to more complex features:

Creating a WordPress plugin

You need to know PHP code and have access to the files in your server. Then, create a .php file and copy-paste this:

/*
Plugin Name: Contact Form 7 special functionalities
Plugin URI: https://xaviesteve.com/
Description: 
Author: Xavi Esteve
Version: 0.1b
Author URI: https://xaviesteve.com/
*/
function wpcf7_do_something (&$WPCF7_ContactForm) {
    // Our code will go here
}
add_action("wpcf7_before_send_mail", "wpcf7_do_something");

Change the plugin name and author and we now have a simple plugin that creates an action hook into CF7. Upload this file to your /wp-content/plugins/ folder and enable it in the WordPress Dashboard.

Note: the & symbol in the function parameter references the object so that any change done inside the hook will also be reflected later in CF7.

Understanding the CF7 object

One of the main issues with users having problems with Contact Form 7s’ hook is that they don’t understand how the object works, here’s a full example of the object for your reference. If you look at it closely you’ll see how it starts being a PHP object but then those objects are arrays so you always need to call the CF7 object like object->object['array']. Also, returning the object at the end of the function is not required but a good practice.

WPCF7_ContactForm Object
(
    [initial] => 
    [id] => 577
    [title] => Home page form
    [unit_tag] => 
    [responses_count] => 0
    [scanned_form_tags] => Array
        (
            [0] => Array
                (
                    [type] => text*
                    [name] => name
                    [options] => Array
                        (
                            [0] => id:firstfield
                        )

                    [raw_values] => Array
                        (
                        )

                    [values] => Array
                        (
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                )

                        )

                    [labels] => Array
                        (
                        )

                    [attr] => 
                    [content] => 
                )

            [1] => Array
                (
                    [type] => email
                    [name] => email
                    [options] => Array
                        (
                        )

                    [raw_values] => Array
                        (
                        )

                    [values] => Array
                        (
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                )

                        )

                    [labels] => Array
                        (
                        )

                    [attr] => 
                    [content] => 
                )

            [2] => Array
                (
                    [type] => text*
                    [name] => phone
                    [options] => Array
                        (
                        )

                    [raw_values] => Array
                        (
                        )

                    [values] => Array
                        (
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                )

                        )

                    [labels] => Array
                        (
                        )

                    [attr] => 
                    [content] => 
                )

            [3] => Array
                (
                    [type] => textarea
                    [name] => message
                    [options] => Array
                        (
                        )

                    [raw_values] => Array
                        (
                        )

                    [values] => Array
                        (
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                )

                        )

                    [labels] => Array
                        (
                        )

                    [attr] => 
                    [content] => 
                )

            [4] => Array
                (
                    [type] => submit
                    [name] => 
                    [options] => Array
                        (
                            [0] => class:button
                        )

                    [raw_values] => Array
                        (
                            [0] => Send
                        )

                    [values] => Array
                        (
                            [0] => Send
                        )

                    [pipes] => WPCF7_Pipes Object
                        (
                            [pipes] => Array
                                (
                                    [0] => WPCF7_Pipe Object
                                        (
                                            [before] => Send
                                            [after] => Send
                                        )

                                )

                        )

                    [labels] => Array
                        (
                            [0] => Send
                        )

                    [attr] => 
                    [content] => 
                )

        )

    [posted_data] => Array
        (
            [_wpcf7] => 577
            [_wpcf7_version] => 3.2.1
            [_wpcf7_unit_tag] => wpcf7-f577-p2-o1
            [_wpnonce] => 8dabc14d71
            [name] => John Moore
            [email] => [email protected]
            [phone] => 07912345678
            [message] => I am interested to know more about your company
            [_wpcf7_is_ajax_call] => 1
        )

    [uploaded_files] => Array
        (
        )

    [skip_mail] => 
    [form] => 
Name

    [text* name] 

Email

    [email email] 

Phone

    [text* phone] 

Enquiry

    [textarea message] 

[submit class:button "Send"]

    [mail] => Array
        (
            [subject] => MyWebsite - New form submission
            [sender] => MyWebsite <[email protected]> 
            [body] => 
            [recipient] => Xavi <[email protected]> 
            [additional_headers] => 
            [attachments] => 
            [use_html] => 1
        )

    [mail_2] => Array
        (
            [active] => 
            [subject] => 
            [sender] => 
            [body] => 
            [recipient] => 
            [additional_headers] => 
            [attachments] => 
            [use_html] => 
        )

    [messages] => Array
        (
            [mail_sent_ok] => Your message was sent successfully. We will call you soon.
            [mail_sent_ng] => Failed to send your message. Please try later or contact administrator by other way.
            [akismet_says_spam] => Failed to send your message. Please try later or contact administrator by other way.
            [validation_error] => Please fill in the required fields and submit the form again.
            [accept_terms] => Please accept the terms to proceed.
            [invalid_email] => Email address seems invalid.
            [invalid_required] => Please fill the required field.
            [captcha_not_match] => Your entered code is incorrect.
            [upload_failed] => Failed to upload file.
            [upload_file_type_invalid] => This file type is not allowed.
            [upload_file_too_large] => This file is too large.
            [upload_failed_php_error] => Failed to upload file. Error occurred.
            [quiz_answer_not_correct] => Your answer is not correct.
        )

    [additional_settings] => 
    [submit_time] => 1348136521.36
    [ip] => 82.18.147.15
)

 

Contact Form 7 action hook examples

So that’s pretty much it, creating a WordPress action hook to the wpcf7_before_send_mail and understanding how to traverse the object should allow any midweight PHP developer to do pretty much anything with it. Let’s see some examples, to use them get the piece of code at the top of the article and put it inside.

Reading a posted value in the form with PHP

$firstname = $WPCF7_ContactForm->posted_data['firstname'];

Having multiple email recipients

No need to code any PHP for this, just go to edit the form through the WordPress Dashboard and add different emails separated by commas:

John <[email protected]>,Mark <[email protected]>

Changing email recipient dynamically depending on code

if ($WPCF7_ContactForm->posted_data['radiobuttonname'] == "Yes") {
    $WPCF7_ContactForm->mail['recipient'] = "John <[email protected]>";
}else{
    $WPCF7_ContactForm->mail['recipient'] = "Mark <[email protected]>";
}

Avoiding CF7 from sending email

Change the skip_mail value to true.

$wpcf7_data->skip_mail = true;

Redirecting someone to a different page depending on submitted data

The additional_settings is what we need to change. Here’s a self explanatory example:

if ($foo == "provider") {
    $wpcf7_data->additional_settings = "on_sent_ok: \"location.replace('https://xaviesteve.com//provider/');\"";
}else{
    $wpcf7_data->additional_settings = "on_sent_ok: \"location.replace('https://xaviesteve.com//client/');\"";
}

Note: My WordPress removed some code when publishing it, remember to add backward slashes to the inner double quotes in the code above.

Adding more text in the sent email

Simple Cloud Hosting Built for Developers

For example, we can add the users’ IP address:

$wpcf7_data->mail['body'] .= '<p>IP Address: '.$_SERVER['REMOTE_ADDR'].'</p>';

Get page from which form was submitted

$pagesubmitted = $_SERVER['HTTP_REFERER'];

That’s it!

You should now have total control over the Contact Form 7 plugin. For any other examples or questions on the code please feel free to comment below, for other issues please visit the Contact Form 7 official WordPress forum.

Looking for cool gift ideas? TrendLiker.com lists hundreds of nice items and lets you know when they go on sale on Amazon.

Did you enjoy this article?

Thank with a coffee ☕

Or help me out by clicking one of these buttons:

    
    

No comments yet

Follow me for cool new products and interesting findings on graphic design, web development, marketing, startups, life and humor.


/*Twitter*/ !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs"); /*Facebook (function(d, s, id) {var js, fjs = d.getElementsByTagName(s)[0];if (d.getElementById(id)) {return;}js = d.createElement(s); js.id = id;js.src = "//connect.facebook.net/en_GB/all.js#xfbml=1&appId=28624667607";fjs.parentNode.insertBefore(js, fjs);}(document, 'script', 'facebook-jssdk'));*/ /*Google+*/ window.___gcfg = {lang: 'en-GB'};(function() {var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;po.src = 'https://apis.google.com/js/plusone.js';var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);})();
Airbnb 25€ discount