<?php // This file is part of Moodle - http://moodle.org/ // // Moodle is free software: you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by // the Free Software Foundation, either version 3 of the License, or // (at your option) any later version. // // Moodle is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with Moodle. If not, see <http://www.gnu.org/licenses/>. /** * Table filterset. * * @package core * @category table * @copyright 2020 Andrew Nicols <andrew@nicols.co.uk> * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ declare(strict_types=1); namespace core_table\local\filter; use InvalidArgumentException; use JsonSerializable; use UnexpectedValueException; use moodle_exception; /** * Class representing a set of filters. * * @package core * @copyright 2020 Andrew Nicols <andrew@nicols.co.uk> * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ abstract class filterset implements JsonSerializable { /** @var int The default filter type (ALL) */ const JOINTYPE_DEFAULT = 2; /** @var int None of the following match */ const JOINTYPE_NONE = 0; /** @var int Any of the following match */ const JOINTYPE_ANY = 1; /** @var int All of the following match */ const JOINTYPE_ALL = 2; /** @var int The join type currently in use */ protected $jointype = null; /** @var array The list of combined filter types */ protected $filtertypes = null; /** @var array The list of active filters */ protected $filters = []; /** @var int[] valid join types */ protected $jointypes = [ self::JOINTYPE_NONE, self::JOINTYPE_ANY, self::JOINTYPE_ALL, ]; /** * Specify the type of join to employ for the filter. * * @param int $jointype The join type to use using one of the supplied constants * @return self */ public function set_join_type(int $jointype): self { if (array_search($jointype, $this->jointypes) === false) { throw new InvalidArgumentException('Invalid join type specified'); } $this->jointype = $jointype; return $this; } /** * Return the currently specified join type. * * @return int */ public function get_join_type(): int { if ($this->jointype === null) { $this->jointype = self::JOINTYPE_DEFAULT; } return $this->jointype; } /** * Add the specified filter. * * @param filter $filter * @return self */ public function add_filter(filter $filter): self { $filtername = $filter->get_name(); if (array_key_exists($filtername, $this->filters)) { // This filter already exists. if ($this->filters[$filtername] === $filter) { // This is the same value as already added. // Just ignore it. return $this; } // This is a different value to last time. Fail as this is not supported. throw new UnexpectedValueException( "A filter of type '{$filtername}' has already been added. Check that you have the correct filter." ); } // Ensure that the filter is both known, and is of the correct type. $validtypes = $this->get_all_filtertypes(); if (!array_key_exists($filtername, $validtypes)) { // Unknown filter. throw new InvalidArgumentException( "The filter '{$filtername}' was not recognised." ); } // Check that the filter is of the correct type. if (!is_a($filter, $validtypes[$filtername])) { $actualtype = get_class($filter); $requiredtype = $validtypes[$filtername]; throw new InvalidArgumentException( "The filter '{$filtername}' was incorrectly specified as a {$actualtype}. It must be a {$requiredtype}." ); } // All good. Add the filter. $this->filters[$filtername] = $filter; return $this; } /** * Add the specified filter from the supplied params. * * @param string $filtername The name of the filter to create * @param mixed[] ...$args Additional arguments used to create this filter type * @return self */ public function add_filter_from_params(string $filtername, ...$args): self { // Fetch the list of valid filters by name. $validtypes = $this->get_all_filtertypes(); if (!array_key_exists($filtername, $validtypes)) { // Unknown filter. throw new InvalidArgumentException( "The filter '{$filtername}' was not recognised." ); } $filterclass = $validtypes[$filtername]; if (!class_exists($filterclass)) { // Filter class cannot be class autoloaded. throw new InvalidArgumentException( "The filter class '{$filterclass}' for filter '{$filtername}' could not be found." ); } // Pass all supplied arguments to the constructor when adding a new filter. // This allows for a wider definition of the the filter in child classes. $this->add_filter(new $filterclass($filtername, ...$args)); return $this; } /** * Return the current set of filters. * * @return filter[] */ public function get_filters(): array { // Sort the filters by their name to ensure consistent output. // Note: This is not a locale-aware sort, but we don't need this. // It's primarily for consistency, not for actual sorting. asort($this->filters); return $this->filters; } /** * Check whether the filter has been added or not. * * @param string $filtername * @return bool */ public function has_filter(string $filtername): bool { // We do not check if the filtername is valid, only that it exists. // This is an existence check and there is no benefit to doing any more. return array_key_exists($filtername, $this->filters); } /** * Get the named filter. * * @param string $filtername * @return filter */ public function get_filter(string $filtername): filter { if (!array_key_exists($filtername, $this->get_all_filtertypes())) { throw new UnexpectedValueException("The filter specified ({$filtername}) is invalid."); } if (!array_key_exists($filtername, $this->filters)) { throw new UnexpectedValueException("The filter specified ({$filtername}) has not been created."); } return $this->filters[$filtername]; } /** * Confirm whether the filter has been correctly specified. * * @throws moodle_exception */ public function check_validity(): void { // Ensure that all required filters are present. $missing = []; foreach (array_keys($this->get_required_filters()) as $filtername) { if (!array_key_exists($filtername, $this->filters)) { $missing[] = $filtername; } } if (!empty($missing)) { throw new moodle_exception( 'missingrequiredfields', 'core_table', '', implode(get_string('listsep', 'langconfig') . ' ', $missing) ); } } /** * Get the list of required filters in an array of filtername => filter class type. * * @return array */ protected function get_required_filters(): array { return []; } /** * Get the list of optional filters in an array of filtername => filter class type. * * @return array */ protected function get_optional_filters(): array { return []; } /** * Get all filter valid types in an array of filtername => filter class type. * * @return array */ public function get_all_filtertypes(): array { if ($this->filtertypes === null) { $required = $this->get_required_filters(); $optional = $this->get_optional_filters(); $conflicts = array_keys(array_intersect_key($required, $optional)); if (!empty($conflicts)) { throw new InvalidArgumentException( "Some filter types are both required, and optional: " . implode(', ', $conflicts) ); } $this->filtertypes = array_merge($required, $optional); asort($this->filtertypes); } return $this->filtertypes; } /** * Serialize filterset. * * @return mixed|object */> #[\ReturnTypeWillChange]public function jsonSerialize() { return (object) [ 'jointype' => $this->get_join_type(), 'filters' => $this->get_filters(), ]; } }