MDL-52292 block testing generators: improve the API
[moodle.git] / lib / testing / generator / block_generator.php
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/>.
17 /**
18  * Block generator base class.
19  *
20  * @package    core
21  * @category   test
22  * @copyright  2012 Petr Skoda {@link http://skodak.org}
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 defined('MOODLE_INTERNAL') || die();
28 /**
29  * Block generator base class.
30  *
31  * Extend in blocks/xxxx/tests/generator/lib.php as class block_xxxx_generator.
32  *
33  * @package    core
34  * @category   test
35  * @copyright  2012 Petr Skoda {@link http://skodak.org}
36  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37  */
38 abstract class testing_block_generator extends component_generator_base {
39     /** @var number of created instances */
40     protected $instancecount = 0;
42     /**
43      * To be called from data reset code only,
44      * do not use in tests.
45      * @return void
46      */
47     public function reset() {
48         $this->instancecount = 0;
49     }
51     /**
52      * Returns block name
53      * @return string name of block that this class describes
54      * @throws coding_exception if class invalid
55      */
56     public function get_blockname() {
57         $matches = null;
58         if (!preg_match('/^block_([a-z0-9_]+)_generator$/', get_class($this), $matches)) {
59             throw new coding_exception('Invalid block generator class name: '.get_class($this));
60         }
62         if (empty($matches[1])) {
63             throw new coding_exception('Invalid block generator class name: '.get_class($this));
64         }
65         return $matches[1];
66     }
68     /**
69      * Fill in record defaults.
70      *
71      * @param stdClass $record
72      * @return stdClass
73      */
74     protected function prepare_record(stdClass $record) {
75         $record->blockname = $this->get_blockname();
76         if (!isset($record->parentcontextid)) {
77             $record->parentcontextid = context_system::instance()->id;
78         }
79         if (!isset($record->showinsubcontexts)) {
80             $record->showinsubcontexts = 0;
81         }
82         if (!isset($record->pagetypepattern)) {
83             $record->pagetypepattern = '*';
84         }
85         if (!isset($record->subpagepattern)) {
86             $record->subpagepattern = null;
87         }
88         if (!isset($record->defaultregion)) {
89             $record->defaultregion = 'side-pre';
90         }
91         if (!isset($record->defaultweight)) {
92             $record->defaultweight = 5;
93         }
94         if (!isset($record->configdata)) {
95             $record->configdata = null;
96         }
97         return $record;
98     }
100     /**
101      * Create a test block instance.
102      *
103      * The $record passed in becomes the basis for the new row added to the
104      * block_instances table. You only need to supply the values of interest.
105      * Any missing values have sensible defaults filled in.
106      *
107      * The $options array provides additional data, not directly related to what
108      * will be inserted in the block_instance table, which may affect the block
109      * that is created. The meanings of any data passed here depends on the particular
110      * type of block being created.
111      *
112      * @param array|stdClass $record forms the basis for the entry to be inserted in the block_instances table.
113      * @param array $options further, block-specific options to control how the block is created.
114      * @return stdClass the block_instance record that has just been created.
115      */
116     public function create_instance($record = null, $options = array()) {
117         global $DB;
119         $this->instancecount++;
121         $record = (object)(array)$record;
122         $this->preprocess_record($record, $options);
123         $record = $this->prepare_record($record);
125         $id = $DB->insert_record('block_instances', $record);
126         context_block::instance($id);
128         $instance = $DB->get_record('block_instances', array('id' => $id), '*', MUST_EXIST);
129         return $instance;
130     }
132     /**
133      * Can be overridden to do block-specific processing. $record can be modified
134      * in-place.
135      *
136      * @param stdClass $record the data, before defaults are filled in.
137      * @param array $options further, block-specific options, as passed to {@link create_instance()}.
138      */
139     protected function preprocess_record(stdClass $record, array $options) {
140     }