first commit

lib/classes/dml/recordset_walk.php

@@ -0,0 +1,163 @@
+<?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/>.
+
+/**
+ * Applies the same callback to all recorset records.
+ *
+ * @since      Moodle 2.9
+ * @package    core
+ * @category   dml
+ * @copyright  2015 David Monllao
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core\dml;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Iterator that walks through a moodle_recordset applying the provided function.
+ *
+ * The internal recordset can be closed using the close() function.
+ *
+ * Note that consumers of this class are responsible of closing the recordset,
+ * although there are some implicit closes under some ciscumstances:
+ * - Once all recordset records have been iterated
+ * - The object is destroyed
+ *
+ * @since      Moodle 2.9
+ * @package    core
+ * @category   dml
+ * @copyright  2015 David Monllao
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class recordset_walk implements \Iterator {
+
+    /**
+     * @var \moodle_recordset The recordset.
+     */
+    protected $recordset;
+
+    /**
+     * @var callable The callback.
+     */
+    protected $callback;
+
+    /**
+     * @var mixed|null Extra param for the callback.
+     */
+    protected $callbackextra;
+
+    /**
+     * Create a new iterator applying the callback to each record.
+     *
+     * @param \moodle_recordset $recordset Recordset to iterate.
+     * @param callable $callback Apply this function to each record. If using a method, it should be public.
+     * @param mixed $callbackextra An extra single parameter to pass to the callback. Use a container to pass multiple values.
+     */
+    public function __construct(\moodle_recordset $recordset, callable $callback, $callbackextra = null) {
+        $this->recordset = $recordset;
+        $this->callback = $callback;
+        $this->callbackextra = $callbackextra;
+    }
+
+    /**
+     * Closes the recordset.
+     *
+     * @return void
+     */
+    public function __destruct() {
+        $this->close();
+    }
+
+    /**
+     * Returns the current element after applying the callback.
+     *
+     * @return mixed|bool The returned value type will depend on the callback.
+     */
+    #[\ReturnTypeWillChange]
+    public function current() {
+
+        if (!$this->recordset->valid()) {
+            return false;
+        }
+
+        if (!$record = $this->recordset->current()) {
+            return false;
+        }
+
+        // Apply callback and return.
+        if (!is_null($this->callbackextra)) {
+            return call_user_func($this->callback, $record, $this->callbackextra);
+        } else {
+            return call_user_func($this->callback, $record);
+        }
+    }
+
+    /**
+     * Moves the internal pointer to the next record.
+     *
+     * @return void
+     */
+    public function next(): void {
+        $this->recordset->next();
+    }
+
+    /**
+     * Returns current record key.
+     *
+     * @return int
+     */
+    #[\ReturnTypeWillChange]
+    public function key() {
+        return $this->recordset->key();
+    }
+
+    /**
+     * Returns whether the current position is valid or not.
+     *
+     * If we reached the end of the recordset we close as we
+     * don't allow rewinds. Doing do so we reduce the chance
+     * of unclosed recordsets.
+     *
+     * @return bool
+     */
+    public function valid(): bool {
+        if (!$valid = $this->recordset->valid()) {
+            $this->close();
+        }
+        return $valid;
+    }
+
+    /**
+     * Rewind is not supported.
+     *
+     * @return void
+     */
+    public function rewind(): void {
+        // No rewind as it is not implemented in moodle_recordset.
+        return;
+    }
+
+    /**
+     * Closes the recordset.
+     *
+     * @return void
+     */
+    public function close() {
+        $this->recordset->close();
+    }
+}

lib/classes/dml/sql_join.php

@@ -0,0 +1,92 @@
+<?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/>.
+
+/**
+ * An object that contains sql join fragments.
+ *
+ * @since      Moodle 3.1
+ * @package    core
+ * @category   dml
+ * @copyright  2016 The Open University
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core\dml;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * An object that contains sql join fragments.
+ *
+ * An example of how to use this class in a simple query, where you have got
+ * a join that is a join to the user table:
+ *
+ * $users = $DB->get_records_sql("SELECT u.*
+ *         FROM {user} u
+ *         {$sqljoin->joins}
+ *         WHERE {$sqljoin->wheres}", $sqljoin->params);
+ *
+ * @since      Moodle 3.1
+ * @package    core
+ * @category   dml
+ * @copyright  2016 The Open University
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class sql_join {
+
+    /**
+     * @var string joins.
+     */
+    public $joins;
+
+    /**
+     * @var string wheres.
+     */
+    public $wheres;
+
+    /**
+     * @var array params.
+     */
+    public $params;
+
+    /**
+     * @var bool if true this join is guaranteed to never match any rows.
+     *      In this case, the calling code may be able to completely
+     *      skip doing the database query.
+     * @since Moodle 3.9/3.8.3/3.7.6.
+     */
+    public $cannotmatchanyrows;
+
+    /**
+     * Create an object that contains sql join fragments.
+     *
+     * Note, even if you set $cannotmatchanyrows to true, it is
+     * important to also set the other fields because the calling
+     * code is not required to check it. For example
+     * new \core\dml\sql_join('', '1 = 2', [], true);
+     *
+     * @param string $joins The join sql fragment.
+     * @param string $wheres The where sql fragment.
+     * @param array $params Any parameter values.
+     * @param bool $cannotmatchanyrows If true, this join is guaranteed to match no rows. See comment on the field above.
+     */
+    public function __construct($joins = '', $wheres = '', $params = array(), $cannotmatchanyrows = false) {
+        $this->joins = $joins;
+        $this->wheres = $wheres;
+        $this->params = $params;
+        $this->cannotmatchanyrows = $cannotmatchanyrows;
+    }
+}

lib/classes/dml/table.php

@@ -0,0 +1,133 @@
+<?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/>.
+
+/**
+ * Helpers and methods relating to DML tables.
+ *
+ * @since      Moodle 3.7
+ * @package    core
+ * @category   dml
+ * @copyright  2019 Andrew Nicols <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+namespace core\dml;
+
+use stdClass;
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * Helpers and methods relating to DML tables.
+ *
+ * @copyright  2019 Andrew Nicols <andrew@nicols.co.uk>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class table {
+
+    /** @var string Name of the table that this class represents */
+    protected $tablename;
+
+    /** @var string Table alias */
+    protected $tablealias;
+
+    /** @var string Prefix to place before each field */
+    protected $fieldprefix;
+
+    /** @var array List of fields */
+    protected $fields;
+
+    /**
+     * Constructor for the table class.
+     *
+     * @param   string  $tablename The name of the table that this instance represents.
+     * @param   string  $tablealias The alias to use when selecting the table
+     * @param   string  $fieldprefix The prefix to use when selecting fields.
+     */
+    public function __construct(string $tablename, string $tablealias, string $fieldprefix) {
+        $this->tablename = $tablename;
+        $this->tablealias = $tablealias;
+        $this->fieldprefix = $fieldprefix;
+    }
+
+    /**
+     * Get the from TABLE ALIAS part of the FROM/JOIN string.
+     *
+     * @return  string
+     */
+    public function get_from_sql(): string {
+        return "{{$this->tablename}} {$this->tablealias}";
+    }
+
+    /**
+     * Get the list of fields in a table for use in preloading fields.
+     *
+     * @return  array       The list of columns in a table. The array key is the column name with an applied prefix.
+     */
+    protected function get_fieldlist(): array {
+        global $DB;
+
+        if (null === $this->fields) {
+            $fields = [];
+            foreach (array_keys($DB->get_columns($this->tablename)) as $fieldname) {
+                $fields["{$this->fieldprefix}{$fieldname}"] = $fieldname;
+            }
+
+            $this->fields = $fields;
+        }
+
+        return $this->fields;
+    }
+
+    /**
+     * Get the SELECT SQL to select a set of columns for this table.
+     *
+     * This function is intended to be used in combination with extract_from_result().
+     *
+     * @return  string      The SQL to use in the SELECT
+     */
+    public function get_field_select(): string {
+        $fieldlist = $this->get_fieldlist();
+
+        return implode(', ', array_map(function($fieldname, $fieldalias) {
+            return "{$this->tablealias}.{$fieldname} AS {$fieldalias}";
+        }, $fieldlist, array_keys($fieldlist)));
+    }
+
+    /**
+     * Extract fields from the specified result. The fields are removed from the original object.
+     *
+     * This function is intended to be used in combination with get_field_select().
+     *
+     * @param   stdClass    $result The result retrieved from the database with fields to be extracted
+     * @return  stdClass    The extracted result
+     */
+    public function extract_from_result(stdClass $result): stdClass {
+        $record = new stdClass();
+
+        $fieldlist = $this->get_fieldlist();
+        foreach ($fieldlist as $fieldalias => $fieldname) {
+            if (property_exists($result, $fieldalias)) {
+                $record->$fieldname = $result->$fieldalias;
+                unset($result->$fieldalias);
+            } else {
+                debugging("Field '{$fieldname}' not found", DEBUG_DEVELOPER);
+            }
+        }
+
+        return $record;
+    }
+}