1: <?php
  2: /**
  3:  * Wicked external API interface.
  4:  *
  5:  * This file defines Wicked's external API interface. Other applications
  6:  * can interact with Wicked through this API.
  7:  *
  8:  * Copyright 2010-2012 Horde LLC (http://www.horde.org/)
  9:  *
 10:  * See the enclosed file COPYING for license information (GPL). If you
 11:  * did not receive this file, see http://www.horde.org/licenses/gpl.
 12:  *
 13:  * @package Wicked
 14:  */
 15: class Wicked_Api extends Horde_Registry_Api
 16: {
 17:     /**
 18:      * Links.
 19:      *
 20:      * @var array
 21:      */
 22:     public $links = array(
 23:         'show' => '%application%/display.php?page=|page|&version=|version|#|toc|'
 24:     );
 25: 
 26:     /**
 27:      * Returns a list of available pages.
 28:      *
 29:      * @param boolean $special Include special pages
 30:      * @param boolean $no_cache Always retreive pages from backed
 31:      *
 32:      * @return array  An array of all available pages.
 33:      */
 34:     public function listPages($special = true, $no_cache = false)
 35:     {
 36:         return $GLOBALS['wicked']->getPages($special, $no_cache);
 37:     }
 38: 
 39:     /**
 40:      * Return basic page information.
 41:      *
 42:      * @param string $pagename Page name
 43:      *
 44:      * @return array  An array of page parameters.
 45:      * @throws Wicked_Exception
 46:      */
 47:     public function getPageInfo($pagename)
 48:     {
 49:         $page = Wicked_Page::getPage($pagename);
 50:         return array(
 51:             'page_version' => $page->_page['page_version'],
 52:             'page_checksum' => md5($page->getText()),
 53:             'version_created' => $page->_page['version_created'],
 54:             'change_author' => $page->_page['change_author'],
 55:             'change_log' => $page->_page['change_log'],
 56:         );
 57:     }
 58: 
 59:     /**
 60:      * Return basic information for multiple pages.
 61:      *
 62:      * @param array $pagenames Page names
 63:      *
 64:      * @return array  An array of arrays of page parameters.
 65:      * @throws Wicked_Exception
 66:      */
 67:     public function getMultiplePageInfo($pagenames = array())
 68:     {
 69:         require_once dirname(__FILE__) . '/base.php';
 70: 
 71:         if (empty($pagenames)) {
 72:             $pagenames = $GLOBALS['wicked']->getPages(false);
 73:         }
 74: 
 75:         $info = array();
 76: 
 77:         foreach ($pagenames as $pagename) {
 78:             $page = Wicked_Page::getPage($pagename);
 79:             $info[$pagename] = array(
 80:                 'page_version' => $page->_page['page_version'],
 81:                 'page_checksum' => md5($page->getText()),
 82:                 'version_created' => $page->_page['version_created'],
 83:                 'change_author' => $page->_page['change_author'],
 84:                 'change_log' => $page->_page['change_log']
 85:             );
 86:         }
 87: 
 88:         return $info;
 89:     }
 90: 
 91:     /**
 92:      * Return page history.
 93:      *
 94:      * @param string $pagename Page name
 95:      *
 96:      * @return array  An array of page parameters.
 97:      * @throws Wicked_Exception
 98:      */
 99:     public function getPageHistory($pagename)
100:     {
101:         $page = Wicked_Page::getPage($pagename);
102:         $summaries = $GLOBALS['wicked']->getHistory($pagename);
103: 
104:         foreach ($summaries as $i => $summary) {
105:             $summaries[$i]['page_checksum'] = md5($summary['page_text']);
106:             unset($summaries[$i]['page_text']);
107:         }
108: 
109:         return $summaries;
110:     }
111: 
112:     /**
113:      * Chech if a page exists
114:      *
115:      * @param string $pagename Page name
116:      *
117:      * @return boolean
118:      */
119:     public function pageExists($pagename)
120:     {
121:         return $GLOBALS['wicked']->pageExists($pagename);
122:     }
123: 
124:     /**
125:      * Returns a rendered wiki page.
126:      *
127:      * @param string $pagename Page to display
128:      *
129:      * @return array  Page without CSS link
130:      * @throws Wicked_Exception
131:      */
132:     public function display($pagename)
133:     {
134:         $page = Wicked_Page::getPage($pagename);
135:         $GLOBALS['wicked']->logPageView($page->pageName());
136:         return $page->displayContents(false);
137:     }
138: 
139:     /**
140:      * Returns a rendered wiki page.
141:      *
142:      * @param string $pagename Page to display
143:      * @param string $format Format to render page to (Plain, XHtml)
144:      *
145:      * @return array  Rendered page
146:      * @throws Wicked_Exception
147:      */
148:     public function renderPage($pagename, $format = 'Plain')
149:     {
150:         $page = Wicked_Page::getPage($pagename);
151:         $content = $page->getProcessor()->transform($page->getText(), $format);
152:         $GLOBALS['wicked']->logPageView($page->pageName());
153:         return $content;
154:     }
155: 
156:     /**
157:      * Updates content of a wiki page. If the page does not exist it is
158:      * created.
159:      *
160:      * @param string $pagename Page to edit
161:      * @param string $text Page content
162:      * @param string $changelog Description of the change
163:      *
164:      * @throws Wicked_Exception
165:      */
166:     public function edit($pagename, $text, $changelog = '')
167:     {
168:         $page = Wicked_Page::getPage($pagename);
169:         if (!$page->allows(Wicked::MODE_EDIT)) {
170:             throw new Wicked_Exception(sprintf(_("You don't have permission to edit \"%s\"."), $pagename));
171:         }
172:         if ($GLOBALS['conf']['wicked']['require_change_log'] &&
173:             empty($changelog)) {
174:             throw new Wicked_Exception(_("You must provide a change log."));
175:         }
176: 
177:         try {
178:             $content = $page->getText();
179:         } catch (Wicked_Exception $e) {
180:             // Maybe the page does not exists, if not create it
181:             if ($GLOBALS['wicked']->pageExists($pagename)) {
182:                 throw $e;
183:             }
184:             $GLOBALS['wicked']->newPage($pagename, $text);
185:         }
186: 
187:         if (trim($text) == trim($content)) {
188:             throw new Wicked_Exception(_("No changes made"));
189:         }
190: 
191:         $page->updateText($text, $changelog);
192:     }
193: 
194:     /**
195:      * Get a list of templates provided by Wicked.  A template is any page
196:      * whose name begins with "Template"
197:      *
198:      * @return arrary  Array on success.
199:      * @throws Wicked_Exception
200:      */
201:     public function listTemplates()
202:     {
203:         global $wicked;
204:         $templates = $wicked->getMatchingPages('Template', Wicked_Page::MATCH_ENDS);
205:         $list = array(array('category' => _("Wiki Templates"),
206:             'templates' => array()));
207:         foreach ($templates as $page) {
208:             $list[0]['templates'][] = array('id' => $page['page_name'],
209:                 'name' => $page['page_name']);
210:         }
211:         return $list;
212:     }
213: 
214:     /**
215:      * Get a template specified by its name.  This is effectively an alias for
216:      * getPageSource() since Wicked templates are also normal pages.
217:      * Wicked templates are pages that include "Template" at the beginning of
218:      * the name.
219:      *
220:      * @param string $name  The name of the template to fetch
221:      *
222:      * @return string  Template data.
223:      * @throws Wicked_Exception
224:      */
225:     public function getTemplate($name)
226:     {
227:         return $this->getPageSource($name);
228:     }
229: 
230:     /**
231:      * Get the wiki source of a page specified by its name.
232:      *
233:      * @param string $name     The name of the page to fetch
234:      * @param string $version  Page version
235:      *
236:      * @return string  Page data.
237:      * @throws Wicked_Exception
238:      */
239:     public function getPageSource($pagename, $version = null)
240:     {
241:         global $wicked;
242: 
243:         $page = Wicked_Page::getPage($pagename, $version);
244: 
245:         if (!$page->allows(Wicked::MODE_CONTENT)) {
246:             throw new Wicked_Exception(_("Permission denied."));
247:         }
248: 
249:         if (!$page->isValid()) {
250:             throw new Wicked_Exception(_("Invalid page requested."));
251:         }
252: 
253:         return $page->getText();
254:     }
255: 
256:     /**
257:      * Process a completed template to update the named Wiki page.  This
258:      * method is basically a passthrough to edit().
259:      *
260:      * @param string $name   Name of the new or modified page
261:      * @param string $data   Text content of the populated template
262:      *
263:      * @throws Wicked_Exception
264:      */
265:     public function saveTemplate($name, $data)
266:     {
267:         $this->edit($name, $data, 'Template Auto-fill', false);
268:     }
269: 
270:     /**
271:      * Returns the most recently changed pages.
272:      *
273:      * @param integer $days  The number of days to look back.
274:      *
275:      * @return array  Pages.
276:      * @throws Wicked_Exception
277:      */
278:     public function getRecentChanges($days = 3)
279:     {
280:         $info = array();
281:         foreach ($GLOBALS['wicked']->getRecentChanges($days) as $page) {
282:             $info[$page['page_name']] = array(
283:                 'page_version' => $page['page_version'],
284:                 'page_checksum' => md5($page['page_text']),
285:                 'version_created' => $page['version_created'],
286:                 'change_author' => $page['change_author'],
287:                 'change_log' => $page['change_log'],
288:             );
289:         }
290: 
291:         return $info;
292:     }
293: }
294: