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
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 */
25
26defined('MOODLE_INTERNAL') || die();
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
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 */
38abstract class testing_block_generator extends component_generator_base {
39    /** @var number of created instances */
40    protected $instancecount = 0;
41
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    /**
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    }
99
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, $PAGE;
118
119        $this->instancecount++;
120
121        // Creating a block is a back end operation, which should not cause any output to happen.
122        // This will allow us to check that the theme was not initialised while creating the block instance.
123        $outputstartedbefore = $PAGE->get_where_theme_was_initialised();
124
125        $record = (object)(array)$record;
126        $this->preprocess_record($record, $options);
127        $record = $this->prepare_record($record);
128
129        if (empty($record->timecreated)) {
130            $record->timecreated = time();
131        }
132        if (empty($record->timemodified)) {
133            $record->timemodified = time();
134        }
135
136        $id = $DB->insert_record('block_instances', $record);
137        context_block::instance($id);
138
139        $instance = $DB->get_record('block_instances', array('id' => $id), '*', MUST_EXIST);
140
141        // If the theme was initialised while creating the block instance, something somewhere called an output
142        // function. Rather than leaving this as a hard-to-debug situation, let's make it fail with a clear error.
143        $outputstartedafter = $PAGE->get_where_theme_was_initialised();
144
145        if ($outputstartedbefore === null && $outputstartedafter !== null) {
146            throw new coding_exception('Creating a block_' . $this->get_blockname() . ' initialised the theme and output!',
147                'This should not happen. Creating a block should be a pure back-end operation. Unnecessarily initialising ' .
148                'the output mechanism at the wrong time can cause subtle bugs and is a significant performance hit. There is ' .
149                'likely a call to an output function that caused it:' . PHP_EOL . PHP_EOL .
150                format_backtrace($outputstartedafter, true));
151        }
152
153        return $instance;
154    }
155
156    /**
157     * Can be overridden to do block-specific processing. $record can be modified
158     * in-place.
159     *
160     * @param stdClass $record the data, before defaults are filled in.
161     * @param array $options further, block-specific options, as passed to {@link create_instance()}.
162     */
163    protected function preprocess_record(stdClass $record, array $options) {
164    }
165}
166