functions.php

If you’re using the child theme and need to add advanced custom features to your site, then the child theme’s functions.php (/wp-content/themes/chap-child/functions.php) is the most common place to add your code.

PHP knowledge required.

The contents of this file are completely up to you, this is how it looks like by default (since Chap 1.19.9):

PHP
Chap Child theme’s default functions.php
<?php
/**
 * Chap Child theme functions.php
 *
 * How to use this file:
 * @see https://chap.website/functions-php
 */
defined('ABSPATH') || exit;
define('CHAP_CHILD_VER', wp_get_theme()->get('Version'));

/**
 * Load child theme assets.
 */
add_action('wp_enqueue_scripts', function() {
	wp_enqueue_style('chap-child', get_stylesheet_directory_uri() . '/style.css', false, CHAP_CHILD_VER);
	wp_enqueue_script('chap-child/js', get_stylesheet_directory_uri() . '/scripts.js', ['chap/js'], CHAP_CHILD_VER, true);
}, 150);

/** Add custom filters, actions and functions below. */

Adding custom actions, filters and functions

Simply add your custom code at the end of the file. It’s a good idea to add comment blocks above your code to have a reference of what the code does when you come back to it months or years later.

PHP
functions.php with custom code
<?php

...

/** Add custom filters, actions and functions below. */

/**
 * Add a custom image size.
 */
add_action('after_setup_theme', function() {
	add_image_size('custom-image-size', 28, 28, true);
});

/**
 * Modify the title.
 */
add_filter('the_title', function($title) {
	return 'The ' . $title . ' was filtered';
});

In the above example anonymous functions are being passed to the WordPress add_action and add_filter functions. This is the cleanest and most readable way of doing it (personal opinion). When reading various WordPress guides and tutorials you may see filters like:

PHP
<?php

...

/** Add custom filters, actions and functions below. */

function myprefix_add_settings() {
	?>
	New 1: <input id="new_setting" name="new_settings" type="text">
	<?php
}
add_action('wporg_after_settings_page_html', 'myprefix_add_settings');

function wporg_filter_title($title) {
	return 'The ' . $title . ' was filtered';
}
add_filter('the_title', 'wporg_filter_title');

and adding them in this format is fine as well, except in that case you will have to make sure that your function name has a unique prefix in order to not conflict with any other functions from core or other plugins that may use the same name.

Overriding theme core functions Advanced

Chap theme includes pluggable functions in PHP namespaces that can be overridden if you wish to change the default functionality.

To override a function in a namespace a new file with the appropriate namespace should be created and included from the main functions.php file of the child theme.

First let’s create the file that defines a chap_render_header_open function in the Chap\TemplateFunctions namespace to override it:

PHP
Create /chap-child/overrides.php
<?php
/**
 * Chap core functions overrides.
 */

namespace Chap\TemplateFunctions {
	use Chap\Options;
	use Chap\Helpers;

	/**
	 * Custom header opening tag function.
	 */
	function chap_render_header_open() {
		$header_classes = Helpers\classnames([
			'ui',
			'inverted' => Options\get('header_inverted'),
			'segment',
		]);

		?>
		Custom content before header opening tag.
		<div class="<?php echo esc_attr($header_classes); ?>">
		<?php
	}
}

Next, this file should be included from the functions.php file:

PHP
Including overrides.php in functions.php
<?php
/**
 * Chap Child theme functions.php
 *
 * How to use this file:
 * @see https://chap.website/functions-php
 */
defined('ABSPATH') || exit;
define('CHAP_CHILD_VER', wp_get_theme()->get('Version'));

/**
 * Load child theme assets.
 */
add_action('wp_enqueue_scripts', function() {
	wp_enqueue_style('chap-child', get_stylesheet_directory_uri() . '/style.css', false, CHAP_CHILD_VER);
	wp_enqueue_script('chap-child/js', get_stylesheet_directory_uri() . '/scripts.js', ['chap/js'], CHAP_CHILD_VER, true);
}, 150);

/** Add custom filters, actions and functions below. */

include_once 'overrides.php';

Now the Chap\TemplateFunctions\chap_render_header_open function is defined and Chap theme will use it instead of the initial one in the theme core.

Page 2 contains documentation of the old functions.php that was provided before Chap version 1.19.9. This version used PHP Namespaces out of the box to allow more intuitive overriding of core functions, how ever this often proved to be too confusing for users with no PHP knowledge.

3 responses to “functions.php

Leave a comment

Your email address will not be published. Required fields are marked *