MDL-52292 block testing generators: improve the API
[moodle.git] / lib / testing / generator / block_generator.php
CommitLineData
7e7cfe7a
PS
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/**
18 * Block generator base class.
19 *
20 * @package core
6b219869 21 * @category test
7e7cfe7a
PS
22 * @copyright 2012 Petr Skoda {@link http://skodak.org}
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 */
25
c29e3e24 26defined('MOODLE_INTERNAL') || die();
7e7cfe7a
PS
27
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
6b219869 34 * @category test
7e7cfe7a
PS
35 * @copyright 2012 Petr Skoda {@link http://skodak.org}
36 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37 */
ba203de1 38abstract class testing_block_generator extends component_generator_base {
7e7cfe7a
PS
39 /** @var number of created instances */
40 protected $instancecount = 0;
41
7e7cfe7a
PS
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 }
50
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 }
61
62 if (empty($matches[1])) {
63 throw new coding_exception('Invalid block generator class name: '.get_class($this));
64 }
65 return $matches[1];
66 }
67
68 /**
eb3884e4
TH
69 * Fill in record defaults.
70 *
7e7cfe7a
PS
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)) {
eb3884e4 80 $record->showinsubcontexts = 0;
7e7cfe7a
PS
81 }
82 if (!isset($record->pagetypepattern)) {
eb3884e4 83 $record->pagetypepattern = '*';
7e7cfe7a
PS
84 }
85 if (!isset($record->subpagepattern)) {
86 $record->subpagepattern = null;
87 }
88 if (!isset($record->defaultregion)) {
eb3884e4 89 $record->defaultregion = 'side-pre';
7e7cfe7a
PS
90 }
91 if (!isset($record->defaultweight)) {
eb3884e4 92 $record->defaultweight = 5;
7e7cfe7a
PS
93 }
94 if (!isset($record->configdata)) {
95 $record->configdata = null;
96 }
97 return $record;
98 }
99
100 /**
eb3884e4
TH
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.
7e7cfe7a 115 */
eb3884e4
TH
116 public function create_instance($record = null, $options = array()) {
117 global $DB;
118
119 $this->instancecount++;
120
121 $record = (object)(array)$record;
122 $this->preprocess_record($record, $options);
123 $record = $this->prepare_record($record);
124
125 $id = $DB->insert_record('block_instances', $record);
126 context_block::instance($id);
127
128 $instance = $DB->get_record('block_instances', array('id' => $id), '*', MUST_EXIST);
129 return $instance;
130 }
131
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 }
7e7cfe7a 141}