CFDB Plugin

Situation

In a short code or export link you want to have a filter expression that calls a PHP function on a field value. Example: You want to check for a value in a case-insensitive way: [cfdb-table form=”form1″ show=”first_name” filter=”strtoupper(first_name)=MIKE”] Output looks like:

Here we use the PHP function strtoupper to upper-case the value in the first_name field and compare it with “MIKE“. This does not upper case first_name when it is displayed. It only upper cases it for the purpose of doing the comparison. So if the actual value for first_name is “Mike” the filter would pass but you would still see “Mike” displayed by the short code output. Alternatively, a filter does not need to be compared to a value if it just returns true or false. For example, the following short code filters for all “your-email” fields that have “@gmail.com” in them. [cfdb-table form=”myform” filter=”strpos(your-email,@gmail.com)>1″]

Filter Functions vs. Transforms Functions

Instead of upper-casing first_name in the filter, we can upper-case it before it gets to the filter. Using a transform, we change the actual value of the first_name field. Then when it gets to the filter, it is already upper-cased. Furthermore, it is displayed by the short code as upper-cased. [cfdb-table form=”form1″ show=”first_name” trans=”first_name=strtoupper(first_name)” filter=”first_name=MIKE”] Output looks like:

See more about Transform Functions. The rest of this page focuses on Filter Functions

What Functions Can Be Used?

Potentially any PHP function can be used, including those you create. But there are only a small set that you can use with default settings. These include most string-related PHP functions.

Function Security

A user who can create a short code (or export link) could potentially run a PHP function that might harm your installation or data. Therefore security restrictions are in place by default. This security can be turned off entirely in the administration page Contact Form DB -> Options -> Allow Any Function in Short Codes. If that is set to true then users which role for Can See Submission when using shortcodes can write a short code or compose a URL that can run any PHP function. It is best to keep this option to false. Alternatively, individual functions that the administrator deems as safe can be registered as being permissible to use.

Permitting a Function and Creating Custom Functions

To permit individual functions, you will need to be able to add PHP code to register function names. First, install the Shortcodes Actions and Filters plugin and activate it. From the administration page, go to the Tools menu -> Shortcodes Actions and Filters. Put your code there and save. Syntax errors will be displayed when you save. Example: to register a custom function “cfdb_reverse” define the function the call cfdb_register_function.

1
2
3
4
5
6
7

require_once(ABSPATH . 'wp-content/plugins/contact-form-7-to-database-extension/CFDBPermittedFunctions.php');
 
function cfdb_reverse($text) {
  return strrev($text);
}
 
cfdb_register_function('cfdb_reverse');

You can then use the function in a filter, e.g. [cfdb-table form=”myform” filter=”cfdb_reverse(first_name)=ekim”] Existing PHP and WordPress functions can be added using cfdb_register_function(function_name).

Function Parameters

Your custom function can take zero or more parameters. Parameters can be:

• Form field names (such as first_name) in which case the value of the field is used, e.g.
  • filter=”strtoupper(first_name)=MIKE”
• Filter variables, e.g. $user_login, POST, GET, and COOKIE values. E.g.
  • filter=”last_name=my_lookup_user($user_login)”
  • filter=”last_name=my_lookup_user($POST(lname))”
• PHP constants, e.g. “STR_PAD_BOTH” in
  • filter=”str_pad(first_name, 10, “_”, STR_PAD_BOTH)=”___Mike___”
• Literal values. Anything not recognized as one of the above will be passed as a string to the function. Do not quote the string.
  • Any function call that is not recognized or not permitted is treated as a string literal
• Multiple parameters: any combination of the above. Separate parameters with commas.
  • filter=”user=my_lookup_user(first_name,last_name,$user_login)”

Passing the entire form entry: if no parameters are listed as being passed to the function, then an associative array of all the form fields is passed. This is useful if you would like to write a function that filters on more than one field as a time. Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

require_once(ABSPATH . 'wp-content/plugins/contact-form-7-to-database-extension/CFDBPermittedFunctions.php');
 
function check_address($street, $state, $zip){
  // TODO: put your code here
  return true;
}
 
function has_valid_address($entry) {
  return check_address(
    $entry['street'],
    $entry['state'],
    $entry['zip']);
}
 
cfdb_register_function('has_valid_address');

You can then use the function in a filter, e.g. [cfdb-table form=”myform” filter=”has_valid_address()”]

More on Filter Function Syntax

General forms you can use: 1. Functions that return true or false: your function returns true or false indicating if the filter passes: [cfdb-table form=”myform” filter=”has_valid_address()”] 2. Functions that return a value. Transforms a field value for comparison with a literal value [cfdb-table form=”myform” filter=”strtoupper(first_name)=MIKE”] 3. Combinations using existing filter Boolean logic (&&=AND, ||=OR) [cfdb-table form=”myform” filter=”strtoupper(first_name)=MIKE&&strtoupper(last_name)=SIMPSON”]

Debugging

Add to your short code debug=”true” to make the short code display how it parses its expression. The important thing to remember for functions is that a function will be parsed into an array where the first value is the function name followed by an array element for each parameter. If the function is not allowed or not recognized then the entire function is shown still as a whole string. See Debugging Filter Expressions. Function is parsed:

'cfdb_reverse(first_name)=ekiM'
Array
(
    [0] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [0] => cfdb_reverse
                            [1] => first_name
                        )

                    [1] => =
                    [2] => ekiM
                )

        )

)

Function is not parsed:

'cfdb_reverse(last_name)=ekiM'
Array
(
    [0] => Array
        (
            [0] => Array
                (
                    [0] => cfdb_reverse(last_name)
                    [1] => =
                    [2] => 1ih
                )

        )

)