xref: /plugin/struct/helper.php (revision b9d35ff22b6a99d33aa2af304df64848b7983f3c)
1<?php
2/**
3 * DokuWiki Plugin struct (Helper Component)
4 *
5 * @license GPL 2 http://www.gnu.org/licenses/gpl-2.0.html
6 * @author  Andreas Gohr, Michael Große <dokuwiki@cosmocode.de>
7 */
8
9// must be run within Dokuwiki
10use dokuwiki\plugin\struct\meta\AccessDataValidator;
11use dokuwiki\plugin\struct\meta\AccessTable;
12use dokuwiki\plugin\struct\meta\AccessTableLookup;
13use dokuwiki\plugin\struct\meta\Assignments;
14use dokuwiki\plugin\struct\meta\Schema;
15use dokuwiki\plugin\struct\meta\StructException;
16
17if(!defined('DOKU_INC')) die();
18
19/**
20 * The public interface for the struct plugin
21 *
22 * 3rd party developers should always interact with struct data through this
23 * helper plugin only. If additionional interface functionality is needed,
24 * it should be added here.
25 *
26 * All functions will throw StructExceptions when something goes wrong.
27 *
28 * Remember to check permissions yourself!
29 */
30class helper_plugin_struct extends DokuWiki_Plugin {
31
32    /**
33     * Get the structured data of a given page
34     *
35     * @param string $page The page to get data for
36     * @param string|null $schema The schema to use null for all
37     * @param int $time A timestamp if you want historic data (0 for now)
38     * @return array ('schema' => ( 'fieldlabel' => 'value', ...))
39     * @throws StructException
40     */
41    public function getData($page, $schema = null, $time = 0) {
42        $page = cleanID($page);
43
44        if(is_null($schema)) {
45            $assignments = Assignments::getInstance();
46            $schemas = $assignments->getPageAssignments($page, false);
47        } else {
48            $schemas = array($schema);
49        }
50
51        $result = array();
52        foreach($schemas as $schema) {
53            $schemaData = AccessTable::byTableName($schema, $page, $time);
54            $result[$schema] = $schemaData->getDataArray();
55        }
56
57        return $result;
58    }
59
60    /**
61     * Saves data for a given page (creates a new revision)
62     *
63     * If this call succeeds you can assume your data has either been saved or it was
64     * not necessary to save it because the data already existed in the wanted form or
65     * the given schemas are no longer assigned to that page.
66     *
67     * Important: You have to check write permissions for the given page before calling
68     * this function yourself!
69     *
70     * this duplicates a bit of code from entry.php - we could also fake post data and let
71     * entry handle it, but that would be rather unclean and might be problematic when multiple
72     * calls are done within the same request.
73     *
74     * @todo should this try to lock the page?
75     *
76     *
77     * @param string $page
78     * @param array $data ('schema' => ( 'fieldlabel' => 'value', ...))
79     * @param string $summary
80     * @param string $summary
81     * @throws StructException
82     */
83    public function saveData($page, $data, $summary = '', $minor = false)
84    {
85        $page = cleanID($page);
86        $summary = trim($summary);
87        if(!$summary) $summary = $this->getLang('summary');
88
89        if(!page_exists($page)) throw new StructException("Page does not exist. You can not attach struct data");
90
91        // validate and see if anything changes
92        $valid = AccessDataValidator::validateDataForPage($data, $page, $errors);
93        if($valid === false) {
94            throw new StructException("Validation failed:\n%s", join("\n", $errors));
95        }
96        if(!$valid) return; // empty array when no changes were detected
97
98        $newrevision = self::createPageRevision($page, $summary, $minor);
99
100        // save the provided data
101        $assignments = Assignments::getInstance();
102        foreach($valid as $v) {
103            $v->saveData($newrevision);
104            // make sure this schema is assigned
105            $assignments->assignPageSchema($page, $v->getAccessTable()->getSchema()->getTable());
106        }
107    }
108
109    /**
110     * Save data row for a lookup schema
111     *
112     * @param AccessTable        $access the table into which to save the data
113     * @param array             $data   data to be saved in the form of [columnName => 'data']
114     */
115    public function saveLookupData(AccessTable $access, $data)
116    {
117        if(!$access->getSchema()->isEditable()) {
118            throw new StructException('lookup save error: no permission for schema');
119        }
120        $validator = $access->getValidator($data);
121        if(!$validator->validate()) {
122            throw new StructException("Validation failed:\n%s", implode("\n", $validator->getErrors()));
123        }
124        if(!$validator->saveData()) {
125            throw new StructException('No data saved');
126        }
127    }
128
129    /**
130     * Save data row for a lookup schema
131     *
132     * @param AccessTable        $access the table into which to save the data
133     * @param array             $data   data to be saved in the form of [columnName => 'data']
134     */
135    public function saveSerialData(AccessTable $access, $data)
136    {
137        if(!$access->getSchema()->isEditable()) {
138            throw new StructException('serial save error: no permission for schema');
139        }
140        $validator = $access->getValidator($data);
141        if(!$validator->validate()) {
142            throw new StructException("Validation failed:\n%s", implode("\n", $validator->getErrors()));
143        }
144        if(!$validator->saveData()) {
145            throw new StructException('No data saved');
146        }
147    }
148
149    /**
150     * Creates a new page revision with the same page content as before
151     *
152     * @param string $page
153     * @param string $summary
154     * @param bool $minor
155     * @return int the new revision
156     */
157    static public function createPageRevision($page, $summary = '', $minor = false) {
158        $summary = trim($summary);
159        // force a new page revision @see action_plugin_struct_entry::handle_pagesave_before()
160        $GLOBALS['struct_plugin_force_page_save'] = true;
161        saveWikiText($page, rawWiki($page), $summary, $minor);
162        unset($GLOBALS['struct_plugin_force_page_save']);
163        $file = wikiFN($page);
164        clearstatcache(false, $file);
165        return filemtime($file);
166    }
167
168    /**
169     * Get info about existing schemas
170     *
171     * @param string|null $schema the schema to query, null for all
172     * @return Schema[]
173     * @throws StructException
174     */
175    public function getSchema($schema = null) {
176        if(is_null($schema)) {
177            $schemas = Schema::getAll();
178        } else {
179            $schemas = array($schema);
180        }
181
182        $result = array();
183        foreach($schemas as $table) {
184            $result[$table] = new Schema($table);
185        }
186        return $result;
187    }
188
189    /**
190     * Returns all pages known to the struct plugin
191     *
192     * That means all pages that have or had once struct data saved
193     *
194     * @param string|null $schema limit the result to a given schema
195     * @return array (page => (schema => true), ...)
196     * @throws StructException
197     */
198    public function getPages($schema = null) {
199        $assignments = Assignments::getInstance();
200        return $assignments->getPages($schema);
201    }
202
203}
204