[Summary view]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  declare(strict_types=1);
  18  
  19  namespace core_reportbuilder\local\filters;
  20  
  21  use MoodleQuickForm;
  22  use core_reportbuilder\local\report\filter;
  23  use core_reportbuilder\local\models\filter as filter_model;
  24  
  25  /**
  26   * Base class for all report filters
  27   *
  28   * Filters provide a form for collecting user input, and then return appropriate SQL fragments based on these values
  29   *
  30   * @package     core_reportbuilder
  31   * @copyright   2021 Paul Holden <paulh@moodle.com>
  32   * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  33   */
  34  abstract class base {
  35  
  36      /** @var filter $filter */
  37      protected $filter;
  38  
  39      /** @var string $name */
  40      protected $name;
  41  
  42      /**
  43       * Do not allow the constructor to be called directly or overridden
  44       *
  45       * @param filter $filter
  46       */
  47      private function __construct(filter $filter) {
  48          $this->filter = $filter;
  49          $this->name = $filter->get_unique_identifier();
  50      }
  51  
  52      /**
  53       * Creates an instance of a filter type, based on supplied report filter instance
  54       *
  55       * The report filter instance is used by reports/entities to define what should be filtered against, e.g. a SQL fragment
  56       *
  57       * @param filter $filter The report filter instance
  58       * @return static
  59       */
  60      final public static function create(filter $filter): self {
  61          $filterclass = $filter->get_filter_class();
  62  
  63          return new $filterclass($filter);
  64      }
  65  
  66      /**
  67       * Returns the filter header
  68       *
  69       * @return string
  70       */
  71      final public function get_header(): string {
  72          return $this->filter->get_header();
  73      }
  74  
  75      /**
  76       * Returns the filter's entity name
  77       *
  78       * @return string
  79       */
  80      final public function get_entity_name(): string {
  81          return $this->filter->get_entity_name();
  82      }
  83  
  84      /**
  85       * Returns the filter persistent
  86       *
  87       * Note that filters for system reports don't store a persistent and will return null.
  88       *
  89       * @return filter_model|null
  90       */
  91      final public function get_filter_persistent(): ?filter_model {
  92          return $this->filter->get_persistent();
  93      }
  94  
  95      /**
  96       * Adds filter-specific form elements
  97       *
  98       * @param MoodleQuickForm $mform
  99       */
 100      abstract public function setup_form(MoodleQuickForm $mform): void;
 101  
 102      /**
 103       * Returns the filter clauses to be used with SQL where
 104       *
 105       * Ideally the field SQL should be included only once in the returned expression, however if that is unavoidable then
 106       * use the {@see filter::get_field_sql_and_params} helper to ensure uniqueness of any parameters included within
 107       *
 108       * @param array $values
 109       * @return array [$sql, [...$params]]
 110       */
 111      abstract public function get_sql_filter(array $values): array;
 112  
 113      /**
 114       * Given an array of current filter values for the report, determine whether the filter would apply to the report (i.e. user
 115       * has configured it from it's initial "Any value" state). A filter would typically be considered applied if it returns SQL
 116       * filter clauses, but child classes may override this method if they use different logic
 117       *
 118       * @param array $values
 119       * @return bool
 120       */
 121      public function applies_to_values(array $values): bool {
 122          [$filtersql] = $this->get_sql_filter($values);
 123  
 124          return $filtersql !== '';
 125      }
 126  
 127      /**
 128       * Return sample filter values, that when applied to a report would activate the filter - that is, cause the filter to return
 129       * SQL snippet. Should be overridden in child classes, to ensure compatibility with stress tests of reports
 130       *
 131       * @return array
 132       */
 133      public function get_sample_values(): array {
 134          return [];
 135      }
 136  }