laipower/wp-content/plugins/easy-digital-downloads/includes/reports/data/class-endpoint-registry.php

315 lines
8.3 KiB
PHP
Raw Normal View History

<?php
/**
* Reports API - Data Endpoints Registry
*
* @package EDD
* @subpackage Reports/Data
* @copyright Copyright (c) 2018, Easy Digital Downloads, LLC
* @license http://opensource.org/licenses/gpl-2.0.php GNU Public License
* @since 3.0
*/
namespace EDD\Reports\Data;
use EDD\Utils;
use EDD\Reports;
use EDD\Reports\Exceptions as Reports_Exceptions;
/**
* Implements a singleton registry for registering reports data endpoints.
*
* @since 3.0
*
* @see \EDD\Reports\Registry
* @see \EDD\Utils\Static_Registry
*
* @method array get_endpoint( string $endpoint_id )
* @method bool endpoint_exists( string $endpoing_id )
* @method void unregister_endpoint( string $endpoint_id )
* @method array get_endpoints( string $sort )
*/
class Endpoint_Registry extends Reports\Registry implements Utils\Static_Registry {
/**
* Registry item error label.
*
* @since 3.0
* @var string
*/
public static $item_error_label = 'reports endpoint';
/**
* The one true Endpoint_Registry instance.
*
* @since 3.0
* @var Endpoint_Registry
*/
private static $instance;
/**
* Retrieves the one true Endpoint_Registry instance.
*
* @since 3.0
*
* @return Endpoint_Registry Registry instance.
*/
public static function instance() {
if ( is_null( self::$instance ) ) {
self::$instance = new Endpoint_Registry();
}
return self::$instance;
}
/**
* Handles magic method calls for endpoint manipulation.
*
* @since 3.0
*
* @throws \EDD_Exception If the endpoint doesn't exist for get_endpoint().
*
* @param string $name Method name.
* @param array $arguments Method arguments (if any)
* @return mixed Results of the method call (if any).
*/
public function __call( $name, $arguments ) {
$endpoint_id_or_sort = isset( $arguments[0] )
? $arguments[0]
: '';
switch( $name ) {
case 'get_endpoint':
return parent::get_item( $endpoint_id_or_sort );
case 'endpoint_exists':
return parent::offsetExists( $endpoint_id_or_sort );
case 'unregister_endpoint':
parent::remove_item( $endpoint_id_or_sort );
break;
case 'get_endpoints':
return $this->get_items_sorted( $endpoint_id_or_sort );
}
}
/**
* Registers a new data endpoint to the master registry.
*
* @since 3.0
*
* @throws \EDD_Exception if the endpoint could not be validated.
*
* @param string $endpoint_id Reports data endpoint ID.
* @param array $attributes {
* Endpoint attributes. All arguments are required unless otherwise noted.
*
* @type string $label Endpoint label.
* @type int $priority Optional. Priority by which to retrieve the endpoint. Default 10.
* @type array $views {
* Array of view handlers by type.
*
* @type array $view_type {
* View type slug, with array beneath it.
*
* @type callable $data_callback Callback used to retrieve data for the view.
* @type callable $display_callback Callback used to render the view.
* @type array $display_args Optional. Array of arguments to pass to the
* display_callback (if any). Default empty array.
* }
* }
* }
* @return bool True if the endpoint was successfully registered, otherwise false.
*/
public function register_endpoint( $endpoint_id, $attributes ) {
$defaults = array(
'label' => '',
'priority' => 10,
'views' => array(),
);
$attributes = array_merge( $defaults, $attributes );
$attributes['id'] = $endpoint_id;
$attributes['views'] = Reports\parse_endpoint_views( $attributes['views'] );
// Bail if this endpoint ID is already registered.
if ( $this->offsetExists( $endpoint_id ) ) {
$message = sprintf( 'The \'%1$s\' endpoint already exists and cannot be registered.', $endpoint_id );
throw new Utils\Exception( $message );
}
try {
$valid = $this->validate_endpoint( $endpoint_id, $attributes );
} catch ( \EDD_Exception $exception ) {
throw $exception;
}
if ( false === $valid ) {
return false;
} else {
try {
$return_value = parent::add_item( $endpoint_id, $attributes );
} catch ( \EDD_Exception $exception ) {
throw $exception;
}
return $return_value;
}
}
/**
* Validates the endpoint attributes.
*
* @since 3.0
*
* @throws \EDD_Exception if the `$label` or `$views` attributes are empty.
* @throws \EDD_Exception if any of the `$views` sub-attributes are empty, except `$filters`.
*
* @param string $endpoint_id Reports data endpoint ID.
* @param array $attributes Endpoint attributes. See register_endpoint() for full accepted attributes.
* @return bool True if the endpoint is considered 'valid', otherwise false.
*/
public function validate_endpoint( $endpoint_id, $attributes ) {
$is_valid = true;
try {
$this->validate_attributes( $attributes, $endpoint_id );
try {
$this->validate_views( $attributes['views'], $endpoint_id );
} catch( \EDD_Exception $exception ) {
edd_debug_log_exception( $exception );
$is_valid = false;
throw $exception;
}
} catch( \EDD_Exception $exception ) {
edd_debug_log_exception( $exception );
$is_valid = false;
throw $exception;
}
return $is_valid;
}
/**
* Builds an endpoint object from a registry entry.
*
* @since 3.0
*
* @param string|Endpoint $endpoint Endpoint ID or object.
* @param string $view_type View type to use when building the object.
* @param string $report Optional. Report ID. Default null.
* @return Endpoint|\WP_Error Endpoint object on success, otherwise a WP_Error object.
*/
public function build_endpoint( $endpoint, $view_type, $report = null ) {
// If an endpoint object was passed, just return it.
if ( $endpoint instanceof Endpoint ) {
return $endpoint;
}
try {
$_endpoint = $this->get_endpoint( $endpoint );
} catch( \EDD_Exception $exception ) {
edd_debug_log_exception( $exception );
return new \WP_Error( 'invalid_endpoint', $exception->getMessage(), $endpoint );
}
if ( ! empty( $_endpoint ) ) {
if ( Reports\validate_endpoint_view( $view_type ) ) {
$_endpoint['report'] = $report;
$handler = Reports\get_endpoint_handler( $view_type );
if ( ! empty( $handler ) && class_exists( $handler ) ) {
$_endpoint = new $handler( $_endpoint );
} else {
$_endpoint = new \WP_Error(
'invalid_handler',
sprintf( 'The handler for the \'%1$s\' view is invalid.', $view_type ),
$handler
);
}
} else {
$_endpoint = new \WP_Error(
'invalid_view',
sprintf( 'The \'%1$s\' view is invalid.', $view_type )
);
}
}
return $_endpoint;
}
/**
* Validates view properties for an incoming endpoint.
*
* @since 3.0
*
* @throws \EDD_Exception if the view attributes is empty or it's not a valid view.
*
* @param array $views List of attributes to check.
* @param string $endpoint_id Endpoint ID.
* @return void
*/
public function validate_views( $views, $endpoint_id ) {
$valid_views = Reports\get_endpoint_views();
$this->validate_attributes( $views, $endpoint_id );
foreach ( $views as $view => $attributes ) {
if ( array_key_exists( $view, $valid_views ) ) {
if ( ! empty( $valid_views[ $view ]['allow_empty'] ) ) {
$skip = $valid_views[ $view ]['allow_empty'];
} else {
$skip = array();
}
// View atts have already been parsed at this point, just validate them.
$this->validate_view_attributes( $attributes, $view, $skip );
} else {
throw Reports_Exceptions\Invalid_View::from( $view, __METHOD__, $endpoint_id );
}
}
}
/**
* Validates a list of endpoint view attributes.
*
* @since 3.0
*
* @throws \EDD_Exception if a required view attribute is empty.
*
* @param array $attributes List of view attributes to check for emptiness.
* @param string $view View slug.
* @param array $skip Optional. List of view attributes to skip validating.
* Default empty array.
* @return void
*/
public function validate_view_attributes( $attributes, $view, $skip = array() ) {
foreach ( $attributes as $attribute => $value ) {
if ( in_array( $attribute, $skip, true ) ) {
continue;
}
if ( empty( $value ) ) {
throw Reports_Exceptions\Invalid_View_Parameter::from( $attribute, __METHOD__, $view );
}
}
}
}