Merge pull request #12818 from woocommerce/wc-logger-interface

Add WC_Logger_Interface

includes/class-wc-logger.php

@@ -12,7 +12,7 @@ if ( ! defined( 'ABSPATH' ) ) {
  * @category       Class
  * @author         WooThemes
  */
-class WC_Logger {
+class WC_Logger implements WC_Logger_Interface {
 
 	/**
 	 * Stores registered log handlers.

includes/interfaces/wc-logger-interface.php

@@ -0,0 +1,132 @@
+<?php
+if ( ! defined( 'ABSPATH' ) ) {
+	exit; // Exit if accessed directly
+}
+
+/**
+ * WC Logger Interface
+ *
+ * Functions that must be defined to correctly fulfill logger API.
+ *
+ * @version        1.0.0
+ * @category       Interface
+ * @author         WooThemes
+ */
+interface WC_Logger_Interface {
+
+	/**
+	 * Add a log entry.
+	 *
+	 * This is not the preferred method for adding log messages. Please use log() or any one of
+	 * the level methods (debug(), info(), etc.). This method may be deprecated in the future.
+	 *
+	 * @param string $handle
+	 * @param string $message
+	 * @return bool True if log was added, otherwise false.
+	 */
+	public function add( $handle, $message, $level = WC_Log_Levels::NOTICE );
+
+	/**
+	 * Add a log entry.
+	 *
+	 * @param string $level One of the following:
+	 *     'emergency': System is unusable.
+	 *     'alert': Action must be taken immediately.
+	 *     'critical': Critical conditions.
+	 *     'error': Error conditions.
+	 *     'warning': Warning conditions.
+	 *     'notice': Normal but significant condition.
+	 *     'informational': Informational messages.
+	 *     'debug': Debug-level messages.
+	 * @param string $message Log message.
+	 * @param array $context Optional. Additional information for log handlers.
+	 */
+	public function log( $level, $message, $context = array() );
+
+	/**
+	 * Adds an emergency level message.
+	 *
+	 * System is unusable.
+	 *
+	 * @param string $message Log message.
+	 * @param array $context Optional. Additional information for log handlers.
+	 */
+	public function emergency( $message, $context = array() );
+
+	/**
+	 * Adds an alert level message.
+	 *
+	 * Action must be taken immediately.
+	 * Example: Entire website down, database unavailable, etc.
+	 *
+	 * @param string $message Log message.
+	 * @param array $context Optional. Additional information for log handlers.
+	 */
+	public function alert( $message, $context = array() );
+
+	/**
+	 * Adds a critical level message.
+	 *
+	 * Critical conditions.
+	 * Example: Application component unavailable, unexpected exception.
+	 *
+	 * @param string $message Log message.
+	 * @param array $context Optional. Additional information for log handlers.
+	 */
+	public function critical( $message, $context = array() );
+
+	/**
+	 * Adds an error level message.
+	 *
+	 * Runtime errors that do not require immediate action but should typically be logged
+	 * and monitored.
+	 *
+	 * @param string $message Log message.
+	 * @param array $context Optional. Additional information for log handlers.
+	 */
+	public function error( $message, $context = array() );
+
+	/**
+	 * Adds a warning level message.
+	 *
+	 * Exceptional occurrences that are not errors.
+	 *
+	 * Example: Use of deprecated APIs, poor use of an API, undesirable things that are not
+	 * necessarily wrong.
+	 *
+	 * @param string $message Log message.
+	 * @param array $context Optional. Additional information for log handlers.
+	 */
+	public function warning( $message, $context = array() );
+
+	/**
+	 * Adds a notice level message.
+	 *
+	 * Normal but significant events.
+	 *
+	 * @param string $message Log message.
+	 * @param array $context Optional. Additional information for log handlers.
+	 */
+	public function notice( $message, $context = array() );
+
+	/**
+	 * Adds a info level message.
+	 *
+	 * Interesting events.
+	 * Example: User logs in, SQL logs.
+	 *
+	 * @param string $message Log message.
+	 * @param array $context Optional. Additional information for log handlers.
+	 */
+	public function info( $message, $context = array() );
+
+	/**
+	 * Adds a debug level message.
+	 *
+	 * Detailed debug information.
+	 *
+	 * @param string $message Log message.
+	 * @param array $context Optional. Additional information for log handlers.
+	 */
+	public function debug( $message, $context = array() );
+}

includes/wc-core-functions.php

@@ -1412,15 +1412,33 @@ function wc_get_rounding_precision() {
 }
 
 /**
- * Returns a new instance of a WC Logger.
+ * Get a shared logger instance.
- * Use woocommerce_logging_class filter to change the logging class.
+ *
+ * Use the woocommerce_logging_class filter to change the logging class. The provided class *must*
+ * implement WC_Logger_Interface.
+ *
+ * @see WC_Logger_Interface
+ *
  * @return WC_Logger
  */
 function wc_get_logger() {
 	static $logger = null;
 	if ( null === $logger ) {
 		$class = apply_filters( 'woocommerce_logging_class', 'WC_Logger' );
-		$logger = new $class;
+		$implements = class_implements( $class );
+		if ( is_array( $implements ) && in_array( 'WC_Logger_Interface', $implements ) ) {
+			$logger = new $class;
+		} else {
+			wc_doing_it_wrong(
+				__FUNCTION__,
+				sprintf(
+					__( 'The class <code>%s</code> provided by woocommerce_logging_class filter must implement <code>WC_Logger_Interface</code>.', 'woocommerce' ),
+					esc_html( $class )
+				),
+				'2.7'
+			);
+			$logger = new WC_Logger();
+		}
 	}
 	return $logger;
 }

tests/unit-tests/util/core-functions.php

@@ -244,6 +244,10 @@ class WC_Tests_Core_Functions extends WC_Unit_Test_Case {
 	 * @since 2.7.0
 	 */
 	public function test_wc_get_logger() {
+		// This filter should have no effect because the class does not implement WC_Logger_Interface
+		add_filter( 'woocommerce_logging_class', array( $this, 'return_bad_logger' ) );
+
+		$this->setExpectedIncorrectUsage( 'wc_get_logger' );
 		$log_a = wc_get_logger();
 		$log_b = wc_get_logger();
 
@@ -252,6 +256,17 @@ class WC_Tests_Core_Functions extends WC_Unit_Test_Case {
 		$this->assertSame( $log_a, $log_b, '`wc_get_logger()` should return the same instance' );
 	}
 
+	/**
+	 * Return class which does not implement WC_Logger_Interface
+	 *
+	 * This is a helper function to test woocommerce_logging_class filter and wc_get_logger.
+	 *
+	 * @return string Class name
+	 */
+	public function return_bad_logger() {
+		return __CLASS__;
+	}
+
 	/**
 	 * Test wc_get_core_supported_themes().
 	 *

woocommerce.php

@@ -287,6 +287,7 @@ final class WooCommerce {
 		include_once( WC_ABSPATH . 'includes/abstracts/abstract-wc-payment-gateway.php' ); // A Payment gateway
 		include_once( WC_ABSPATH . 'includes/abstracts/abstract-wc-integration.php' ); // An integration with a service
 		include_once( WC_ABSPATH . 'includes/abstracts/abstract-wc-log-handler.php' );
+		include_once( WC_ABSPATH . 'includes/interfaces/wc-logger-interface.php' );
 		include_once( WC_ABSPATH . 'includes/class-wc-product-factory.php' ); // Product factory
 		include_once( WC_ABSPATH . 'includes/class-wc-payment-tokens.php' ); // Payment tokens controller
 		include_once( WC_ABSPATH . 'includes/class-wc-shipping-zone.php' );