Plugin Class
This document explains the Plugin
class in WP Bones, which is responsible for plugin initialization, registration, and loading. You can access the Plugin
class using the WPKirk()
helper function. The document details the config()
method, which is used to get or set configuration values stored in the config
directory of the plugin. Examples demonstrate how to retrieve configuration values from files like plugin.php
.
Overview
The most important class in WP Bones is the Plugin
class. This class is the main class that is responsible for the plugin initialization. It is the class that is responsible for registering the plugin, loading the plugin, and initializing the plugin.
Accessing the Plugin Class
You may access the Plugin class using the WPKirk()
helper function. The WPKirk()
helper function returns an instance of the Plugin
class.
$plugin = WPKirk();
The WPKirk()
helper function is a global which returns an instance of the Plugin
class. This function is used to access the plugin class from anywhere in the plugin. As you may already know, if your plugin is named MyAwesomePlugin
, then the helper function will be MyAwesomePlugin()
.
Properties
apps
/**
* Return the public apps URL
*
* @example http://example.com/wp-content/plugins/my-plugin/public/apps
*
* @return string
*/
This property provides the URL to the public apps directory of the plugin, which can be used to access application resources.
Example:
echo $plugin->apps; // Outputs the URL to the plugin's public apps directory
basePath
/**
* Return the filesystem path to the plugin
*
* @example /var/www/html/wp-content/plugins/my-plugin
*
* @return string
*/
This property provides the filesystem path to the plugin installation directory.
Example:
echo $plugin->basePath; // Outputs the filesystem path to the plugin
baseUri
/**
* Return the base URI of the plugin
*
* @example http://example.com/wp-content/plugins/my-plugin
*
* @return string
*/
This property provides the base URI of the plugin, which is used to construct URLs for accessing the plugin’s resources.
Example:
echo $plugin->baseUri; // Outputs the base URI of the plugin
css
/**
* Return the public css URL
*
* @example http://example.com/wp-content/plugins/my-plugin/public/css
*
* @return string
*/
This property provides the URL to the public CSS directory of the plugin, allowing stylesheets to be easily referenced.
Example:
echo $plugin->css; // Outputs the URL to the plugin's public CSS directory
file
/**
* Return the plugin file.
* This is an alias of `__FILE__`
*
* @example /var/www/html/wp-content/plugins/my-plugin/my-plugin.php
*
* @since 1.8.0
*
* @return string
*/
This property provides the path to the main plugin file, typically used for registering hooks and other plugin operations.
Example:
echo $plugin->file; // Outputs the path to the main plugin file
images
/**
* Return the public images URL
*
* @example http://example.com/wp-content/plugins/my-plugin/public/images
*
* @return string
*/
This property provides the URL to the public images directory of the plugin, facilitating easy access to image resources.
Example:
echo $plugin->images; // Outputs the URL to the plugin's public images directory
js
/**
* Return the public js URL
*
* @example http://example.com/wp-content/plugins/my-plugin/public/js
*
* @return string
*/
This property provides the URL to the public JavaScript directory of the plugin, allowing scripts to be easily referenced.
Example:
echo $plugin->js; // Outputs the URL to the plugin's public JavaScript directory
options
/**
* Magic method to get the options
*
* @return WordPressOption
*/
This property provides access to the WordPress options associated with the plugin, allowing for easy retrieval and manipulation of option values.
Example:
$options = $plugin->options; // Access the plugin's options
pluginBasename
/**
* Return the plugin basename
*
* @example my-plugin/my-plugin.php
*
* @return string
*/
This property provides the basename of the plugin, which is often used for identifying the plugin within WordPress.
Example:
echo $plugin->pluginBasename; // Outputs the plugin's basename
request
/**
* Magic method to get the request
*
* @return Request
*/
This property provides access to the HTTP request object, allowing the plugin to handle and respond to HTTP requests.
Example:
$request = $plugin->request; // Access the current HTTP request
slug
/**
* The slug of this plugin.
*
* @var string
*/
This property holds the slug of the plugin, which is typically a sanitized version of the plugin’s name. It is used to uniquely identify the plugin within WordPress.
Example:
echo $plugin->slug; // Outputs the slug of the plugin
Dynamic Properties
The Plugin
class has dynamic properties that are generated by the get_plugin_data()
function. These properties are generated from the main plugin file.
Name
string
Return Plugin Name
defined in the main plugin file.
PluginURI
string
Return Plugin URI
defined in the main plugin file.
Description
string
Return Description
defined in the main plugin file.
Version
string
Return Version
defined in the main plugin file.
Author
string
Return Author
defined in the main plugin file.
AuthorURI
string
Return Author URI
defined in the main plugin file.
TextDomain
string
Return Text Domain
defined in the main plugin file.
DomainPath
string
Return Domain Path
defined in the main plugin file.
Network
bool
Return Network
defined in the main plugin file.
RequiresWP
string
Return Requires at least
defined in the main plugin file.
RequiresPHP
string
Return Requires PHP
defined in the main plugin file.
UpdateURI
string
Return Update URI
defined in the main plugin file.
RequiresPlugins
string
Return Requires Plugins
defined in the main plugin file. Comma separated list of dot org plugin slugs.
Methods
config
/**
* Get / set the specified configuration value.
*
* If an array is passed as the key, we will assume you want to set an array of values.
*
* @param array|string $key The key of the configuration in dot notation.
* @param mixed $default Optional. Default value
*
* @return mixed
*/
public function config($key = null, $default = null)
This method retrieves or sets configuration values using dot notation for nested arrays. It loads configuration files based on the first part of the key.
Example:
$value = $plugin->config('plugin.some_setting', 'default_value');
Usage
You can use the config()
method to get or set the configuration value. The configuration values are stored in the config
directory of the plugin.
- menus.php
- plugin.php
…
For example if you want to get a configuration value from the plugin.php
file, you can use the following code:
$log = WPKirk()->config('plugin.log');
In the dot notation the first part is the file name and the second part is the key of the configuration.
If you have a custom.php
file in the config
directory, like this:
<?php
return [
'sample' => 'Hello, Captain!',
'nested' => [
'key' => 'value'
]
];
You can get the sample
value by using the following code:
$sample = WPKirk()->config('custom.sample');
You can also get the nested value by using the following code:
$nested = WPKirk()->config('custom.nested.key');
css
/**
* Helper method to load (enqueue) styles.
*
* For your convenience, the params $filename may be an array of file.
*
* @param string|array $filename Filename
* @param array $deps Optional. Dependencies array
* @param null $version Optional. Default plugin version
*/
public function css($filename, $deps = [], $version = null)
This method enqueues CSS files for the plugin, allowing multiple files to be specified at once.
Example:
$plugin->css(['style.css', 'theme.css']);
env
/**
* Gets the value of an environment variable. Supports boolean, empty and null.
*
* @param string $key The environment variable name.
* @param mixed $default Optional. Default null.
*
* @return mixed
*/
public function env($key, $default = null)
Retrieves the value of an environment variable, with support for default values if the variable is not set.
Example:
$dbHost = $plugin->env('DB_HOST', 'localhost');
getCallableHook
/**
* Utility method to get the callback for a route
*
* @param array $routes
* @return Closure|null
*/
public function getCallableHook($routes)
Determines the appropriate callback for a given route based on the HTTP request method and returns it as a closure.
Example:
$callback = $plugin->getCallableHook($routes);
getMenuUrl
/**
* Return the URL of a menu page
*
* @param string|int $menuSlug The slug of the menu. The array key used in the menu array.
*
* @return string
*/
public function getMenuUrl($menuSlug): string
Generates and returns the URL for a specific admin menu page based on its slug.
Example:
$url = $plugin->getMenuUrl('my_menu_slug');
getPageUrl
/**
* Return the URL of a custom page
*
* @param string $pageSlug The slug of the page
*
* @return string
*/
public function getPageUrl($pageSlug): string
Generates and returns the URL for a specific admin page based on its slug.
Example:
$url = $plugin->getPageUrl('my_page_slug');
isAjax
/**
* Return TRUE if an Ajax called
*
* @return bool
*/
public function isAjax(): bool
Checks if the current request is an AJAX request.
Example:
if ($plugin->isAjax()) {
// Handle AJAX request
}
js
/**
* Helper method to load (enqueue) styles.
*
* For your convenience, the params $filename may be an array of file.
*
* @param string|array $filename Filenames
* @param array $deps Optional. Dependencies array
* @param null $version Optional. Default plugin version
* @param bool $footer Optional. Load on footer. Default true
*/
public function js($filename, $deps = [], $version = null, $footer = true)
This method enqueues JavaScript files for the plugin, allowing multiple files to be specified at once.
Example:
$plugin->js(['script.js', 'theme.js']);
log
/**
* Return the Log provider
*
* @return mixed
*/
public function log()
Returns the log service provider instance, allowing logging operations within the plugin.
Example:
$log = $plugin->log();
$log->info('This is a log message.');
provider
/**
* Return a provider by name
*
* @param string $name The Class name of the provider.
*
* @return mixed|null
*/
public function provider($name)
Retrieves a registered service provider by its class name.
Example:
$provider = $plugin->provider('SomeServiceProvider');
vendor
/**
* Returns the absolute URL for the vendor directory.
*
* @param string $vendor Optional. Default 'wpbones'.
*
* @return string
*/
public function vendor($vendor = 'wpbones'): string
Returns the URL to the vendor directory, which can be customized by specifying a different vendor name.
Example:
$vendorUrl = $plugin->vendor();
view
/**
* Return an instance of View/Contract.
*
* @param null $key Optional. Default null.
* @param array $data Optional. Default null.
*
* @return View
*/
public function view($key = null, $data = []): View
Creates and returns a new view instance, which can be used to render templates with data.
Example:
$view = $plugin->view('template', ['key' => 'value']);
See the View Class documentation for more information.