The proper way to include/require PHP files in WordPress

Question

I'm a new WordPress developer and recently I've been having problems (on multiple sites) with include_once and require_once for PHP files. If I include (get_theme_directory_uri() . 'subdir/file') the specified file gets included (or required, which leads to fatal errors) but if any WordPress functions are called within 'file' I get something similar to:

'Call to undefined function add_action() in /full/path/to/file'.

The apparent solution I've found is to do:

include(dirname(__FILE__) . "/subdir/filename");

Is this right or did I miss 'the WordPress way' to include files somewhere?

Answer 1

If you check https://codex.wordpress.org/Function_Reference/get_template_directory_uri

You will see get_template_directory_uri() returns a uri, not a server path.

You should use instead the get_template_directory() function, which returns the path to the theme, without trailing slash:

include get_template_directory() . '/subdir/filename.php';

For a plugin you can use the plugin_dir_path() function:

include plugin_dir_path( __FILE__ ) . '/subdir/filename.php';

Answer 2

WordPress 4.7+ introduce get_theme_file_path() functions to include file on WordPress theme.

Include like this:

include get_theme_file_path( '/subdir/filename.php' );

The advantage of using this function is on child theme you can override the parent theme file.

Reference : https://developer.wordpress.org/reference/functions/get_theme_file_path/

Answer 3

In the following examples, I assume you are using composer and a child theme might be enabled or not.

1. Use this method if you want to include a file within a theme and want to ensure the parent theme's directory is used even if a child theme is enabled:

require get_template_directory() . '/vendor/autoload.php';

2. Or use this method if you want to include a file within a theme and don't mind whether the parent theme's directory is used or the child theme's directory is used if a child theme is enabled:

require get_stylesheet_directory() . '/vendor/autoload.php';

3. And lastly, use this method if you want to include a file within a plugin:

require __DIR__ . '/vendor/autoload.php';

Be careful with the last method because the magic constant __DIR__ will have a different value depending on the directory in which your php file is located.

Note that there's no benefit to using the plugin_dir_path() function as it is just a wrapper to the trailingslashit() function.

The documentation says:

The “plugin” part of the name is misleading – it can be used for any file, and will not return the directory of a plugin unless you call it within a file in the plugin’s base directory.

See https://developer.wordpress.org/reference/functions/plugin_dir_path/ for more details.

Also note that using include is poor practice because a missing file will only raise a warning. Always use require instead, because a missing file will raise a fatal error and won't stay unnoticed.