Rumperuu/footnotes
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: update docblocks

Browse source
This commit is contained in:
Ben Goldsworthy 2021-04-29 20:57:30 +01:00
parent 418abc253b
commit bfeb11d5ad
11 changed files with 363 additions and 306 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
src/admin/layout/class-footnotes-layout-settings.php
View file

@ -1152,7 +1152,7 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* Edited: * Edited:
* @since 2.1.6 drop localized notices for CSS classes as the number increased to 16 * @since 2.1.6 drop localized notices for CSS classes as the number increased to 16
* list directly in the template, as CSS is in English anyway * list directly in the template, as CSS is in English anyway
* @see admin/partials/customize-css.html * @link ../partials/customize-css.html
* *
* @since 2.2.2 migrate Custom CSS to a dedicated tab * @since 2.2.2 migrate Custom CSS to a dedicated tab
* @since 2.3.0 say 'copy-paste' instead of 'cut and paste' since cutting is not needed * @since 2.3.0 say 'copy-paste' instead of 'cut and paste' since cutting is not needed

39
src/footnotes.php
View file

@ -7,11 +7,11 @@
* registers the activation and deactivation functions, and defines a function * registers the activation and deactivation functions, and defines a function
* that starts the plugin. * that starts the plugin.
* *
* @author Mark Cheret * @package footnotes
* @since 1.0.0 * @license GPL-3.0-only
* @package footnotes * @copyright 2021 Mark Cheret (email: mark@cheret.de)
* @copyright 2021 Mark Cheret (email: mark@cheret.de) *
* @license GPL-3.0-only * @since 1.0.0
* *
* @wordpress-plugin * @wordpress-plugin
* Plugin Name: footnotes * Plugin Name: footnotes
@ -34,24 +34,33 @@ if ( ! defined( 'WPINC' ) ) {
} }
/** /**
* Current plugin version. * The current plugin version.
*
* @link https://github.com/markcheret/footnotes/wiki/Versioning Versioning Guide
*
* @global string PLUGIN_VERSION
* *
* @since 2.1.4 * @since 2.1.4
*/ */
define( 'PLUGIN_VERSION', '2.8.0d' ); define( 'PLUGIN_VERSION', '2.8.0d' );
/** /**
* Defines the current environment ('development' or 'production'). * The current environment ('development' or 'production').
* *
* This primarily affects whether minified or unminified files are requested. * This primarily affects whether minified or unminified files are requested.
* *
* @global bool PRODUCTION_ENV
*
* @since 2.5.5 * @since 2.5.5
*/ */
define( 'PRODUCTION_ENV', false ); define( 'PRODUCTION_ENV', false );
/** /**
* The code that runs during plugin activation. * Triggers during plugin activation.
* This action is documented in includes/class-plugin-name-activator.php *
* @uses Footnotes_Activator::activate() Method called on plugin activation.
*
* @since 2.8.0
*/ */
function activate_footnotes() { function activate_footnotes() {
require_once plugin_dir_path( __FILE__ ) . 'includes/class-footnotes-activator.php'; require_once plugin_dir_path( __FILE__ ) . 'includes/class-footnotes-activator.php';
@ -59,8 +68,11 @@ function activate_footnotes() {
} }
/** /**
* The code that runs during plugin deactivation. * Triggers during plugin deactivation.
* This action is documented in includes/class-plugin-name-deactivator.php *
* @uses Footnotes_Deactivator::deactivate() Method called on plugin deactivation.
*
* @since 2.8.0
*/ */
function deactivate_plugin_name() { function deactivate_plugin_name() {
require_once plugin_dir_path( __FILE__ ) . 'includes/class-footnotes-deactivator.php'; require_once plugin_dir_path( __FILE__ ) . 'includes/class-footnotes-deactivator.php';
@ -79,9 +91,8 @@ require plugin_dir_path( __FILE__ ) . 'includes/class-footnotes.php';
/** /**
* Begins execution of the plugin. * Begins execution of the plugin.
* *
* Since everything within the plugin is registered via hooks, * Since everything within the plugin is registered via hooks, then kicking off
* then kicking off the plugin from this point in the file does * the plugin from this point in the file does not affect the page life cycle.
* not affect the page life cycle.
* *
* @since 2.8.0 * @since 2.8.0
*/ */

21
src/includes/class-footnotes-activator.php
View file

@ -1,30 +1,31 @@
<?php <?php
/** /**
* Fired during plugin activation * File providing `Footnotes_Activator` class.
* *
* @since 2.8.0 * @package footnotes
* @subpackage includes
* *
* @package footnotes * @since 2.8.0
* @subpackage includes
*/ */
/** /**
* Fired during plugin activation. * Class providing action(s) on plugin activation.
* *
* This class defines all code necessary to run during the plugin's activation. * This class defines all code necessary to run during the plugin's activation.
* *
* @since 2.8.0 * @package footnotes
* @package footnotes * @subpackage includes
* @subpackage includes *
* @since 2.8.0
*/ */
class Footnotes_Activator { class Footnotes_Activator {
/** /**
* Runs when the Plugin is deactivated. * Runs when the plugin is deactivated.
* *
* Currently NOP. * Currently NOP.
* *
* @since 2.8.0 * @since 2.8.0
*/ */
public static function activate() { public static function activate() {
// Nothing yet. // Nothing yet.

71
src/includes/class-footnotes-config.php
View file

@ -1,65 +1,84 @@
<?php <?php
/** /**
* Includes the Plugin Constants class to load all Plugin constant vars like Plugin name, etc. * File providing the `Footnotes_Config` class.
* *
* @since 1.5.0 * @package footnotes
* @since 2.0.4 add Public Plugin name for dashboard heading * @subpackage includes
* *
* @package footnotes * @since 1.5.0
* @subpackage includes * @since 2.8.0 Rename file from `config.php` to `class-footnotes-config.php`.
* @todo Remove.
* @deprecated
*/ */
/** /**
* Contains all Plugin Constants. Contains no Method or Property. * Class defining plugin constants.
* *
* @since 1.5.0 * This class contains no methods of properties.
*
* @since 1.5.0
* @todo Remove.
* @deprecated
*/ */
class Footnotes_Config { class Footnotes_Config {
/** /**
* Public Plugin name. * Public plugin name.
* *
* @since 1.5.0
* @var string * @var string
* *
* edited classes for v2.0.4 * @since 1.5.0
* @todo Remove.
* @deprecated
*/ */
const C_STR_PLUGIN_PUBLIC_NAME = '<span class="footnotes_logo footnotes_logo_part1">foot</span><span class="footnotes_logo footnotes_logo_part2">notes</span>'; const C_STR_PLUGIN_PUBLIC_NAME = '<span class="footnotes_logo footnotes_logo_part1">foot</span><span class="footnotes_logo footnotes_logo_part2">notes</span>';
/** /**
* Public Plugin name for dashboard heading * Public plugin name for use as a dashboard heading.
* *
* After properly displaying in dashboard headings until WPv5.4, the above started * After properly displaying in dashboard headings until WPv5.4, the above started
* in WPv5.5 being torn apart as if the headline was text-align:justify and not * in WP 5.5 being torn apart as if the headline was `text-align:justify` and not
* the last line. That ugly display bug badly affected the plugin’s communication. * the last line. That ugly display bug badly affected the plugin's communication.
* The only working solution found so far is using position:fixed in one heading * The only working solution found so far is using `position:fixed` in one heading
* that isn’t translated, and dropping the logo in another, translatable heading. * that isn't translated, and dropping the logo in another, translatable heading.
* *
* @since 2.0.4 * @var string
* @var string *
* @since 2.0.4
* @todo Remove.
* @deprecated
*/ */
const C_STR_PLUGIN_HEADING_NAME = '<span class="footnotes_logo_heading footnotes_logo_part1_heading">foot</span><span class="footnotes_logo_heading footnotes_logo_part2_heading">notes</span>'; const C_STR_PLUGIN_HEADING_NAME = '<span class="footnotes_logo_heading footnotes_logo_part1_heading">foot</span><span class="footnotes_logo_heading footnotes_logo_part2_heading">notes</span>';
/** /**
* Html tag for the LOVE symbol. * HTML element for the ‘love’ symbol.
* *
* @since 1.5.0 * @var string
* @var string *
* @since 1.5.0
* @todo Remove.
* @deprecated
*/ */
const C_STR_LOVE_SYMBOL = '<span style="color:#ff6d3b; font-weight:bold;">&hearts;</span>'; const C_STR_LOVE_SYMBOL = '<span style="color:#ff6d3b; font-weight:bold;">&hearts;</span>';
/** /**
* HTML code for the 'love' symbol used in dashboard heading * HTML element for the ‘love’ symbol used in dashboard heading
* *
* @since 2.0.4 * @var string
* @var string *
* @since 2.0.4
* @todo Remove.
* @deprecated
*/ */
const C_STR_LOVE_SYMBOL_HEADING = '<span class="footnotes_heart_heading">&hearts;</span>'; const C_STR_LOVE_SYMBOL_HEADING = '<span class="footnotes_heart_heading">&hearts;</span>';
/** /**
* Short code to DON'T display the 'LOVE ME' slug on certain pages. * Shortcode to NOT display the ‘LOVE ME’ slug on certain pages.
* *
* @since 1.5.0 * @var string
* @var string *
* @since 1.5.0
* @todo Remove.
* @deprecated
*/ */
const C_STR_NO_LOVE_SLUG = '[[no footnotes: love]]'; const C_STR_NO_LOVE_SLUG = '[[no footnotes: love]]';
} }

92
src/includes/class-footnotes-convert.php
View file

@ -1,31 +1,29 @@
<?php <?php
/** /**
* Includes the Convert Class. * File providing core `Footnotes_Convert` class.
* *
* @since 1.5.0 * @package footnotes
* @since 2.2.0 add lowercase Roman * @subpackage includes
* *
* @package footnotes * @since 1.5.0
* @subpackage includes * @since 2.8.0 Rename file from `convert.php` to `class-footnotes-convert.php`.
*/ */
/** /**
* Converts data types and Footnotes specific values. * Class providing variable type and value conversion functions.
* *
* @since 1.5.0 * @since 1.5.0
*/ */
class Footnotes_Convert { class Footnotes_Convert {
/** /**
* Converts a integer into the user-defined counter style for the footnotes. * Converts an integer into the user-defined counter style for the footnotes.
* *
* @since 1.5.0 * @param int $p_int_index Index to be converted.
* @param int $p_int_index Index to be converted. * @param string $p_str_convert_style Counter style to use.
* @param string $p_str_convert_style Style of the new/converted Index. * @return string Converted Index converted to the defined counter style.
* @return string Converted Index as string in the defined counter style.
* *
* Edited: * @since 1.5.0
* @since 2.2.0 lowercase Roman numerals supported
*/ */
public static function index( $p_int_index, $p_str_convert_style = 'arabic_plain' ) { public static function index( $p_int_index, $p_str_convert_style = 'arabic_plain' ) {
switch ( $p_str_convert_style ) { switch ( $p_str_convert_style ) {
@ -46,13 +44,17 @@ class Footnotes_Convert {
} }
/** /**
* Converts an integer into latin ascii characters, either lower or upper-case. * Converts an integer into Latin ASCII characters, either lower or upper-case.
* Function available from A to ZZ ( means 676 footnotes at 1 page possible).
* *
* @since 1.0-gamma * This function works from values A–ZZ (meaning there is a limit of 676
* @param int $p_int_value Value/Index to be converted. * gootnotes per Page).
* @param bool $p_bool_upper_case True to convert the value to upper case letter, otherwise to lower case. *
* @return string * @param int $p_int_value Value to be converted.
* @param bool $p_bool_upper_case Whether to convert the value to upper-case.
* @return string
*
* @since 1.0-gamma
* @todo Replace with built-in char casting.
*/ */
private static function to_latin( $p_int_value, $p_bool_upper_case ) { private static function to_latin( $p_int_value, $p_bool_upper_case ) {
// Output string. // Output string.
@ -80,9 +82,11 @@ class Footnotes_Convert {
/** /**
* Converts an integer to a leading-0 integer. * Converts an integer to a leading-0 integer.
* *
* @since 1.0-gamma * @param int $p_int_value Value to be converted.
* @param int $p_int_value Value/Index to be converted. * @return string Value with a leading zero.
* @return string Value with a leading zero. *
* @since 1.0-gamma
* @todo Replace with built-in string formatting.
*/ */
private static function to_arabic_leading( $p_int_value ) { private static function to_arabic_leading( $p_int_value ) {
// Add a leading 0 if number lower then 10. // Add a leading 0 if number lower then 10.
@ -93,15 +97,13 @@ class Footnotes_Convert {
} }
/** /**
* Converts an integer to a romanic letter. * Converts an integer to a Roman numeral.
* *
* @since 1.0-gamma * @param int $p_int_value Value to be converted.
* @param int $p_int_value Value/Index to be converted. * @param bool $p_bool_upper_case Whether to convert the value to upper-case.
* @param bool $p_bool_upper_case Whether to uppercase. * @return string
* @return string
* *
* Edited: * @since 1.0-gamma
* @since 2.2.0 optionally lowercase (code from Latin)
*/ */
private static function to_romanic( $p_int_value, $p_bool_upper_case ) { private static function to_romanic( $p_int_value, $p_bool_upper_case ) {
// Table containing all necessary romanic letters. // Table containing all necessary romanic letters.
@ -142,9 +144,11 @@ class Footnotes_Convert {
/** /**
* Converts a string depending on its value to a boolean. * Converts a string depending on its value to a boolean.
* *
* @since 1.0-beta * @param string $p_str_value String to be converted to boolean.
* @param string $p_str_value String to be converted to boolean. * @return bool Boolean value represented by the string.
* @return bool Boolean representing the string. *
* @since 1.0-beta
* @todo Replace with built-in type casting.
*/ */
public static function to_bool( $p_str_value ) { public static function to_bool( $p_str_value ) {
// Convert string to lower-case to make it easier. // Convert string to lower-case to make it easier.
@ -163,11 +167,13 @@ class Footnotes_Convert {
} }
/** /**
* Get a html Array short code depending on Arrow-Array key index. * Get an HTML array short code depending on Arrow-Array key index.
* *
* @since 1.3.2 * @param int $p_int_index Index representing the arrow. If empty, all arrows are specified.
* @param int $p_int_index Index representing the Arrow. If empty all Arrows are specified. * @return array|string Array of all arrows if index is empty, otherwise HTML tag of a specific arrow.
* @return array|string Array of all Arrows if Index is empty otherwise html tag of a specific arrow. *
* @since 1.3.2
* @todo Review.
*/ */
public static function get_arrow( $p_int_index = -1 ) { public static function get_arrow( $p_int_index = -1 ) {
// Define all possible arrows. // Define all possible arrows.
@ -184,14 +190,14 @@ class Footnotes_Convert {
return $l_arr_arrows[ $p_int_index ]; return $l_arr_arrows[ $p_int_index ];
} }
// phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_var_dump // phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_var_dump, WordPress.PHP.DevelopmentFunctions.error_log_print_r
// phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_print_r
/** /**
* Displays a Variable. * Displays a variable.
* *
* @since 1.5.0 * @param mixed $p_mixed_value The variable to display.
* @param mixed $p_mixed_value The variable to display. *
* @return void * @since 1.5.0
* @todo Replace with proper logging/debug functions.
*/ */
public static function debug( $p_mixed_value ) { public static function debug( $p_mixed_value ) {
if ( empty( $p_mixed_value ) ) { if ( empty( $p_mixed_value ) ) {
@ -218,5 +224,5 @@ class Footnotes_Convert {
} }
echo '<br/>'; echo '<br/>';
} }
// phpcs:disable // phpcs:enable WordPress.PHP.DevelopmentFunctions.error_log_var_dump, WordPress.PHP.DevelopmentFunctions.error_log_print_r
} }

21
src/includes/class-footnotes-deactivator.php
View file

@ -1,30 +1,31 @@
<?php <?php
/** /**
* Fired during plugin deactivation. * File providing `Footnotes_Deactivator` class.
* *
* @since 2.8.0 * @package footnotes
*
* @package footnotes
* @subpackage includes * @subpackage includes
*
* @since 2.8.0
*/ */
/** /**
* Fired during plugin deactivation. * Class providing action(s) on plugin deactivation.
* *
* This class defines all code necessary to run during the plugin's deactivation. * This class defines all code necessary to run during the plugin's deactivation.
* *
* @since 2.8.0 * @package footnotes
* @package footnotes * @subpackage includes
* @subpackage includes *
* @since 2.8.0
*/ */
class Footnotes_Deactivator { class Footnotes_Deactivator {
/** /**
* Runs when the Plugin is deactivated. * Runs when the plugin is deactivated.
* *
* Currently NOP. * Currently NOP.
* *
* @since 2.8.0 * @since 2.8.0
*/ */
public static function deactivate() { public static function deactivate() {
// Nothing yet. // Nothing yet.

34
src/includes/class-footnotes-i18n.php
View file

@ -1,37 +1,37 @@
<?php // phpcs:disable PEAR.NamingConventions.ValidClassName.Invalid <?php // phpcs:disable PEAR.NamingConventions.ValidClassName.Invalid
/** /**
* Define the internationalization functionality * File providing core `Footnotes_i18n` class.
* *
* Loads and defines the internationalization files for this plugin * @package footnotes
* so that it is ready for translation. * @subpackage includes
* *
* @since 1.5.0 * @since 1.5.0
* @since 2.8.0 Renamed class to `Footnotes_i18n`. * @since 2.8.0 Rename file from `language.php` to `class-footnotes-i18n.php`.
*
* @package footnotes
* @subpackage includes
*/ */
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-config.php'; require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-config.php';
/** /**
* Define the internationalization functionality. * Class providing internationalization functionality.
* *
* Loads and defines the internationalization files for this plugin * Loads and defines the internationalization files for this plugin so that it
* so that it is ready for translation. * is ready for translation.
* *
* @since 1.5.0 * @link https://translate.wordpress.org/projects/wp-plugins/footnotes/ GlotPress listing
* @since 2.8.0 Renamed class to `Footnotes_i18n`. *
* @package footnotes * @package footnotes
* @subpackage includes * @subpackage includes
*
* @since 1.5.0
* @since 2.8.0 Rename class from `Footnotes_Language` to `Footnotes_i18n`.
*/ */
class Footnotes_i18n { class Footnotes_i18n {
/** /**
* Load the plugin text domain for translation. * Load the plugin text domain for translation.
* *
* @since 1.5.1 * @since 1.5.1
* @since 2.8.0 Rename from `load()` to `load_plugin_textdomain()`. Remove unused `$p_str_language_code` parameter. * @since 2.8.0 Rename from `load()` to `load_plugin_textdomain()`. Remove unused `$p_str_language_code` parameter.
*/ */
public function load_plugin_textdomain() { public function load_plugin_textdomain() {
load_plugin_textdomain( load_plugin_textdomain(

87
src/includes/class-footnotes-loader.php
View file

@ -1,46 +1,50 @@
<?php <?php
/** /**
* Register all actions and filters for the plugin. * File providing the `Footnotes_Loader` class.
* *
* @since 2.8.0 * @package footnotes
* @subpackage includes
* *
* @package footnotes * @since 2.8.0
* @subpackage includes
*/ */
/** /**
* Register all actions and filters for the plugin. * Class defining action/filter registration for the plugin.
* *
* Maintain a list of all hooks that are registered throughout * Maintain a list of all hooks that are registered throughout the plugin, and
* the plugin, and register them with the WordPress API. Call the * register them with the WordPress API. Call the run function to execute the
* run function to execute the list of actions and filters. * list of actions and filters.
* *
* @package footnotes * @package footnotes
* @subpackage includes * @subpackage includes
*
* @since 2.8.0
*/ */
class Footnotes_Loader { class Footnotes_Loader {
/** /**
* The array of actions registered with WordPress. * The array of actions registered with WordPress.
* *
* @since 2.8.0 * @access protected
* @access protected * @var array $actions The actions registered with WordPress to fire when the plugin loads.
* @var array $actions The actions registered with WordPress to fire when the plugin loads. *
* @since 2.8.0
*/ */
protected $actions; protected $actions;
/** /**
* The array of filters registered with WordPress. * The array of filters registered with WordPress.
* *
* @since 2.8.0 * @access protected
* @access protected * @var array $filters The filters registered with WordPress to fire when the plugin loads.
* @var array $filters The filters registered with WordPress to fire when the plugin loads. *
* @since 2.8.0
*/ */
protected $filters; protected $filters;
/** /**
* Initialize the collections used to maintain the actions and filters. * Initialize the collections used to maintain the actions and filters.
* *
* @since 2.8.0 * @since 2.8.0
*/ */
public function __construct() { public function __construct() {
@ -52,12 +56,13 @@ class Footnotes_Loader {
/** /**
* Add a new action to the collection to be registered with WordPress. * Add a new action to the collection to be registered with WordPress.
* *
* @since 2.8.0 * @param string $hook The name of the WordPress action that is being registered.
* @param string $hook The name of the WordPress action that is being registered. * @param object $component A reference to the instance of the object on which the action is defined.
* @param object $component A reference to the instance of the object on which the action is defined. * @param string $callback The name of the function definition on the `$component`.
* @param string $callback The name of the function definition on the $component. * @param int $priority (optional) The priority at which the function should be fired. Default is 10.
* @param int $priority Optional. The priority at which the function should be fired. Default is 10. * @param int $accepted_args (optional) The number of arguments that should be passed to the $callback. Default is 1.
* @param int $accepted_args Optional. The number of arguments that should be passed to the $callback. Default is 1. *
* @since 2.8.0
*/ */
public function add_action( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) { public function add_action( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
$this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority, $accepted_args ); $this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority, $accepted_args );
@ -66,12 +71,13 @@ class Footnotes_Loader {
/** /**
* Add a new filter to the collection to be registered with WordPress. * Add a new filter to the collection to be registered with WordPress.
* *
* @since 2.8.0 * @param string $hook The name of the WordPress filter that is being registered.
* @param string $hook The name of the WordPress filter that is being registered. * @param object $component A reference to the instance of the object on which the filter is defined.
* @param object $component A reference to the instance of the object on which the filter is defined. * @param string $callback The name of the function definition on the `$component`.
* @param string $callback The name of the function definition on the $component. * @param int $priority (optional) The priority at which the function should be fired. Default is 10.
* @param int $priority Optional. The priority at which the function should be fired. Default is 10. * @param int $accepted_args (optional) The number of arguments that should be passed to the $callback. Default is 1.
* @param int $accepted_args Optional. The number of arguments that should be passed to the $callback. Default is 1. *
* @since 2.8.0
*/ */
public function add_filter( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) { public function add_filter( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
$this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority, $accepted_args ); $this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority, $accepted_args );
@ -81,15 +87,16 @@ class Footnotes_Loader {
* A utility function that is used to register the actions and hooks into a single * A utility function that is used to register the actions and hooks into a single
* collection. * collection.
* *
* @since 2.8.0 * @access private
* @access private * @param array $hooks The collection of hooks that is being registered (that is, actions or filters).
* @param array $hooks The collection of hooks that is being registered (that is, actions or filters). * @param string $hook The name of the WordPress filter that is being registered.
* @param string $hook The name of the WordPress filter that is being registered. * @param object $component A reference to the instance of the object on which the filter is defined.
* @param object $component A reference to the instance of the object on which the filter is defined. * @param string $callback The name of the function definition on the `$component`.
* @param string $callback The name of the function definition on the $component. * @param int $priority The priority at which the function should be fired.
* @param int $priority The priority at which the function should be fired. * @param int $accepted_args The number of arguments that should be passed to the `$callback`.
* @param int $accepted_args The number of arguments that should be passed to the $callback. * @return array The collection of actions and filters registered with WordPress.
* @return array The collection of actions and filters registered with WordPress. *
* @since 2.8.0
*/ */
private function add( $hooks, $hook, $component, $callback, $priority, $accepted_args ) { private function add( $hooks, $hook, $component, $callback, $priority, $accepted_args ) {
@ -106,9 +113,9 @@ class Footnotes_Loader {
} }
/** /**
* Register the filters and actions with WordPress. * Registers the filters and actions with WordPress.
* *
* @since 2.8.0 * @since 2.8.0
*/ */
public function run() { public function run() {

67
src/includes/class-footnotes-settings.php
View file

@ -4,96 +4,103 @@
* *
* The constants are ordered by ascending version so their docblocks can replace most of this list. * The constants are ordered by ascending version so their docblocks can replace most of this list.
* *
* @since 1.5.0 * @package footnotes
* @since 2.0.0 Update: **symbol for backlinks** removed; hyperlink moved to the reference number. * @subpackage includes
* @since 2.0.4 Update: Restore arrow settings to customize or disable the now prepended arrow symbol, thanks to @mmallett issue report.
* @since 2.0.7 BUGFIX: Hooks: Default-disable 'the_post', thanks to @spaceling @markcheret @nyamachi @whichgodsaves @spiralofhope2 @mmallett @andreasra @widecast @ymorin007 @tashi1es bug reports.
* @since 2.1.3 Bugfix: Hooks: disable the_excerpt hook by default to fix issues, thanks to @nikelaos bug report.
* *
* @package footnotes * @since 1.5.0
* @subpackage includes * @since 2.8.0 Rename file from `settings.php` to `class-footnotes-settings.php`.
*/ */
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-convert.php'; require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-convert.php';
/** /**
* Loads the settings values, sets to default values if undefined. * Class defining configurable plugin settings.
* *
* @since 1.5.0 * @since 1.5.0
*/ */
class Footnotes_Settings { class Footnotes_Settings {
/** /**
* Settings container key for the label of the reference container. * Settings container key for the label of the reference container.
* *
* @since 1.5.0 * @var str
* @var str *
* @since 1.5.0
*/ */
const C_STR_REFERENCE_CONTAINER_NAME = 'footnote_inputfield_references_label'; const C_STR_REFERENCE_CONTAINER_NAME = 'footnote_inputfield_references_label';
/** /**
* Settings container key to collapse the reference container by default. * Settings container key to collapse the reference container by default.
* *
* @since 1.5.0
* @var str
* The string is converted to Boolean false if 'no', true if 'yes'. * The string is converted to Boolean false if 'no', true if 'yes'.
* @see Footnotes_Convert::to_bool() *
* @var str
*
* @since 1.5.0
* @todo Refactor to use sane typing.
*/ */
const C_STR_REFERENCE_CONTAINER_COLLAPSE = 'footnote_inputfield_collapse_references'; const C_STR_REFERENCE_CONTAINER_COLLAPSE = 'footnote_inputfield_collapse_references';
/** /**
* Settings container key for the position of the reference container. * Settings container key for the position of the reference container.
* *
* @since 1.5.0 * @var str
* @var str *
* @since 1.5.0
*/ */
const C_STR_REFERENCE_CONTAINER_POSITION = 'footnote_inputfield_reference_container_place'; const C_STR_REFERENCE_CONTAINER_POSITION = 'footnote_inputfield_reference_container_place';
/** /**
* Settings container key for combining identical footnotes. * Settings container key for combining identical footnotes.
* *
* @since 1.5.0 * @var str
* @var str *
* @since 1.5.0
*/ */
const C_STR_COMBINE_IDENTICAL_FOOTNOTES = 'footnote_inputfield_combine_identical'; const C_STR_COMBINE_IDENTICAL_FOOTNOTES = 'footnote_inputfield_combine_identical';
/** /**
* Settings container key for the short code of the footnote’s start. * Settings container key for the short code of the footnote's start.
* *
* @since 1.5.0 * @var str
* @var str *
* @since 1.5.0
*/ */
const C_STR_FOOTNOTES_SHORT_CODE_START = 'footnote_inputfield_placeholder_start'; const C_STR_FOOTNOTES_SHORT_CODE_START = 'footnote_inputfield_placeholder_start';
/** /**
* Settings container key for the short code of the footnote’s end. * Settings container key for the short code of the footnote's end.
* *
* @since 1.5.0 * @var str
* @var str *
* @since 1.5.0
*/ */
const C_STR_FOOTNOTES_SHORT_CODE_END = 'footnote_inputfield_placeholder_end'; const C_STR_FOOTNOTES_SHORT_CODE_END = 'footnote_inputfield_placeholder_end';
/** /**
* Settings container key for the user-defined short code of the footnotes start. * Settings container key for the user-defined short code of the footnotes start.
* *
* @since 1.5.0 * @var str
* @var str *
* @since 1.5.0
*/ */
const C_STR_FOOTNOTES_SHORT_CODE_START_USER_DEFINED = 'footnote_inputfield_placeholder_start_user_defined'; const C_STR_FOOTNOTES_SHORT_CODE_START_USER_DEFINED = 'footnote_inputfield_placeholder_start_user_defined';
/** /**
* Settings container key for the user-defined short code of the footnotes end. * Settings container key for the user-defined short code of the footnotes end.
* *
* @since 1.5.0 * @var str
* @var str *
* @since 1.5.0
*/ */
const C_STR_FOOTNOTES_SHORT_CODE_END_USER_DEFINED = 'footnote_inputfield_placeholder_end_user_defined'; const C_STR_FOOTNOTES_SHORT_CODE_END_USER_DEFINED = 'footnote_inputfield_placeholder_end_user_defined';
/** /**
* Settings container key for the counter style of the footnotes. * Settings container key for the counter style of the footnotes.
* *
* @since 1.5.0 * @var str
* @var str *
* @since 1.5.0
*/ */
const C_STR_FOOTNOTES_COUNTER_STYLE = 'footnote_inputfield_counter_style'; const C_STR_FOOTNOTES_COUNTER_STYLE = 'footnote_inputfield_counter_style';

109
src/includes/class-footnotes-template.php
View file

@ -1,78 +1,84 @@
<?php <?php
/** /**
* Includes the Template Engine to load and handle all Template files of the Plugin. * File providing the `Footnotes_Template` class.
* *
* @since 1.5.0
* @since 2.2.6 Adding: Templates: support for custom templates in sibling folder, thanks to @misfist issue report.
* @since 2.5.0 Adding: Templates: Enable template location stack, thanks to @misfist issue report and code contribution.
* *
* @package footnotes * @package footnotes
* @subpackage includes * @subpackage includes
*
* @since 1.5.0
* @since 2.2.6 Add support for custom templates in sibling folder.
* @since 2.8.0 Rename file from `templates.php` to `class-footnotes-templates.php`.
*/ */
/** /**
* Handles each Template file for the Plugin Frontend (e.g. Settings Dashboard, Public pages, ...). * Class defining template rendering.
* Loads a template file, replaces all Placeholders and returns the replaced file content.
* *
* @since 1.5.0 * Loads a template file, replaces all Placeholders and returns the replaced
* file content.
* @package footnotes
* @subpackage includes
*
* @since 1.5.0
* @todo Refactor templating.
*/ */
class Footnotes_Template { class Footnotes_Template {
/** /**
* Directory name for dashboard partials. * Directory name for dashboard partials.
* *
* @since 1.5.0
* @var string * @var string
*
* @since 1.5.0
*/ */
const C_STR_DASHBOARD = 'admin/partials'; const C_STR_DASHBOARD = 'admin/partials';
/** /**
* Directory name for public partials. * Directory name for public partials.
* *
* @since 1.5.0
* @var string * @var string
*
* @since 1.5.0
*/ */
const C_STR_PUBLIC = 'public/partials'; const C_STR_PUBLIC = 'public/partials';
/** /**
* Contains the content of the template after initialize. * Contains the content of the template after initialize.
* *
* @since 1.5.0
* @var string * @var string
*
* @since 1.5.0
*/ */
private $a_str_original_content = ''; private $a_str_original_content = '';
/** /**
* Contains the content of the template after initialize with replaced place holders. * Contains the content of the template after initialize with replaced place holders.
* *
* @since 1.5.0
* @var string * @var string
*
* @since 1.5.0
*/ */
private $a_str_replaced_content = ''; private $a_str_replaced_content = '';
/** /**
* Plugin Directory * Plugin Directory
* *
* @since 2.4.0d3 * @var string
* *
* @var string * @since 2.4.0d3
*/ */
public $plugin_directory; public $plugin_directory;
/** /**
* Class Constructor. Reads and loads the template file without replace any placeholder. * Class Constructor. Reads and loads the template file without replace any placeholder.
* *
* @since 1.5.0 * @param string $p_str_file_type Template file type.
* @param string $p_str_file_type Template file type (take a look on the Class constants). * @param string $p_str_file_name Template file name inside the `partials/` directory, without the file extension.
* @param string $p_str_file_name Template file name inside the Template directory without the file extension. * @param string $p_str_extension (optional) Template file extension (default: 'html').
* @param string $p_str_extension Optional Template file extension (default: html).
* *
* - Adding: Templates: support for custom templates in sibling folder, thanks to @misfist issue report. * @since 1.5.0
* * @todo Refactor templating.
* @since 2.2.6
*
* @reporter @misfist
* @link https://wordpress.org/support/topic/template-override-filter/
*/ */
public function __construct( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) { public function __construct( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) {
// No template file type and/or file name set. // No template file type and/or file name set.
@ -80,18 +86,8 @@ class Footnotes_Template {
return; return;
} }
/**
* Define plugin root path.
*
* @since 2.4.0d3
*/
$this->plugin_directory = plugin_dir_path( dirname( __FILE__ ) ); $this->plugin_directory = plugin_dir_path( dirname( __FILE__ ) );
/**
* Modularize functions.
*
* @since 2.4.0d3
*/
$template = $this->get_template( $p_str_file_type, $p_str_file_name, $p_str_extension ); $template = $this->get_template( $p_str_file_type, $p_str_file_name, $p_str_extension );
if ( $template ) { if ( $template ) {
$this->process_template( $template ); $this->process_template( $template );
@ -104,9 +100,11 @@ class Footnotes_Template {
/** /**
* Replace all placeholders specified in array. * Replace all placeholders specified in array.
* *
* @param array $p_arr_placeholders Placeholders (key = placeholder, value = value).
* @return bool `true` on Success, `false` if placeholders invalid.
*
* @since 1.5.0 * @since 1.5.0
* @param array $p_arr_placeholders Placeholders (key = placeholder, value = value). * @todo Refactor templating.
* @return bool True on Success, False if Placeholders invalid.
*/ */
public function replace( $p_arr_placeholders ) { public function replace( $p_arr_placeholders ) {
// No placeholders set. // No placeholders set.
@ -129,6 +127,7 @@ class Footnotes_Template {
* Reloads the original content of the template file. * Reloads the original content of the template file.
* *
* @since 1.5.0 * @since 1.5.0
* @todo Refactor templating.
*/ */
public function reload() { public function reload() {
$this->a_str_replaced_content = $this->a_str_original_content; $this->a_str_replaced_content = $this->a_str_original_content;
@ -137,8 +136,10 @@ class Footnotes_Template {
/** /**
* Returns the content of the template file with replaced placeholders. * Returns the content of the template file with replaced placeholders.
* *
* @return string Template content with replaced placeholders.
*
* @since 1.5.0 * @since 1.5.0
* @return string Template content with replaced placeholders. * @todo Refactor templating.
*/ */
public function get_content() { public function get_content() {
return $this->a_str_replaced_content; return $this->a_str_replaced_content;
@ -147,16 +148,11 @@ class Footnotes_Template {
/** /**
* Process template file. * Process template file.
* *
* @since 2.4.0d3 * @param string $template The template to be processed.
* @return void
* *
* @param string $template The template to be processed. * @since 2.4.0d3
* @return void * @todo Refactor templating.
*
* @since 2.0.3 Replace tab with a space.
* @since 2.0.3 Replace 2 spaces with 1.
* @since 2.0.4 Collapse multiple spaces.
* @since 2.2.6 Delete a space before a closing pointy bracket.
* @since 2.5.4 Collapse HTML comments and PHP/JS docblocks (only).
*/ */
public function process_template( $template ) { public function process_template( $template ) {
// phpcs:disable WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents // phpcs:disable WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
@ -174,18 +170,13 @@ class Footnotes_Template {
/** /**
* Get the template. * Get the template.
* *
* - Adding: Templates: Enable template location stack, thanks to @misfist issue report and code contribution. * @param string $p_str_file_type The file type of the template.
* @param string $p_str_file_name The file name of the template.
* @param string $p_str_extension The file extension of the template.
* @return mixed `false` or the template path
* *
* @since 2.4.0d3 Contribution. * @since 2.5.0
* @since 2.5.0 Release. * @todo Refactor templating.
*
* @contributor @misfist
* @link https://wordpress.org/support/topic/template-override-filter/#post-13864301
*
* @param string $p_str_file_type The file type of the template.
* @param string $p_str_file_name The file name of the template.
* @param string $p_str_extension The file extension of the template.
* @return mixed false | template path
*/ */
public function get_template( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) { public function get_template( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) {
$located = false; $located = false;
@ -197,6 +188,8 @@ class Footnotes_Template {
* add_filter( 'footnotes_template_directory', function( $directory ) { * add_filter( 'footnotes_template_directory', function( $directory ) {
* return 'template_parts/footnotes/'; * return 'template_parts/footnotes/';
* } ); * } );
*
* @todo Review.
*/ */
$template_directory = apply_filters( '', 'footnotes/' ); $template_directory = apply_filters( '', 'footnotes/' );
$custom_directory = apply_filters( 'footnotes_custom_template_directory', 'footnotes-custom/' ); $custom_directory = apply_filters( 'footnotes_custom_template_directory', 'footnotes-custom/' );

122
src/includes/class-footnotes.php
View file

@ -1,66 +1,69 @@
<?php // phpcs:disable PEAR.Commenting.FileComment.Missing <?php // phpcs:disable PEAR.Commenting.FileComment.Missing
/** /**
* The file that defines the core plugin class * File providing core `Footnotes` class.
* *
* A class definition that includes attributes and functions used across both the * A class definition that includes attributes and functions used across both the
* public-facing side of the site and the admin area. * public-facing side of the site and the admin area.
* *
* @since 1.5.0 * @package footnotes
*
* @package footnotes
* @subpackage includes * @subpackage includes
*
* @since 1.5.0
* @since 2.8.0 Rename file from `init.php` to `class-footnotes.php`.
*/ */
/** /**
* The core plugin class. * Class providing core plugin functionality.
* *
* This is used to define internationalization, admin-specific hooks, and * This is used to define internationalization, admin-specific hooks, and
* public-facing site hooks. * public-facing site hooks.
*
* Also maintains the unique identifier of this plugin as well as the current * @package footnotes
* version of the plugin.
*
* @since 1.5.0
* @package footnotes
* @subpackage includes * @subpackage includes
*
* @since 1.5.0
* @since 2.8.0
*/ */
class Footnotes { class Footnotes {
/** /**
* The loader that's responsible for maintaining and registering all hooks that power * The loader that's responsible for maintaining and registering all hooks that power
* the plugin. * the plugin.
* *
* @since 2.8.0 * @access protected
* @access protected * @var Footnotes_Loader $loader Maintains and registers all hooks for the plugin.
* @var Footnotes_Loader $loader Maintains and registers all hooks for the plugin. *
* @since 2.8.0
*/ */
protected $loader; protected $loader;
/** /**
* The unique identifier of this plugin * The unique identifier of this plugin
* *
* @since 2.8.0 * @since 2.8.0
* @access protected * @access protected
* @var string $plugin_name The string used to uniquely identify this plugin. * @var string $plugin_name The string used to uniquely identify this plugin.
*/ */
protected $plugin_name; protected $plugin_name;
/** /**
* The current version of the plugin. * The current version of the plugin.
* *
* @since 2.8.0 * @since 2.8.0
* @access protected * @access protected
* @var string $version The current version of the plugin. * @var string $version The current version of the plugin.
*/ */
protected $version; protected $version;
/** /**
* Define the core functionality of the plugin. * Build the core of the plugin.
* *
* Set the plugin name and the plugin version that can be used throughout the plugin. * Set the plugin name and the plugin version that can be used throughout the
* Load the dependencies, define the locale, and set the hooks for the admin area and * plugin. Load the dependencies, define the locale, and set the hooks for
* the public-facing side of the site. * the admin area and the public-facing side of the site.
* *
* @since 1.0.0 * @uses PLUGIN_VERSION The plugin version constant.
*
* @since 1.0.0
*/ */
public function __construct() { public function __construct() {
if ( defined( 'PLUGIN_VERSION' ) ) { if ( defined( 'PLUGIN_VERSION' ) ) {
@ -80,7 +83,7 @@ class Footnotes {
/** /**
* Load the required dependencies for this plugin. * Load the required dependencies for this plugin.
* *
* Include the following files that make up the plugin: * Includes the following files that make up the plugin:
* *
* - `Footnotes_Loader`. Orchestrates the hooks of the plugin. * - `Footnotes_Loader`. Orchestrates the hooks of the plugin.
* - `Footnotes_i18n`. Defines internationalization functionality. * - `Footnotes_i18n`. Defines internationalization functionality.
@ -91,11 +94,13 @@ class Footnotes {
* - `Footnotes_Admin`. Defines all hooks for the admin area. * - `Footnotes_Admin`. Defines all hooks for the admin area.
* - `Footnotes_Public`. Defines all hooks for the public side of the site. * - `Footnotes_Public`. Defines all hooks for the public side of the site.
* *
* Create an instance of the loader which will be used to register the hooks * Creates an instance of the loader which will be used to register the hooks
* with WordPress. * with WordPress.
* *
* @since 2.8.0 * @access private
* @access private * @uses Footnotes_Loader Loads plugin dependencies.
*
* @since 2.8.0
*/ */
private function load_dependencies() { private function load_dependencies() {
@ -137,11 +142,13 @@ class Footnotes {
/** /**
* Define the locale for this plugin for internationalization. * Define the locale for this plugin for internationalization.
* *
* Uses the `Footnotes_i18n` class in order to set the domain and to register the hook * Uses the {@see Footnotes_i18n} class in order to set the domain and to
* with WordPress. * register the hook with WordPress.
* *
* @since 2.8.0 * @access private
* @access private * @uses Footnotes_i18n Handles initialization functions.
*
* @since 2.8.0
*/ */
private function set_locale() { private function set_locale() {
@ -152,12 +159,14 @@ class Footnotes {
} }
/** /**
* Register all of the hooks related to the admin area functionality * Register all of the hooks related to the admin area functionality of the
* of the plugin. * plugin.
* *
* @since 1.5.0 * @access private
* @since 2.8.0 Moved registrating from various classes into `Footnotes_Admin`. * @uses Footnotes_Admin Defines admin functionality.
* @access private *
* @since 1.5.0
* @since 2.8.0 Moved hook registrations from various classes into `Footnotes_Admin`.
*/ */
private function define_admin_hooks() { private function define_admin_hooks() {
@ -182,11 +191,13 @@ class Footnotes {
} }
/** /**
* Register all of the hooks related to the public-facing functionality * Register all of the hooks related to the public-facing functionality of
* of the plugin. * the plugin.
* *
* @since 2.8.0
* @access private * @access private
* @uses Footnotes_Admin Defines public-facing functionality.
*
* @since 2.8.0
*/ */
private function define_public_hooks() { private function define_public_hooks() {
@ -199,42 +210,43 @@ class Footnotes {
} }
/** /**
* Run the loader to execute all of the hooks with WordPress. * Runs the loader to execute all of the hooks with WordPress.
* *
* @since 1.5.0 * @since 1.5.0
*
* @see self::initialize_widgets()
*/ */
public function run() { public function run() {
$this->loader->run(); $this->loader->run();
} }
/** /**
* The name of the plugin used to uniquely identify it within the context of * Gets the name of the plugin used to uniquely identify it within the
* WordPress and to define internationalization functionality. * context of WordPress and to define internationalization functionality.
* *
* @since 1.0.0 * @return string The name of the plugin.
* @return string The name of the plugin. *
* @since 2.8.0
*/ */
public function get_plugin_name() { public function get_plugin_name() {
return $this->plugin_name; return $this->plugin_name;
} }
/** /**
* The reference to the class that orchestrates the hooks with the plugin. * Returns a reference to the class that orchestrates the hooks with the plugin.
* *
* @since 1.0.0 * @return Footnotes_Loader Orchestrates the hooks of the plugin.
* @return Footnotes_Loader Orchestrates the hooks of the plugin. *
* @since 2.8.0
*/ */
public function get_loader() { public function get_loader() {
return $this->loader; return $this->loader;
} }
/** /**
* Retrieve the version number of the plugin. * Gets the version number of the plugin.
* *
* @since 1.0.0 * @return string The version number of the plugin.
* @return string The version number of the plugin. *
* @since 2.8.0
*/ */
public function get_version() { public function get_version() {
return $this->version; return $this->version;