[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\helpers\database;
  23  
  24  /**
  25   * Select report filter
  26   *
  27   * The options for the select are defined when creating the filter by calling {@see set_options} or {@see set_options_callback}
  28   *
  29   * To extend this class in your own filter (e.g. to pre-populate available options), you should override the {@see get_operators}
  30   * and/or {@see get_select_options} methods
  31   *
  32   * @package     core_reportbuilder
  33   * @copyright   2021 David Matamoros <davidmc@moodle.com>
  34   * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  35   */
  36  class select extends base {
  37  
  38      /** @var int Any value */
  39      public const ANY_VALUE = 0;
  40  
  41      /** @var int Equal to */
  42      public const EQUAL_TO = 1;
  43  
  44      /** @var int Not equal to */
  45      public const NOT_EQUAL_TO = 2;
  46  
  47      /**
  48       * Returns an array of comparison operators
  49       *
  50       * @return array
  51       */
  52      protected function get_operators(): array {
  53          $operators = [
  54              self::ANY_VALUE => get_string('filterisanyvalue', 'core_reportbuilder'),
  55              self::EQUAL_TO => get_string('filterisequalto', 'core_reportbuilder'),
  56              self::NOT_EQUAL_TO => get_string('filterisnotequalto', 'core_reportbuilder')
  57          ];
  58  
  59          return $this->filter->restrict_limited_operators($operators);
  60      }
  61  
  62      /**
  63       * Return the options for the filter as an array, to be used to populate the select input field
  64       *
  65       * @return array
  66       */
  67      protected function get_select_options(): array {
  68          return (array) $this->filter->get_options();
  69      }
  70  
  71      /**
  72       * Adds controls specific to this filter in the form.
  73       *
  74       * @param MoodleQuickForm $mform
  75       */
  76      public function setup_form(MoodleQuickForm $mform): void {
  77          $elements = [];
  78          $elements['operator'] = $mform->createElement('select', $this->name . '_operator',
  79              get_string('filterfieldoperator', 'core_reportbuilder', $this->get_header()), $this->get_operators());
  80  
  81          // If a multi-dimensional array is passed, we need to use a different element type.
  82          $options = $this->get_select_options();
  83          $element = (count($options) == count($options, COUNT_RECURSIVE) ? 'select' : 'selectgroups');
  84          $elements['value'] = $mform->createElement($element, $this->name . '_value',
  85              get_string('filterfieldvalue', 'core_reportbuilder', $this->get_header()), $options);
  86  
  87          $mform->addElement('group', $this->name . '_group', '', $elements, '', false);
  88  
  89          $mform->hideIf($this->name . '_value', $this->name . '_operator', 'eq', self::ANY_VALUE);
  90      }
  91  
  92      /**
  93       * Return filter SQL
  94       *
  95       * Note that operators must be of type integer, while values can be integer or string.
  96       *
  97       * @param array $values
  98       * @return array array of two elements - SQL query and named parameters
  99       */
 100      public function get_sql_filter(array $values): array {
 101          $name = database::generate_param_name();
 102  
 103          $operator = $values["{$this->name}_operator"] ?? self::ANY_VALUE;
 104          $value = $values["{$this->name}_value"] ?? 0;
 105  
 106          $fieldsql = $this->filter->get_field_sql();
 107          $params = $this->filter->get_field_params();
 108  
 109          // Validate filter form values.
 110          if (!$this->validate_filter_values((int) $operator, $value)) {
 111              // Filter configuration is invalid. Ignore the filter.
 112              return ['', []];
 113          }
 114  
 115          switch ($operator) {
 116              case self::EQUAL_TO:
 117                  $fieldsql .= "=:$name";
 118                  $params[$name] = $value;
 119                  break;
 120              case self::NOT_EQUAL_TO:
 121                  $fieldsql .= "<>:$name";
 122                  $params[$name] = $value;
 123                  break;
 124              default:
 125                  return ['', []];
 126          }
 127          return [$fieldsql, $params];
 128      }
 129  
 130      /**
 131       * Validate filter form values
 132       *
 133       * @param int|null $operator
 134       * @param mixed|null $value
 135       * @return bool
 136       */
 137      private function validate_filter_values(?int $operator, $value): bool {
 138          return !($operator === null || $value === '');
 139      }
 140  
 141      /**
 142       * Return sample filter values
 143       *
 144       * @return array
 145       */
 146      public function get_sample_values(): array {
 147          return [
 148              "{$this->name}_operator" => self::EQUAL_TO,
 149              "{$this->name}_value" => 1,
 150          ];
 151      }
 152  }