Collects a set of filters to iterate. Creates a filter chain for the given class/method,
executes it, and returns the value.
| public static run ( mixed $class, array $params, array $options = [] ) : Returns | ||
| $class | mixed | 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. |
| $params | array | An associative array of the given method's parameters. |
| $options | array | 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 function testRunWithoutChain()
{
$options = array('method' => __FUNCTION__, 'class' => __CLASS__, 'items' => array(function ($self, $params, $chain) {
return $chain->next($self, $params, null);
}, 'This is a filter chain that calls $chain->next() without the $chain argument.'));
$result = Filters::run(__CLASS__, array(), $options);
$expected = 'This is a filter chain that calls $chain->next() without the $chain argument.';
$this->assertEqual($expected, $result);
}
/**
* Executes a set of filters against a method by taking a method's main implementation as a
* callback, and iteratively wrapping the filters around it.
*
* @see lithium\util\collection\Filters
* @param string|array $method The name of the method being executed, or an array containing
* the name of the class that defined the method, and the method name.
* @param array $params An associative array containing all the parameters passed into
* the method.
* @param Closure $callback The method's implementation, wrapped in a closure.
* @param array $filters Additional filters to apply to the method for this call only.
* @return mixed
*/
protected static function _filter($method, $params, $callback, $filters = array())
{
$class = get_called_class();
$hasNoFilters = empty(static::$_methodFilters[$class][$method]);
if ($hasNoFilters && !$filters && !Filters::hasApplied($class, $method)) {
return $callback($class, $params, null);
}
if (!isset(static::$_methodFilters[$class][$method])) {
static::$_methodFilters += array($class => array());
static::$_methodFilters[$class][$method] = array();
}
$data = array_merge(static::$_methodFilters[$class][$method], $filters, array($callback));
return Filters::run($class, $params, compact('data', 'class', 'method'));
}
/**
* Uses service location (i.e. `Libraries::locate()`) to look up a named class of a particular
* type, and creates an instance of it, and passes an array of parameters to the constructor.
*
* If the given class can't be found, an exception is thrown.
*
* @param string $type The type of class as defined by `Libraries::$_paths`.
* @param string $name The un-namespaced name of the class to instantiate.
* @param array $options An array of constructor parameters to pass to the class.
* @return object If the class is found, returns an instance of it, otherwise throws an
* exception.
* @throws lithium\core\ClassNotFoundException Throws an exception if the class can't be found.
* @filter
*/
public static function instance($type, $name, array $options = array())
{
$params = compact('type', 'name', 'options');
$_paths =& static::$_paths;
$implementation = function ($self, $params) use(&$_paths) {
$name = $params['name'];
$type = $params['type'];
if (!$name && !$type) {
$message = "Invalid class lookup: `\$name` and `\$type` are empty.";
throw new ClassNotFoundException($message);
}
if (!is_string($type) && $type !== null && !isset($_paths[$type])) {
throw new ClassNotFoundException("Invalid class type `{$type}`.");
}
if (!($class = $self::locate($type, $name))) {
throw new ClassNotFoundException("Class `{$name}` of type `{$type}` not found.");
}
if (is_object($class)) {
return $class;
}
if (!(is_string($class) && class_exists($class))) {
throw new ClassNotFoundException("Class `{$name}` of type `{$type}` not defined.");
}
return new $class($params['options']);
};
if (!isset(static::$_methodFilters[__FUNCTION__])) {
return $implementation(get_called_class(), $params);
}
$class = get_called_class();
$method = __FUNCTION__;
$data = array_merge(static::$_methodFilters[__FUNCTION__], array($implementation));
return Filters::run($class, $params, compact('data', 'class', 'method'));
}
/**
* Executes a set of filters against a method by taking a method's main implementation as a
* callback, and iteratively wrapping the filters around it. This, along with the `Filters`
* class, is the core of Lithium's filters system. This system allows you to "reach into" an
* object's methods which are marked as _filterable_, and intercept calls to those methods,
* optionally modifying parameters or return values.
*
* @see lithium\core\Object::applyFilter()
* @see lithium\util\collection\Filters
* @param string $method The name of the method being executed, usually the value of
* `__METHOD__`.
* @param array $params An associative array containing all the parameters passed into
* the method.
* @param Closure $callback The method's implementation, wrapped in a closure.
* @param array $filters Additional filters to apply to the method for this call only.
* @return mixed Returns the return value of `$callback`, modified by any filters passed in
* `$filters` or applied with `applyFilter()`.
*/
protected function _filter($method, $params, $callback, $filters = array())
{
list($class, $method) = explode('::', $method);
if (empty($this->_methodFilters[$method]) && empty($filters)) {
return $callback($this, $params, null);
}
$f = isset($this->_methodFilters[$method]) ? $this->_methodFilters[$method] : array();
$data = array_merge($f, $filters, array($callback));
return Filters::run($this, $params, compact('data', 'class', 'method'));
}
/**
* Executes a set of filters against a method by taking a method's main implementation as a
* callback, and iteratively wrapping the filters around it.
*
* @param string|array $method The name of the method being executed, or an array containing
* the name of the class that defined the method, and the method name.
* @param array $params An associative array containing all the parameters passed into
* the method.
* @param Closure $callback The method's implementation, wrapped in a closure.
* @param array $filters Additional filters to apply to the method for this call only.
* @return mixed
* @see lithium\util\collection\Filters
*/
protected static function _filter($method, $params, $callback, $filters = array())
{
if (!strpos($method, '::')) {
$class = get_called_class();
} else {
list($class, $method) = explode('::', $method);
}
if (empty(static::$_methodFilters[$class][$method]) && empty($filters)) {
return $callback->__invoke($class, $params, null);
}
if (!isset(static::$_methodFilters[$class][$method])) {
static::$_methodFilters += array($class => array());
static::$_methodFilters[$class][$method] = array();
}
$items = array_merge(static::$_methodFilters[$class][$method], $filters, array($callback));
return Filters::run($class, $params, compact('items', 'class', 'method'));
}
