Packaging required plugins with a WordPress theme

A Theme is responsible for the design and layout of your WordPress website. Whereas, a Plugin controls the behavior and functionality of a site.  As a theme developer, we need to include some additional improvements and features to enhance the functionality of the theme.

I had a business case where we needed some plugins to be made required on installing the child theme. So, after going through lots of blogs I found an easy way to make it possible.

In order to accomplish the same, we need to include the required plugins as you cannot add them to the theme folder.  Wouldn’t it be great if all the required plugins are ready to be installed when you activate your custom theme? This can be done using a library called as “TGM Plugin Activation”.

In this tutorial, we are going to see how to include the plugins into the theme folder as I have done in mine.

TGM Plugin Activation defines this library as:

TGM Plugin Activation is a PHP library that allows you to easily require or recommend plugins for your WordPress themes (and plugins). It allows your users to install, update and even automatically activate plugins in singular or bulk fashion using native WordPress classes, functions and interfaces. You can reference bundled plugins, plugins from the WordPress Plugin Repository or even plugins hosted elsewhere on the internet.

Installation process:

The following steps will guide you through the installation and how to use the plugin:

Step 1: Download the TGM Activation plugin from their website.

Step 2: Unzip the folder and find class-tgm-plugin-activation.php in the root and copy this inside your themes folder.

Step 3: In order to include this library we need to use require_once in our functions.php fileThis can be done for plugin level as well as theme level implementation. In theme level, we have parent and child theme implementations. Depending on the implementation you can change the include call.

For Child Theme:

require_once get_stylesheet_directory() . '/path/to/class-tgm-plugin-activation.php';

Parent Theme:

require_once get_template_directory() . '/path/to/class-tgm-plugin-activation.php';


require_once dirname( __FILE__ ) . '/path/to/class-tgm-plugin-activation.php';

Step 4: Now, let’s create a file in our theme folder which contains the PHP code to require/recommend plugins and name it as tgm_activation.php or you can copy the example.php from the root folder of TGM Activation plugin and rename it.

Step 5: In the .php file create a function to configure TGM Plugin Activation and hook it to tgmpa_register via the add_action() function.

add_action( 'tgmpa_register', 'setup_plugins' );

If you have renamed the example.php file, then you can skip this step as the function is already hooked into ‘tgmpa_register’.

Step 6: In the function, we need to create two arrays – $plugins, $config. $plugins array is where we need to include all the plugins we need. $config is optional. We then pass these variables into ‘tgmpa()’ function.

function setup_plugins() {
    $plugins = array( /* To install plugins */ );
    $config = array( /* To configure TGM Plugin Activation - Optional */ );

    tgmpa( $plugins, $config );

The $plugin array takes the following parameters:

$plugins = array(

	// This is an example of how to include a plugin bundled with a theme.
		'name'               => 'TGM Activation Plugin', // The plugin name.
		'slug'               => 'tgm-activation-plugin', // The plugin slug (typically the folder name).
		'source'             => get_stylesheet_directory() . '/lib/plugins/', // The plugin source. It can be an external link, wordpress plugin repository or a GITHUB repository.
		'required'           => true, // If false, the plugin is only 'recommended' instead of required.
		'version'            => '', // E.g. 1.0.0. If set, the active plugin must be this version or higher. If the plugin version is higher than the plugin version installed, the user will be notified to update the plugin.
		'force_activation'   => false, // If true, plugin is activated upon theme activation and cannot be deactivated until theme switch.
		'force_deactivation' => false, // If true, plugin is deactivated upon theme switch, useful for theme-specific plugins.
		'external_url'       => '', // If set, overrides default API URL and points to an external URL.
		'is_callable'        => '', // If set, this callable will be checked for availability to determine if a plugin is active.

I have included custom sidebars plugin in the following way:

$plugins= array(
	'name' => 'Custom sidebars',
	'slug' => 'custom-sidebars',
        'source'    => get_template_directory() . '/lib/plugins/',
	'required' => true,
	'force_activation' => false

The $config array is used to configure the TGM plugin activation library. The options that can be set are:

$config = array(
	'id'           => 'tgm_act',               // Unique ID for hashing notices for multiple instances of TGMPA.
	'default_path' => '',                      // Default absolute path to bundled plugins.
	'menu'         => 'tgmpa-install-plugins', // Menu slug.
	'parent_slug'  => 'themes.php',            // Parent menu slug.
	'capability'   => 'edit_theme_options',    // Capability needed to view plugin install page, should be a capability associated with the parent menu used.
	'has_notices'  => true,                    // Show admin notices or not.
	'dismissable'  => true,                    // If false, a user cannot dismiss the nag message.
	'dismiss_msg'  => '',                      // If 'dismissable' is false, this message will be output at top of nag.
	'is_automatic' => false,                   // Automatically activate plugins after installation or not.
	'message'      => '',                      // Message to output right before the plugins table.

After including this library in your theme and after activating it, a message will be displayed prompting you to install the plugins you have specified.


‘Begin Installing Plugins’ and then the plugins’ functionalities are ready to be used in your theme. I have done the same and it’s working pretty fine. This is the best and easy way to implement the functionality along with WordPress themes.


About The Author

Leave a Reply