Home

Welcome to the wiki page for wordpress-base-plugin.

More documentation will be added as the plugin evolves.

Dependencies

Carbon Fields

This plugin uses Carbon Fields to handle custom fields and plugin settings. In order for it to work, you will either need to add it as a Composer dependency or install a compatible Carbon Fields Loader plugin.

Loader Plugin

To avoid conflicts caused by multiple versions of Carbon Fields being loaded, it is recommended that you use a Carbon Fields Loader plugin.

Simply clone/download it to your plugins folder an activate.

Composer Dependency

Alternatively, you may also load Carbon Fields as a Composer dependency.

1. Add "htmlburger/carbon-fields": "^2.0.0", to the require section of composer.json.
2. Run composer update.
3. This plugin also uses TGMPA to show a notice when the Carbon Fields Loader is not detected. You can remove this check by commenting out the TGMPA line in app/Plugin.php or by modifying app/TGMPA.php to exclude it as a requirement.

Getting Started

Once you have cloned/downloaded the base plugin, follow these steps to make it your own.

Install Node Modules

Change to the directory where the plugin is located and run the following to install NPM dependencies:

npm install

Rename Files and Strings

1. Edit the package.json file. In the config section, change the slug from "wordpress-base-plugin" to your own (if you're not sure, set it to what you intend to name the plugin directory).
2. Change the namespace from "VendorName\\PluginName" to your own namespace.
3. Save the file.

At the command prompt, run:

npm run rename

This will replace the namespaces, slugs and filenames to your new strings.

Finally, open composer.json and change the autoload psr-4 namespace from "VendorName\\PluginName\\" to your own namespace, paying attention to the double backslashes. Save changes.

Install Composer Dependencies

Important: See Dependencies for important information about Carbon Fields. If you are not going to usae the Carbon Fields Loader, you must add Carbon Fields as a dependency to your composer.json file first.

To install Composer dependencies, run:

composer install

Other Changes

Edit the following files and change the names, descriptions, versions, etc as necessary:

• composer.json
• package.json
• plugin.json
• readme.txt
• The main plugin PHP file in the plugin root directory (initially wordpress-base-plugin.php before running the npm run rename command.

Translation

Translation language files can be created automatically using wp-pot-cli.

Assuming the you have already run npm install, you can run the following command to create a translation file in the languages directory:

npm run translate

Usage Examples

Caching

The caching class is intended to make it easy to reduce database calls and other resource-intensive operations.

• If object caching is enabled and the key exists, it will be return from cache.
• If either of the above are not true, it will fetch and return the current value.

Simple Example

$my_option = Cache::get_object( '_cache_key_name', function() {
  return get_option( '_my_option_name' );
});

Carbon Fields Example

$my_option = Cache::get_object( '_cache_key_name', function() {
  return carbon_get_theme_option( self::$prefix . '_my_option_name );
});

Additionally, the Plugin class contains a wrapper for retrieving Carbon Fields values:

$my_option = $this->get_plugin_option( '_my_option_name' );

Flushing the Cache

There is also a Cache::flush() function that you can use to clear the cache when the "Save Changes" button (or anywhere appropriate, such as on posts and pages). Example:

add_action('carbon_fields_theme_options_container_saved', array( '\\VendorName\\MyPlugin\\Cache', 'flush' ) );

Testing

An easy way to test object caching locally is to install Local by FlyWheel (which loads sites in virtual machines and also includes Redis) and:

1. Create a new site.
2. Install and activate the Redis Object Cache plugin.
3. Click the Enable Object Cache button in Settings > Redis.

You can now enable/disable/flush the cache and test to make sure that everything is functioning as expected.