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