<?php
namespace Automattic\WooCommerce\Internal\Traits;
use Automattic\WooCommerce\Utilities\ArrayUtil;
/**
* This trait allows making private methods of a class accessible from outside.
* This is useful to define hook handlers with the [$this, 'method'] or [__CLASS__, 'method'] syntax
* without having to make the method public (and thus having to keep it forever for backwards compatibility).
*
* Example:
*
* class Foobar {
* use AccessiblePrivateMethods;
*
* public function __construct() {
* self::add_action('some_action', [$this, 'handle_some_action']);
* }
*
* public static function init() {
* self::add_filter('some_filter', [__CLASS__, 'handle_some_filter']);
* }
*
* private function handle_some_action() {
* }
*
* private static function handle_some_filter() {
* }
* }
*
* For this to work the callback must be an array and the first element of the array must be either '$this', '__CLASS__',
* or another instance of the same class; otherwise the method won't be marked as accessible
* (but the corresponding WordPress 'add_action' and 'add_filter' functions will still be called).
*
* No special procedure is needed to remove hooks set up with these methods, the regular 'remove_action'
* and 'remove_filter' functions provided by WordPress can be used as usual.
*/
trait AccessiblePrivateMethods {
//phpcs:disable PSR2.Classes.PropertyDeclaration.Underscore
/**
* List of instance methods marked as externally accessible.
*
* @var array
*/
private $_accessible_private_methods = array();
/**
* List of static methods marked as externally accessible.
*
* @var array
*/
private static $_accessible_static_private_methods = array();
//phpcs:enable PSR2.Classes.PropertyDeclaration.Underscore
/**
* Register a WordPress action.
* If the callback refers to a private or protected instance method in this class, the method is marked as externally accessible.
*
* $callback can be a standard callable, or a string representing the name of a method in this class.
*
* @param string $hook_name The name of the action to add the callback to.
* @param callable|string $callback The callback to be run when the action is called.
* @param int $priority Optional. Used to specify the order in which the functions
* associated with a particular action are executed.
* Lower numbers correspond with earlier execution,
* and functions with the same priority are executed
* in the order in which they were added to the action. Default 10.
* @param int $accepted_args Optional. The number of arguments the function accepts. Default 1.
*/
protected static function add_action( string $hook_name, $callback, int $priority = 10, int $accepted_args = 1 ): void {
self::process_callback_before_hooking( $callback );
add_action( $hook_name, $callback, $priority, $accepted_args );
}
/**
* Register a WordPress filter.
* If the callback refers to a private or protected instance method in this class, the method is marked as externally accessible.
*
* $callback can be a standard callable, or a string representing the name of a method in this class.
*
* @param string $hook_name The name of the filter to add the callback to.
* @param callable|string $callback The callback to be run when the filter is called.
* @param int $priority Optional. Used to specify the order in which the functions
* associated with a particular filter are executed.
* Lower numbers correspond with earlier execution,
* and functions with the same priority are executed
* in the order in which they were added to the filter. Default 10.
* @param int $accepted_args Optional. The number of arguments the function accepts. Default 1.
*/
protected static function add_filter( string $hook_name, $callback, int $priority = 10, int $accepted_args = 1 ): void {
self::process_callback_before_hooking( $callback );
add_filter( $hook_name, $callback, $priority, $accepted_args );
}
/**
* Do the required processing to a callback before invoking the WordPress 'add_action' or 'add_filter' function.
*
* @param callable $callback The callback to process.
* @return void
*/
protected static function process_callback_before_hooking( $callback ): void {
if ( ! is_array( $callback ) || count( $callback ) < 2 ) {
return;
}
$first_item = $callback[0];
if ( __CLASS__ === $first_item ) {
static::mark_static_method_as_accessible( $callback[1] );
} elseif ( is_object( $first_item ) && get_class( $first_item ) === __CLASS__ ) {
$first_item->mark_method_as_accessible( $callback[1] );
}
}
/**
* Register a private or protected instance method of this class as externally accessible.
*
* @param string $method_name Method name.
* @return bool True if the method has been marked as externally accessible, false if the method doesn't exist.
*/
protected function mark_method_as_accessible( string $method_name ): bool {
// Note that an "is_callable" check would be useless here:
// "is_callable" always returns true if the class implements __call.
if ( method_exists( $this, $method_name ) ) {
$this->_accessible_private_methods[ $method_name ] = $method_name;
return true;
}
return false;
}
/**
* Register a private or protected static method of this class as externally accessible.
*
* @param string $method_name Method name.
* @return bool True if the method has been marked as externally accessible, false if the method doesn't exist.
*/
protected static function mark_static_method_as_accessible( string $method_name ): bool {
if ( method_exists( __CLASS__, $method_name ) ) {
static::$_accessible_static_private_methods[ $method_name ] = $method_name;
return true;
}
return false;
}
/**
* Undefined/inaccessible instance method call handler.
*
* @param string $name Called method name.
* @param array $arguments Called method arguments.
* @return mixed
* @throws \Error The called instance method doesn't exist or is private/protected and not marked as externally accessible.
*/
public function __call( $name, $arguments ) {
if ( isset( $this->_accessible_private_methods[ $name ] ) ) {
return call_user_func_array( array( $this, $name ), $arguments );
} elseif ( is_callable( array( 'parent', '__call' ) ) ) {
return parent::__call( $name, $arguments );
} elseif ( method_exists( $this, $name ) ) {
throw new \Error( 'Call to private method ' . get_class( $this ) . '::' . $name );
} else {
throw new \Error( 'Call to undefined method ' . get_class( $this ) . '::' . $name );
}
}
/**
* Undefined/inaccessible static method call handler.
*
* @param string $name Called method name.
* @param array $arguments Called method arguments.
* @return mixed
* @throws \Error The called static method doesn't exist or is private/protected and not marked as externally accessible.
*/
public static function __callStatic( $name, $arguments ) {
if ( isset( static::$_accessible_static_private_methods[ $name ] ) ) {
return call_user_func_array( array( __CLASS__, $name ), $arguments );
} elseif ( is_callable( array( 'parent', '__callStatic' ) ) ) {
return parent::__callStatic( $name, $arguments );
} elseif ( 'add_action' === $name || 'add_filter' === $name ) {
$proper_method_name = 'add_static_' . substr( $name, 4 );
throw new \Error( __CLASS__ . '::' . $name . " can't be called statically, did you mean '$proper_method_name'?" );
} elseif ( method_exists( __CLASS__, $name ) ) {
throw new \Error( 'Call to private method ' . __CLASS__ . '::' . $name );
} else {
throw new \Error( 'Call to undefined method ' . __CLASS__ . '::' . $name );
}
}
}