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

refactor: add type decs

Browse source
This commit is contained in:
Ben Goldsworthy 2021-05-02 09:26:03 +01:00
parent c0dd0d0623
commit e8e41c6c9d
7 changed files with 106 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
src/admin/layout/class-engine.php
View file

@ -121,7 +121,7 @@ abstract class Engine {
* @param string $p_str_title Title of the section.
* @param int $p_int_settings_container_index Settings Container index.
* @param bool $p_bool_has_submit_button Whether a ‘Submit’ button should
* be displayed for this section. Default `true`.
* be displayed for this section. Default `true`.
* @return array {
* A dashboard section.
*

3
src/admin/layout/class-settings.php
View file

@ -77,8 +77,7 @@ class Settings extends Engine {
/**
* Returns an array of all registered sections for the sub-page.
*
* @see Engine::add_section() For more information on the
* section array format.
* @see Engine::add_section() For more information on the section array format.
* @return array[] All of the registered sections.
*
* @since 1.5.0

34
src/includes/class-convert.php
View file

@ -22,16 +22,16 @@ class Convert {
*
* @param int $p_int_index Index to be converted.
* @param string $p_str_convert_style Counter style to use.
* @return string Converted Index converted to the defined counter style.
* @return string The index converted to the defined counter style.
*
* @since 1.5.0
*/
public static function index( $p_int_index, $p_str_convert_style = 'arabic_plain' ) {
public static function index( int $p_int_index, string $p_str_convert_style = 'arabic_plain' ): string {
switch ( $p_str_convert_style ) {
case 'romanic':
return self::to_romanic( $p_int_index, true );
case 'roman':
return self::to_roman( $p_int_index, true );
case 'roman_low':
return self::to_romanic( $p_int_index, false );
return self::to_roman( $p_int_index, false );
case 'latin_high':
return self::to_latin( $p_int_index, true );
case 'latin_low':
@ -57,7 +57,7 @@ class Convert {
* @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( int $p_int_value, bool $p_bool_upper_case ): string {
// Output string.
$l_str_return = '';
$l_int_offset = 0;
@ -89,7 +89,7 @@ class Convert {
* @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( int $p_int_value ): string {
// Add a leading 0 if number lower then 10.
if ( $p_int_value < 10 ) {
return '0' . $p_int_value;
@ -106,9 +106,9 @@ class Convert {
*
* @since 1.0-gamma
*/
private static function to_romanic( $p_int_value, $p_bool_upper_case ) {
// Table containing all necessary romanic letters.
$l_arr_romanic_letters = array(
private static function to_roman( int $p_int_value, bool $p_bool_upper_case ): string {
// Table containing all necessary roman letters.
$l_arr_roman_numerals = array(
'M' => 1000,
'CM' => 900,
'D' => 500,
@ -127,15 +127,15 @@ class Convert {
$l_str_return = '';
// Iterate through integer value until it is reduced to 0.
while ( $p_int_value > 0 ) {
foreach ( $l_arr_romanic_letters as $l_str_romanic => $l_int_arabic ) {
foreach ( $l_arr_roman_numerals as $l_str_roman => $l_int_arabic ) {
if ( $p_int_value >= $l_int_arabic ) {
$p_int_value -= $l_int_arabic;
$l_str_return .= $l_str_romanic;
$l_str_return .= $l_str_roman;
break;
}
}
}
// Return romanic letters as string.
// Return roman letters as string.
if ( $p_bool_upper_case ) {
return strtoupper( $l_str_return );
}
@ -151,7 +151,7 @@ class Convert {
* @since 1.0-beta
* @todo Replace with built-in type casting.
*/
public static function to_bool( $p_str_value ) {
public static function to_bool( string $p_str_value ): bool {
// Convert string to lower-case to make it easier.
$p_str_value = strtolower( $p_str_value );
// Check if string seems to contain a "true" value.
@ -171,12 +171,13 @@ class Convert {
* Get an HTML array short code depending on Arrow-Array key index.
*
* @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 string|string[] Array of all arrows if index is empty, otherwise HTML tag of a specific arrow.
*
* @since 1.3.2
* @todo Review.
* @todo Single return type.
*/
public static function get_arrow( $p_int_index = -1 ) {
public static function get_arrow( int $p_int_index = -1 ) {
// Define all possible arrows.
$l_arr_arrows = array( '&#8593;', '&#8613;', '&#8607;', '&#8617;', '&#8626;', '&#8629;', '&#8657;', '&#8673;', '&#8679;', '&#65514;' );
// Convert index to an integer.
@ -196,6 +197,7 @@ class Convert {
* Displays a variable.
*
* @param mixed $p_mixed_value The variable to display.
* @return void
*
* @since 1.5.0
* @todo Replace with proper logging/debug functions.

2
src/includes/class-deactivator.php
View file

@ -24,6 +24,8 @@ class Deactivator {
* Currently NOP.
*
* @since 2.8.0
*
* @return void
*/
public static function deactivate() {
// Nothing yet.

2
src/includes/class-i18n.php
View file

@ -31,6 +31,8 @@ class i18n {
*
* @since 1.5.1
* @since 2.8.0 Rename from `load()` to `load_plugin_textdomain()`. Remove unused `$p_str_language_code` parameter.
*
* @return void
*/
public function load_plugin_textdomain() {
load_plugin_textdomain(

62
src/includes/class-loader.php
View file

@ -24,20 +24,20 @@ class Loader {
/**
* The array of actions registered with WordPress.
*
* @access protected
* @var array $actions The actions registered with WordPress to fire when the plugin loads.
*
* @since 2.8.0
* @see Loader::add() For more information on the hook array format.
*
* @var (string|int|object)[][] $actions The actions registered with WordPress to fire when the plugin loads.
*/
protected $actions;
/**
* The array of filters registered with WordPress.
*
* @access protected
* @var array $filters The filters registered with WordPress to fire when the plugin loads.
*
* @since 2.8.0
* @see Loader::add() For more information on the hook array format.
*
* @var (string|int|object)[][] $filters The filters registered with WordPress to fire when the plugin loads.
*/
protected $filters;
@ -45,6 +45,8 @@ class Loader {
* Initialize the collections used to maintain the actions and filters.
*
* @since 2.8.0
*
* @return void
*/
public function __construct() {
@ -56,13 +58,15 @@ class Loader {
/**
* Add a new action to the collection to be registered with WordPress.
*
* @since 2.8.0
* @see Loader::add() For more information on the hook array format.
*
* @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 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 $accepted_args (optional) The number of arguments that should be passed to the $callback. Default is 1.
*
* @since 2.8.0
* @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.
* @return void
*/
public function add_action( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
$this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority, $accepted_args );
@ -71,13 +75,15 @@ class Loader {
/**
* Add a new filter to the collection to be registered with WordPress.
*
* @since 2.8.0
* @see Loader::add() For more information on the hook array format.
*
* @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 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 $accepted_args (optional) The number of arguments that should be passed to the $callback. Default is 1.
*
* @since 2.8.0
* @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.
* @return void
*/
public function add_filter( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
$this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority, $accepted_args );
@ -87,16 +93,23 @@ class Loader {
* A utility function that is used to register the actions and hooks into a single
* collection.
*
* @access private
* @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 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 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`.
* @return array The collection of actions and filters registered with WordPress.
*
* @since 2.8.0
*
* @param (string|int|object)[][] $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 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 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`.
* @return (string|int|object)[][] {
* The registered hook(s).
*
* @type string $hook The name of the registered WordPress hook.
* @type object $component A reference to the instance of the object on which the hook is defined.
* @type string $callback The name of the function definition on the `$component`.
* @type int $priority The priority at which the function should be fired.
* @type int $accepted_args The number of arguments that should be passed to the `$callback`.
* }
*/
private function add( $hooks, $hook, $component, $callback, $priority, $accepted_args ) {
@ -116,6 +129,9 @@ class Loader {
* Registers the filters and actions with WordPress.
*
* @since 2.8.0
* @see Loader::add() For more information on the hook array format.
*
* @return void
*/
public function run() {

92
src/includes/class-template.php
View file

@ -30,59 +30,60 @@ class Template {
/**
* Directory name for dashboard partials.
*
* @var string
*
* @since 1.5.0
*
* @var string
*/
const C_STR_DASHBOARD = 'admin/partials';
/**
* Directory name for public partials.
*
* @var string
*
* @since 1.5.0
*
* @var string
*/
const C_STR_PUBLIC = 'public/partials';
/**
* Contains the content of the template after initialize.
*
* @var string
*
* @since 1.5.0
*
* @var string
*/
private $a_str_original_content = '';
/**
* Contains the content of the template after initialize with replaced place holders.
*
* @var string
*
* @since 1.5.0
*
* @var string
*/
private $a_str_replaced_content = '';
/**
* Plugin Directory
*
* @var string
*
* @since 2.4.0d3
*
* @var string
*/
public $plugin_directory;
/**
* Class Constructor. Reads and loads the template file without replace any placeholder.
*
* @since 1.5.0
* @todo Refactor templating.
*
* @param string $p_str_file_type Template file type.
* @param string $p_str_file_name Template file name inside the `partials/` directory, without the file extension.
* @param string $p_str_extension (optional) Template file extension (default: 'html').
*
* @since 1.5.0
* @todo Refactor templating.
* @return void
*/
public function __construct( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) {
public function __construct( string $p_str_file_type, string $p_str_file_name, string $p_str_extension = 'html' ) {
// No template file type and/or file name set.
if ( empty( $p_str_file_type ) || empty( $p_str_file_name ) ) {
return;
@ -102,13 +103,13 @@ class Template {
/**
* 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
* @todo Refactor templating.
*
* @param string[] $p_arr_placeholders Placeholders (key = placeholder, value = value).
* @return bool `true` on Success, `false` if placeholders invalid.
*/
public function replace( $p_arr_placeholders ) {
public function replace( array $p_arr_placeholders ): bool {
// No placeholders set.
if ( empty( $p_arr_placeholders ) ) {
return false;
@ -130,6 +131,8 @@ class Template {
*
* @since 1.5.0
* @todo Refactor templating.
*
* @return void
*/
public function reload() {
$this->a_str_replaced_content = $this->a_str_original_content;
@ -138,25 +141,25 @@ class Template {
/**
* Returns the content of the template file with replaced placeholders.
*
* @return string Template content with replaced placeholders.
*
* @since 1.5.0
* @todo Refactor templating.
*
* @return string Template content with replaced placeholders.
*/
public function get_content() {
public function get_content(): string {
return $this->a_str_replaced_content;
}
/**
* Process template file.
*
* @param string $template The template to be processed.
* @return void
*
* @since 2.4.0d3
* @todo Refactor templating.
*
* @param string $template The template to be processed.
* @return void
*/
public function process_template( $template ) {
public function process_template( string $template ) {
// phpcs:disable WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
$this->a_str_original_content = preg_replace( '#<!--.+?-->#s', '', file_get_contents( $template ) );
// phpcs:enable
@ -172,52 +175,43 @@ class Template {
/**
* Get the template.
*
* @since 2.5.0
* @todo Refactor templating.
* @todo Single return type.
*
* @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.5.0
* @todo Refactor templating.
* @return string|bool `false` or the template path
*/
public function get_template( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) {
public function get_template( string $p_str_file_type, string $p_str_file_name, string $p_str_extension = 'html' ) {
$located = false;
/**
/*
* The directory can be changed.
*
* @usage to change location of templates to 'template_parts/footnotes/':
* add_filter( 'template_directory', function( $directory ) {
* return 'template_parts/footnotes/';
* } );
*
* @todo Review.
* To change location of templates to 'template_parts/footnotes/':
* add_filter( 'template_directory', function( $directory ) {
* return 'template_parts/footnotes/';
* } );
*/
$template_directory = apply_filters( '', 'footnotes/' );
$custom_directory = apply_filters( 'custom_template_directory', 'footnotes-custom/' );
$template_name = $p_str_file_type . '/' . $p_str_file_name . '.' . $p_str_extension;
/**
* Look in active theme.
*/
// Look in active theme.
if ( file_exists( trailingslashit( get_stylesheet_directory() ) . $template_directory . $template_name ) ) {
$located = trailingslashit( get_stylesheet_directory() ) . $template_directory . $template_name;
/**
* Look in parent theme in case active is child.
*/
// Look in parent theme in case active is child.
} elseif ( file_exists( trailingslashit( get_template_directory() ) . $template_directory . $template_name ) ) {
$located = trailingslashit( get_template_directory() ) . $template_directory . $template_name;
/**
* Look in custom plugin directory.
*/
// Look in custom plugin directory.
} elseif ( file_exists( trailingslashit( WP_PLUGIN_DIR ) . $custom_directory . 'templates/' . $template_name ) ) {
$located = trailingslashit( WP_PLUGIN_DIR ) . $custom_directory . 'templates/' . $template_name;
/**
* Fall back to the templates shipped with the plugin.
*/
// Fall back to the templates shipped with the plugin.
} elseif ( file_exists( $this->plugin_directory . $template_name ) ) {
$located = $this->plugin_directory . $template_name;
}