<?php
/**
 * li₃: the most RAD framework for PHP (http://li3.me)
 *
 * Copyright 2009, Union of RAD. All rights reserved. This source
 * code is distributed under the terms of the BSD 3-Clause License.
 * The full license text can be found in the LICENSE.txt file.
 */

namespace lithium\util\collection;

$message  = 'The `lithium\util\collection\Filters` class has been deprecated in favor of ';
$message .= '`lithium\aop\Filters`. All old methods keep on working and are forwared to ';
$message .= 'the new ones.';
trigger_error($message, E_USER_DEPRECATED);

use lithium\aop\Filters as NewFilters;

/**
 * The `Filters` class is the basis of Lithium's method filtering system: an efficient way to enable
 * event-driven communication between classes without tight coupling and without depending on a
 * centralized publish/subscribe system.
 *
 * In Lithium itself, when creating a method that can be filtered, a method is implemented as
 * a closure and is passed to either `Object::_filter()` or `StaticObject::_filter()`. Each
 * object internally maintains its own list of filters, which are applied in these methods and
 * passed to `Filters::run()`.
 *
 * When implementing a custom filter system outside of Lithium, you can create your own list of
 * filters, and pass it to `$options['data']` in the `run()` method.
 *
 * When creating a filter to apply to a method, you need the name of the method you want to call,
 * along with a **closure**, that defines what you want the filter to do.  All filters take the same
 * 3 parameters: `$self`,`$params`, and `$chain`.
 *
 * - `$self`: If the filter is applied on an object instance, then `$self` will be that instance. If
 * applied to a static class, then `$self` will be a string containing the fully-namespaced class
 * name.
 *
 * - `$params`: Contains an associative array of the parameters that are passed into the method. You
 * can modify or inspect these parameters before allowing the method to continue.
 *
 * - `$chain`: Finally, `$chain` contains the list of filters in line to be executed (as an
 * instance of the `Filters` class).  At the bottom of `$chain` is the method itself.  This is why
 * most filters contain a line that looks like this:
 *
 * ```
 * return $chain->next($self, $params, $chain);
 * ```
 *
 * This passes control to the next filter in the chain, and finally, to the method itself.  This
 * allows you to interact with the return value as well as the parameters.
 *
 * Within the framework, you can call `applyFilter()` on any object (static or instantiated) and
 * pass the name of the method you would like to filter, along with the filter itself. For example:
 *
 * ```
 * use lithium\action\Dispatcher;
 *
 * Dispatcher::applyFilter('run', function($self, $params, $chain) {
 * 	// Custom pre-dispatch logic goes here
 * 	$response = $chain->next($self, $params, $chain);
 *
 * 	// $response now contains a Response object with the result of the dispatched request,
 * 	// and can be modified as appropriate
 * 	// ...
 * 	return $response;
 * });
 * ```
 *
 * The logic in the closure will now be executed on every call to `Dispatcher::run()`, and
 * `$response` will always be modified by any custom logic present before being returned from
 * `run()`.
 *
 * @deprecated Replaced by `\lithium\aop\Filters` and `\lithium\aop\Chain`.
 * @link http://php.net/functions.anonymous.php
 * @see lithium\util\collection\Filters::run()
 * @see lithium\core\Object::_filter()
 * @see lithium\core\StaticObject::_filter()
 * @see lithium\core\Object::applyFilter()
 * @see lithium\core\StaticObject::applyFilter()
 */
class Filters extends \lithium\util\Collection {

	/**
	 * An array of filters indexed by class and method name, stored so that they can be lazily
	 * applied to classes which are not loaded yet.
	 *
	 * @deprecated
	 * @var array
	 */
	protected static $_lazyFilters = [];

	/**
	 * This is the list of configuration settings that will be automatically applied to the
	 * properties of each `Filters` instance.
	 *
	 * @deprecated
	 * @var array
	 */
	protected $_autoConfig = ['data', 'class', 'method'];

	/**
	 * The fully-namespaced class name of the class containing the method being filtered.
	 *
	 * @deprecated
	 * @see lithium\util\collection\Filters::method()
	 * @var string
	 */
	protected $_class = null;

	/**
	 * The name of the method being filtered by the current instance of `Filters`.
	 *
	 * @deprecated
	 * @see lithium\util\collection\Filters::method()
	 * @var string
	 */
	protected $_method = null;

	/**
	 * Lazily applies a filter to a method of a static class.
	 *
	 * This method is useful if you want to apply a filter inside a global bootstrap file to a
	 * static class which may or may not be loaded during every request, or which may be loaded
	 * lazily elsewhere in your application. If the class is already loaded, the filter will be
	 * applied immediately.
	 *
	 * However, if the class has not been loaded, the filter will be stored and applied to the class
	 * the first time the method specified in `$method` is called. This works for any class which
	 * extends `StaticObject`.
	 *
	 * @deprecated Forwards to new implementation.
	 * @see lithium\core\StaticObject
	 * @param string $class The fully namespaced name of a **static** class to which the filter will
	 *               be applied. The class name specified in `$class` **must** extend
	 *               `StaticObject`, or else statically implement the `applyFilter()` method.
	 * @param string $method The method to which the filter will be applied.
	 * @param \Closure $filter The filter to apply to the class method.
	 * @return void
	 */
	public static function apply($class, $method, $filter) {
		$message  = '`\lithium\util\collection\Filters::apply()` has been deprecated ';
		$message .= 'in favor of `\lithium\aop\Filters::apply()`';
		trigger_error($message, E_USER_DEPRECATED);

		NewFilters::apply($class, $method, $filter);
	}

	/**
	 * Checks to see if the given class / method has any filters which have been applied lazily,
	 * and not yet attached.
	 *
	 * If a filter has been lazily applied (using `Filters::apply()`) to a class which is/was not
	 * yet loaded, checks to see if the filter is still being held, or has been applied. The filter
	 * will not be applied until the method being filtered has been called.
	 *
	 * @deprecated Now always returns `false`.
	 * @see lithium\util\collection\Filters::apply()
	 * @param string $class Fully-namespaced class name.
	 * @param string $method Method name.
	 * @return boolean
	 */
	public static function hasApplied($class, $method) {
		$message = '`\lithium\util\collection\Filters::hasApplied()` has been deprecated.';
		trigger_error($message, E_USER_DEPRECATED);

		return false;
	}

	/**
	 * Collects a set of filters to iterate. Creates a filter chain for the given class/method,
	 * executes it, and returns the value.
	 *
	 * @deprecated Forwards to new implementation.
	 * @param mixed $class The class for which this filter chain is being created. If this is the
	 *        result of a static method call, `$class` should be a string. Otherwise, it should
	 *        be the instance of the object making the call.
	 * @param array $params An associative array of the given method's parameters.
	 * @param array $options The configuration options with which to create the filter chain.
	 *        Mainly, these options allow the `Filters` object to be queried for details such as
	 *        which class / method initiated it. Available keys:
	 *        - `'class'`: The name of the class that initiated the filter chain.
	 *        - `'method'`: The name of the method that initiated the filter chain.
	 *        - `'data'` _array_: An array of callable objects (usually closures) to be iterated
	 *          through. By default, execution will be nested such that the first item will be
	 *          executed first, and will be the last to return.
	 * @return Returns the value returned by the first closure in `$options['data`]`.
	 */
	public static function run($class, $params, array $options = []) {
		$message  = '`\lithium\util\collection\Filters::run()` has been deprecated ';
		$message .= 'in favor of `\lithium\aop\Filters::run()`';
		trigger_error($message, E_USER_DEPRECATED);

		$defaults = ['class' => null, 'method' => null, 'data' => []];
		$options += $defaults;

		$callback = array_pop($options['data']);

		foreach ($options['data'] as $filter) {
			NewFilters::apply($class, $options['method'], $filter);
		}
		return NewFilters::run($class, $options['method'], $params, $callback);
	}

	/**
	 * Provides short-hand convenience syntax for filter chaining.
	 *
	 * @deprecated Not used here anymore.
	 * @see lithium\core\Object::applyFilter()
	 * @see lithium\core\Object::_filter()
	 * @param object $self The object instance that owns the filtered method.
	 * @param array $params An associative array containing the parameters passed to the filtered
	 *              method.
	 * @param array $chain The Filters object instance containing this chain of filters.
	 * @return mixed Returns the return value of the next filter in the chain.
	 */
	public function next(/* $self, $params, $chain */) {
		if (func_num_args() !== 3) {
			trigger_error('Missing argument/s.', E_USER_WARNING);
			return;
		}
		list($self, $params, $chain) = func_get_args();

		$message  = '`\lithium\util\collection\Filters::next()` has been deprecated ';
		$message .= 'in favor of `\lithium\aop\Chain::next()`';
		trigger_error($message, E_USER_DEPRECATED);

		if (empty($self) || empty($chain)) {
			return parent::next();
		}
		$next = parent::next();
		return $next($self, $params, $chain);
	}

	/**
	 * Gets the method name associated with this filter chain.  This is the method being filtered.
	 *
	 * @deprecated Not used here anymore.
	 * @param boolean $full Whether to return the method name including the class name or not.
	 * @return string
	 */
	public function method($full = false) {
		$message  = '`\lithium\util\collection\Filters::method()` has been deprecated ';
		$message .= 'in favor of `\lithium\aop\Chain::method()`';
		trigger_error($message, E_USER_DEPRECATED);

		return $full ? $this->_class . '::' . $this->_method : $this->_method;
	}
}

?>