xref: /plugin/struct/helper.php (revision 9914e87efa9c3f3c75f0e56619423f12ea7ca649) 
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 plugin\struct\meta\Assignments;
11use plugin\struct\meta\Schema;
12use plugin\struct\meta\SchemaData;
13use plugin\struct\meta\StructException;
14use plugin\struct\meta\Validator;
15
16if(!defined('DOKU_INC')) die();
17
18/**
19 * The public interface for the struct plugin
20 *
21 * 3rd party developers should always interact with struct data through this
22 * helper plugin only. If additionional interface functionality is needed,
23 * it should be added here.
24 *
25 * All functions will throw StructExceptions when something goes wrong.
26 *
27 * Remember to check permissions yourself!
28 */
29class helper_plugin_struct extends DokuWiki_Plugin {
30
31    /**
32     * Get the structured data of a given page
33     *
34     * @param string $page The page to get data for
35     * @param string|null $schema The schema to use null for all
36     * @param int $time A timestamp if you want historic data (0 for now)
37     * @return array ('schema' => ( 'fieldlabel' => 'value', ...))
38     * @throws StructException
39     */
40    public function getData($page, $schema=null, $time=0) {
41        $page = cleanID($page);
42
43        if(is_null($schema)) {
44            $assignments = new Assignments();
45            $schemas = $assignments->getPageAssignments($page, false);
46        } else {
47            $schemas = array($schema);
48        }
49
50        $result = array();
51        foreach($schemas as $schema) {
52            $schemaData = new SchemaData($schema, $page, $time);
53            $result[$schema] = $schemaData->getDataArray(false);
54        }
55
56        return $result;
57    }
58
59    /**
60     * Saves data for a given page (creates a new revision)
61     *
62     * If this call succeeds you can assume your data has either been saved or it was
63     * not necessary to save it because the data already existed in the wanted form or
64     * the given schemas are no longer assigned to that page.
65     *
66     * Important: You have to check write permissions for the given page before calling
67     * this function yourself!
68     *
69     * this duplicates a bit of code from entry.php - we could also fake post data and let
70     * entry handle it, but that would be rather unclean and might be problematic when multiple
71     * calls are done within the same request.
72     *
73     * @todo should this try to lock the page?
74     *
75     *
76     * @param string $page
77     * @param array $data ('schema' => ( 'fieldlabel' => 'value', ...))
78     * @param string $summary
79     * @throws StructException
80     */
81    public function saveData($page, $data, $summary='') {
82        $page = cleanID($page);
83        $summary = trim($summary);
84        if(!$summary) $summary = $this->getLang('summary');
85
86        if(!page_exists($page)) throw new StructException("Page does not exist. You can not attach struct data");
87
88        // validate and see if anything changes
89        $validator = new Validator();
90        if(!$validator->validate($data, $page)) {
91            throw new StructException("Validation failed:\n%s", join("\n", $validator->getErrors()));
92        }
93        $data = $validator->getCleanedData();
94        $tosave = $validator->getChangedSchemas();
95        if(!$tosave) return;
96
97        // force a new page revision @see action_plugin_struct_entry::handle_pagesave_before()
98        $GLOBALS['struct_plugin_force_page_save'] = true;
99        saveWikiText($page, rawWiki($page), $summary);
100        unset($GLOBALS['struct_plugin_force_page_save']);
101        $file = wikiFN($page);
102        clearstatcache(false, $file);
103        $newrevision = filemtime($file);
104
105        // save the provided data
106        $assignments = new Assignments();
107        foreach($tosave as $table) {
108            $schemaData = new SchemaData($table, $page, $newrevision);
109            $schemaData->saveData($data[$table]);
110            // make sure this schema is assigned
111            $assignments->assignPageSchema($page, $table);
112        }
113    }
114
115    /**
116     * Get info about existing schemas
117     *
118     * @param string|null $schema the schema to query, null for all
119     * @return Schema[]
120     * @throws StructException
121     */
122    public function getSchema($schema=null) {
123        if(is_null($schema)) {
124            $schemas = Schema::getAll();
125        } else {
126            $schemas = array($schema);
127        }
128
129        $result = array();
130        foreach($schemas as $table) {
131            $result[$table] = new Schema($table);
132        }
133        return $result;
134    }
135
136    /**
137     * Returns all pages known to the struct plugin
138     *
139     * That means all pages that have or had once struct data saved
140     *
141     * @param string|null $schema limit the result to a given schema
142     * @return array (page => (schema => true), ...)
143     * @throws StructException
144     */
145    public function getPages($schema=null) {
146        $assignments = new Assignments();
147        return $assignments->getPages($schema);
148    }
149
150}
151