latest version

PHP Helpers¶

General
Cache
Options
Database
FW_Form
FW_Flash_Messages

General ¶

General PHP helpers:

fw_print($value, $die = false) - styled version of print_r().

fw_html_tag($tag, $attr = null, $end = null) - generate html tag.

echo fw_html_tag('script', array('src' => '/demo.js'), true);

// <script src="/demo.js"></script>

fw_attr_to_html(array $attr_array) - generate html attributes from array.

echo '<div '. fw_attr_to_html(array('id' => 'foo', 'class' => 'bar')) .'></div>';

// <div id="foo" class="bar" ></div>

fw_akg($keys, &$array_or_object, $default_value = null, $keys_delimiter = '/') - get array multikey value.

Note

MultiKey is a string composed from multiple array keys, separated by a delimiter character, that represents an array structure. For example

'a/b/c'

represents

array(
    'a' => array(
        'b' => array(
            'c' => null
        )
    )
)

$demo = array(
    'a' => array(
        'b' => 'hello'
    )
 );

echo fw_akg('a/b', $demo);

// 'hello'

fw_aks($keys, $value, &$array_or_object, $keys_delimiter = '/') - set a multikey value in array.

$demo = array(
    'a' => array()
);

fw_aks('a/b', 'hello', $demo);

print_r($demo);

/*
array(
    'a' => array(
        'b' => 'hello'
    )
)
*/

fw_aku($keys, &$array_or_object, $keys_delimiter = '/') - unset a multikey from array.

$demo = array(
    'a' => array(
        'b' => array()
    )
);

fw_aku('a/b', $demo);

print_r($demo);

/*
array(
    'a' => array()
)
*/

fw_rand_md5() - generate a random md5.

fw_unique_increment() - random number incremented every time you call the function.

echo fw_unique_increment(), PHP_EOL;
echo fw_unique_increment(), PHP_EOL;
echo fw_unique_increment(), PHP_EOL;

/*
9370
9371
9372
*/

fw_stripslashes_deep_keys($value) - strip slashes (recursive) from values and keys (if value is array) if magic_quotes_gpc = On.

fw_addslashes_deep_keys($value) - add slashes (recursive) to values and keys (if value is array) if magic_quotes_gpc = On.

fw_current_screen_match($rules) - check if current global $current_screen; (available in admin side) matches the given rules. Used to detect on which admin page you currently are. Thus you can for example enqueue a script only on a target page, not on all admin pages.

/**
 * @internal
 */
function _action_enqueue_demo_admin_scripts() {
    // To find out what is the current screen of the current page, uncomment next line
    //global $current_screen; fw_print($current_screen);

    $only = array(
        'only' => array(
            array( 'id' => 'dashboard' )
        )
    );

    if (fw_current_screen_match($only)) {
        // enqueue this script only on dashboard page
        wp_enqueue_script(
            'demo-dashboard',
            get_template_directory_uri() .'/js/demo-only.js'
        );
    }

    $exclude = array(
        'exclude' => array(
            array( 'id' => 'dashboard' ),
            array( 'post_type' => 'post' )
        )
    );

    if (fw_current_screen_match($exclude)) {
        // enqueue this script on all admin pages
        // except dashboard page and all pages from posts menu (add, edit, categories, tags)
        wp_enqueue_script(
            'demo-dashboard',
            get_template_directory_uri() .'/js/demo-excluded.js'
        );
    }
}
add_action('admin_enqueue_scripts', '_action_enqueue_demo_admin_scripts');

Note

You can combine only and exclude in the same rules array.

fw_locate_theme_path_uri($rel_path) - search by relative path, in child then in parent theme directory, and return URI.
echo fw_locate_theme_path_uri('/styles.css'); // http://your-site.com/wp-content/themes/child-theme/style.css

fw_locate_theme_path($rel_path) - search by relative path, in child then in parent theme directory, and return full path.

echo fw_locate_theme_path('/styles.css');

// /var/www/wordpress/public_html/wp-content/themes/child-theme/style.css

fw_render_view($file_path, $view_variables = array()) - safe render view and return html. In view will be accessible only passed variables, not current context variables.

$private = 'Top Secret';

echo fw_render_view(
    get_stylesheet_directory() .'/demo-view.php',
    array('message' => 'Hello')
);

/* demo-view.php
<?php if (!defined('FW')) die('Forbidden');

echo $message;
echo $private;
*/

// Hello
// Notice: Undefined variable: private

fw_get_variables_from_file($file_path, array $variables) - extract specified variables from file.

$variables = fw_get_variables_from_file(
    get_stylesheet_directory() .'/demo-variables.php',
    array(
        'message' => 'Hi',
        'foo' => 'bar'
    )
);

/* demo-variables.php
<?php if (!defined('FW')) die('Forbidden');

$message = 'Hello';
*/

print_r($variables);

/*
array(
    'message' => 'Hello',
    'foo' => 'bar'
)
*/

fw_include_file_isolated($file_path) - include files isolated and don’t give access to current context variables.

$private = 'Top Secret';

fw_include_file_isolated(get_stylesheet_directory() .'/demo-isolated.php');

/* demo-isolated.php
<?php if (!defined('FW')) die('Forbidden');

echo $private;
*/

// Notice: Undefined variable: private

fw_html_attr_name_to_array_multi_key($attr_name) - convert html name attribute to multikey.
echo fw_html_attr_name_to_array_multi_key('a[b][c]'); // 'a/b/c'

fw_is_real_post_save() - used in ‘save_post’ action to detect if it’s a real post save, not a revision, auto save or something else.

fw_current_url() - generate current page url from $_SERVER data.

fw_is_valid_domain_name($domain_name) - check if a domain name is valid.

fw_htmlspecialchars($string) - UTF-8 version of php’s htmlspecialchars(). Just a shorthand not to write two more parameters for default htmlspecialchars() every time.

Note

In php 5.2 htmlspecialchars() default encoding is not UTF-8.

fw_human_time($seconds) - convert seconds to human readable time.
echo fw_human_time(12345); // '3 hours'

fw_strlen($string) - UTF-8 version of php’s strlen().

echo strlen('Привет!'), PHP_EOL;
echo fw_strlen('Привет!'), PHP_EOL;

// 13
// 7

fw_is_post_edit() - check if you are currently on a post edit page. It also detects if form submit was made from the post edit page.

fw_dirname_to_classname($dirname) - convert directory name to string to be used as/in class name.
echo 'FW_'. fw_dirname_to_classname('hello-world'); // FW_Hello_World

fw_fix_path($path) - make sure a path is in unix style, with / directory separators.

fw_get_stylesheet_customizations_directory() - Full path to the child-theme/framework-customizations directory.

fw_get_stylesheet_customizations_directory_uri() - URI to the child-theme/framework-customizations directory.

fw_get_template_customizations_directory() - Full path to the parent-theme/framework-customizations directory.

fw_get_template_customizations_directory_uri() - URI to the parent-theme/framework-customizations directory.

fw_get_framework_directory() - Full path to the parent-theme/framework directory.

fw_get_framework_directory_uri() - URI to the parent-theme/framework directory

Cache ¶

Use cache to store frequently accessed data. Cache is just a big array and has one useful feature: it will automatically begin to unset array keys if the php memory is close to full. So it is safe to store in it as much data as you want (of course the maximum allowed by php, by default is ~100Mb).

function get_foo_bar() {
    $cache_key = 'foo/bar';

    try {
        /**
         * This will throw an exception if the key was not found
         */
        return FW_Cache::get($cache_key);
    } catch (FW_Cache_Not_Found_Exception $e) {
        $data = _generate_foo_bar_data();

        FW_Cache::set($cache_key, $data);

        return $data;
    }
}

Attention

Don’t do this:

    ...
} catch (FW_Cache_Not_Found_Exception $e) {
    FW_Cache::set($cache_key, _generate_foo_bar_data());

    return FW_Cache::get($cache_key);
}

because FW_Cache::set(...) can fail or the data that was set can be removed after automatically memory free.

Options ¶

Functions for working with options:

fw_extract_only_options(array $options) - extract only regular options from any array of options.

$options = array(
    array(
        'type' => 'box',
        'options' => array(
            'demo-1' => array(
                'type' => 'text'
            )
        )
    ),
    array(
        'type' => 'box',
        'options' => array(
            array(
                'type' => 'tab',
                'options' => array(
                    'demo-2' => array(
                        'type' => 'textarea'
                    )
                )
            )
        )
    )
);

print_r( fw_extract_only_options($options) );

/*
array(
    'demo-1' => array(
        'type' => 'text'
    ),
    'demo-2' => array(
        'type' => 'textarea'
    )
)
*/

fw_get_options_values_from_input(array $options, $input_array = null) - extract options values from input array. If no input array is provided, values from $_POST will be used.

$options = array(
    'demo-1' => array( 'type' => 'text', 'value' => 'default value 1' ),
    'demo-2' => array( 'type' => 'text', 'value' => 'default value 2' ),
);

$input_values = array(
    'demo-1' => 'input value 1',
    'demo-3' => 'input value 3',
);

$values = fw_get_options_values_from_input($options, $input_values);

print_r($values);

/*
array(
    'demo-1' => 'input value 1',
    'demo-2' => 'default value 2',
)
*/

fw_prepare_option_value($value) - by default WordPress offers filters for other plugins to alter database options and post meta. For ex translation plugins use these filters to translate things. If you save your options values in a custom place (like framework does by default, by saving options in a serialized array in database options and post meta) the WordPress filter doesn’t know how to work with them.

Tip

Use this function to pass an option value through filters and translation features that simulates WordPress default behavior. This function is already used in core so you don’t have to bother about passing options values through it each time. Use it if you will do something custom and strings will not be translated.

Database ¶

fw_get_db_settings_option($option_id, $default_value = null) - get value from the database of an option from the theme settings page. Settings options are located in framework-customizations/theme/options/settings.php.

fw_set_db_settings_option($option_id, $value) - set a value in the database for an option from the theme settings page.

fw_get_db_customizer_option($option_id, $default_value = null) - get value from the database of an option from the customizer page. Customizer options are located in framework-customizations/theme/options/customizer.php.

fw_set_db_customizer_option($option_id, $value) - set a value in the database for an option from the customizer page.

fw_get_db_post_option($post_id, $option_id, $default_value = null) - get a post option value from the database. Post options are located in framework-customizations/theme/options/posts/{post-type}.php.

fw_set_db_post_option($post_id, $option_id, $value) - set a post option value in the database.

fw_get_db_term_option($term_id, $taxonomy, $option_id, $default_value = null) - get a term option value from the database. Term options are located in framework-customizations/theme/options/taxonomies/{taxonomy}.php.

fw_set_db_term_option($term_id, $taxonomy, $option_id, $value) - set a term option value in the database.

fw_get_db_ext_settings_option($extension_name, $option_id, $default_value = null) - get extension settings option value from the database.

fw_set_db_ext_settings_option($extension_name, $option_id, $value) - update extension settings option value in the database.

fw_get_db_extension_data($extension_name, $key, $default_value = null) - get a value from the database of some private data stored by an extension.

fw_set_db_extension_data($extension_name, $key, $value) - extensions uses this function to store private values in the database.

FW_Form ¶

A convenient way to create forms. You can create a form class instance and give it three callbacks that control the render, validate and save process.

$my_form = new FW_Form('<unique-id>', array(
    'render'   => '_my_form_render',
    'validate' => '_my_form_validate',
    'save'     => '_my_form_save',
));

function _my_form_render() {
    $input_value = FW_Request::POST('demo');

    echo '<input type="text" name="demo" maxlength="10" value="'. esc_attr($input_value) .'">';
}

function _my_form_validate($errors) {
    $input_value = FW_Request::POST('demo');

    if (fw_strlen($input_value) > 10) {
        $errors['demo'] = __('Value cannot be more that 10 characters long', '{domain}');
    }

    return $errors;
}

function _my_form_save() {
    $input_value = FW_Request('demo');

    // do something with value
}

echo $my_form->render();
// this will output:
// <form ... ><input type="text" name="demo" maxlength="10" value=""></form>

Customize errors ¶

By default the errors are displayed right before the <form> tag. You can display the errors in your own way and cancel the default display. Before the errors are displayed, an action is fired so you can use it:

/**
 * @param FW_Form $form
 * @internal
 */
function _action_theme_fw_form_errors_display($form) {
    /**
     * Once the errors was accessed/requested
     * the form will cancel/abort the default errors display
     */
    $errors = $form->get_errors();

    echo '<ul class="your-custom-errors-class">';
    foreach ($errors as $input_name => $error_message) {
        echo fw_html_tag(
            'li',
            array('data-input-name' => $input_name),
            $error_message
        );
    }
    echo '</ul>';
}
add_action('fw_form_display_errors_frontend', '_action_theme_fw_form_errors_display');

Ajax submit ¶

You can use this script to make FW_Form ajax submittable.

Enqueue the script in frontend:

// file: {theme}/inc/static.php
// https://github.com/ThemeFuse/Theme-Includes

if (!is_admin()) {
    wp_enqueue_script(
        'fw-form-helpers',
        fw_get_framework_directory_uri('/static/js/fw-form-helpers.js')
    );
    wp_localize_script('fw-form-helpers', 'fwAjaxUrl', admin_url( 'admin-ajax.php', 'relative' ));
}

Run the initialization script:

jQuery(function(){
    fwForm.initAjaxSubmit({
        //selector: 'form[some-custom-attribute].or-some-class'

        // Open the script code and check the `opts` variable
        // to see all options that you can overwrite/customize.
    });
});

Create Settings Page ¶

If you want to create a settings page similar to Theme Settings, this will help you getting started.

FW_Flash_Messages ¶

You can display small messages that will be stored on the user’s session for exactly one additional request. This is useful when processing a form: you want to redirect and have a special message shown on the next page. These types of messages are called “flash” messages.

Adding a flash message

FW_Flash_Messages::add(
    'unique-id',
    __('Test message', '{domain}'),
    'success' // available types: info, warning, error, success
);

Displaying flash messages

In admin the messages are displayed as admin notices.

In frontend the messages are printed in footer, then a javascript tries to find on the page the content container and move the messages in it. This position guessing sometimes fails when the page has some special html structure and the messages may not be visible or will be displayed in an inappropriate place. You can choose a place in your template and display the messages manually:

<?php if (defined('FW')) { FW_Flash_Messages::_print_frontend(); } ?>

Introduction JavaScript Helpers

Check out our extended

Developer Manual

PHP Helpers¶

General ¶

Cache ¶

Options ¶

Database ¶

FW_Form ¶

Customize errors ¶

Ajax submit ¶

Create Settings Page ¶

FW_Flash_Messages ¶

Developer Manual