1<?php 2 3namespace dokuwiki\Remote; 4 5use Doku_Renderer_xhtml; 6use dokuwiki\ChangeLog\PageChangeLog; 7use dokuwiki\Extension\AuthPlugin; 8use dokuwiki\Extension\Event; 9use dokuwiki\Remote\Response\Link; 10use dokuwiki\Remote\Response\Media; 11use dokuwiki\Remote\Response\MediaChange; 12use dokuwiki\Remote\Response\Page; 13use dokuwiki\Remote\Response\PageChange; 14use dokuwiki\Remote\Response\PageHit; 15use dokuwiki\Remote\Response\User; 16use dokuwiki\Utf8\Sort; 17 18/** 19 * Provides the core methods for the remote API. 20 * The methods are ordered in 'wiki.<method>' and 'dokuwiki.<method>' namespaces 21 */ 22class ApiCore 23{ 24 /** @var int Increased whenever the API is changed */ 25 public const API_VERSION = 13; 26 27 /** 28 * Returns details about the core methods 29 * 30 * @return array 31 */ 32 public function getMethods() 33 { 34 return [ 35 'core.getAPIVersion' => (new ApiCall([$this, 'getAPIVersion'], 'info'))->setPublic(), 36 37 'core.getWikiVersion' => new ApiCall('getVersion', 'info'), 38 'core.getWikiTitle' => (new ApiCall([$this, 'getWikiTitle'], 'info'))->setPublic(), 39 'core.getWikiTime' => (new ApiCall([$this, 'getWikiTime'], 'info')), 40 41 'core.login' => (new ApiCall([$this, 'login'], 'user'))->setPublic(), 42 'core.logoff' => new ApiCall([$this, 'logoff'], 'user'), 43 'core.whoAmI' => (new ApiCall([$this, 'whoAmI'], 'user')), 44 'core.aclCheck' => new ApiCall([$this, 'aclCheck'], 'user'), 45 46 'core.listPages' => new ApiCall([$this, 'listPages'], 'pages'), 47 'core.searchPages' => new ApiCall([$this, 'searchPages'], 'pages'), 48 'core.getRecentPageChanges' => new ApiCall([$this, 'getRecentPageChanges'], 'pages'), 49 50 'core.getPage' => (new ApiCall([$this, 'getPage'], 'pages')), 51 'core.getPageHTML' => (new ApiCall([$this, 'getPageHTML'], 'pages')), 52 'core.getPageInfo' => (new ApiCall([$this, 'getPageInfo'], 'pages')), 53 'core.getPageHistory' => new ApiCall([$this, 'getPageHistory'], 'pages'), 54 'core.getPageLinks' => new ApiCall([$this, 'getPageLinks'], 'pages'), 55 'core.getPageBackLinks' => new ApiCall([$this, 'getPageBackLinks'], 'pages'), 56 57 'core.lockPages' => new ApiCall([$this, 'lockPages'], 'pages'), 58 'core.unlockPages' => new ApiCall([$this, 'unlockPages'], 'pages'), 59 'core.savePage' => new ApiCall([$this, 'savePage'], 'pages'), 60 'core.appendPage' => new ApiCall([$this, 'appendPage'], 'pages'), 61 62 'core.listMedia' => new ApiCall([$this, 'listMedia'], 'media'), 63 'core.getRecentMediaChanges' => new ApiCall([$this, 'getRecentMediaChanges'], 'media'), 64 65 'core.getMedia' => new ApiCall([$this, 'getMedia'], 'media'), 66 'core.getMediaInfo' => new ApiCall([$this, 'getMediaInfo'], 'media'), 67 'core.getMediaUsage' => new ApiCall([$this, 'getMediaUsage'], 'media'), 68 // todo: implement getMediaHistory 69 70 'core.saveMedia' => new ApiCall([$this, 'saveMedia'], 'media'), 71 'core.deleteMedia' => new ApiCall([$this, 'deleteMedia'], 'media'), 72 ]; 73 } 74 75 // region info 76 77 /** 78 * Return the API version 79 * 80 * This is the version of the DokuWiki API. It increases whenever the API definition changes. 81 * 82 * When developing a client, you should check this version and make sure you can handle it. 83 * 84 * @return int 85 */ 86 public function getAPIVersion() 87 { 88 return self::API_VERSION; 89 } 90 91 /** 92 * Returns the wiki title 93 * 94 * @link https://www.dokuwiki.org/config:title 95 * @return string 96 */ 97 public function getWikiTitle() 98 { 99 global $conf; 100 return $conf['title']; 101 } 102 103 /** 104 * Return the current server time 105 * 106 * Returns a Unix timestamp (seconds since 1970-01-01 00:00:00 UTC). 107 * 108 * You can use this to compensate for differences between your client's time and the 109 * server's time when working with last modified timestamps (revisions). 110 * 111 * @return int A unix timestamp 112 */ 113 public function getWikiTime() 114 { 115 return time(); 116 } 117 118 // endregion 119 120 // region user 121 122 /** 123 * Login 124 * 125 * This will use the given credentials and attempt to login the user. This will set the 126 * appropriate cookies, which can be used for subsequent requests. 127 * 128 * Use of this mechanism is discouraged. Using token authentication is preferred. 129 * 130 * @param string $user The user name 131 * @param string $pass The password 132 * @return int If the login was successful 133 */ 134 public function login($user, $pass) 135 { 136 global $conf; 137 /** @var AuthPlugin $auth */ 138 global $auth; 139 140 if (!$conf['useacl']) return 0; 141 if (!$auth instanceof AuthPlugin) return 0; 142 143 @session_start(); // reopen session for login 144 $ok = null; 145 if ($auth->canDo('external')) { 146 $ok = $auth->trustExternal($user, $pass, false); 147 } 148 if ($ok === null) { 149 $evdata = [ 150 'user' => $user, 151 'password' => $pass, 152 'sticky' => false, 153 'silent' => true 154 ]; 155 $ok = Event::createAndTrigger('AUTH_LOGIN_CHECK', $evdata, 'auth_login_wrapper'); 156 } 157 session_write_close(); // we're done with the session 158 159 return $ok; 160 } 161 162 /** 163 * Log off 164 * 165 * Attempt to log out the current user, deleting the appropriate cookies 166 * 167 * Use of this mechanism is discouraged. Using token authentication is preferred. 168 * 169 * @return int 0 on failure, 1 on success 170 */ 171 public function logoff() 172 { 173 global $conf; 174 global $auth; 175 if (!$conf['useacl']) return 0; 176 if (!$auth instanceof AuthPlugin) return 0; 177 178 auth_logoff(); 179 180 return 1; 181 } 182 183 /** 184 * Info about the currently authenticated user 185 * 186 * @return User 187 */ 188 public function whoAmI() 189 { 190 return new User(); 191 } 192 193 /** 194 * Check ACL Permissions 195 * 196 * This call allows to check the permissions for a given page/media and user/group combination. 197 * If no user/group is given, the current user is used. 198 * 199 * Read the link below to learn more about the permission levels. 200 * 201 * @link https://www.dokuwiki.org/acl#background_info 202 * @param string $page A page or media ID 203 * @param string $user username 204 * @param string[] $groups array of groups 205 * @return int permission level 206 * @throws RemoteException 207 */ 208 public function aclCheck($page, $user = '', $groups = []) 209 { 210 /** @var AuthPlugin $auth */ 211 global $auth; 212 213 $page = $this->checkPage($page, 0, false, AUTH_NONE); 214 215 if ($user === '') { 216 return auth_quickaclcheck($page); 217 } else { 218 if ($groups === []) { 219 $userinfo = $auth->getUserData($user); 220 if ($userinfo === false) { 221 $groups = []; 222 } else { 223 $groups = $userinfo['grps']; 224 } 225 } 226 return auth_aclcheck($page, $user, $groups); 227 } 228 } 229 230 // endregion 231 232 // region pages 233 234 /** 235 * List all pages in the given namespace (and below) 236 * 237 * Setting the `depth` to `0` and the `namespace` to `""` will return all pages in the wiki. 238 * 239 * Note: author information is not available in this call. 240 * 241 * @param string $namespace The namespace to search. Empty string for root namespace 242 * @param int $depth How deep to search. 0 for all subnamespaces 243 * @param bool $hash Whether to include a MD5 hash of the page content 244 * @return Page[] A list of matching pages 245 * @todo might be a good idea to replace search_allpages with search_universal 246 */ 247 public function listPages($namespace = '', $depth = 1, $hash = false) 248 { 249 global $conf; 250 251 $namespace = cleanID($namespace); 252 253 // shortcut for all pages 254 if ($namespace === '' && $depth === 0) { 255 return $this->getAllPages($hash); 256 } 257 258 // search_allpages handles depth weird, we need to add the given namespace depth 259 if ($depth) { 260 $depth += substr_count($namespace, ':') + 1; 261 } 262 263 // run our search iterator to get the pages 264 $dir = utf8_encodeFN(str_replace(':', '/', $namespace)); 265 $data = []; 266 $opts['skipacl'] = 0; 267 $opts['depth'] = $depth; 268 $opts['hash'] = $hash; 269 search($data, $conf['datadir'], 'search_allpages', $opts, $dir); 270 271 return array_map(static fn($item) => new Page( 272 $item['id'], 273 0, // we're searching current revisions only 274 $item['mtime'], 275 '', // not returned by search_allpages 276 $item['size'], 277 null, // not returned by search_allpages 278 $item['hash'] ?? '' 279 ), $data); 280 } 281 282 /** 283 * Get all pages at once 284 * 285 * This is uses the page index and is quicker than iterating which is done in listPages() 286 * 287 * @return Page[] A list of all pages 288 * @see listPages() 289 */ 290 protected function getAllPages($hash = false) 291 { 292 $list = []; 293 $pages = idx_get_indexer()->getPages(); 294 Sort::ksort($pages); 295 296 foreach (array_keys($pages) as $idx) { 297 $perm = auth_quickaclcheck($pages[$idx]); 298 if ($perm < AUTH_READ || isHiddenPage($pages[$idx]) || !page_exists($pages[$idx])) { 299 continue; 300 } 301 302 $page = new Page($pages[$idx], 0, 0, '', null, $perm); 303 if ($hash) $page->calculateHash(); 304 305 $list[] = $page; 306 } 307 308 return $list; 309 } 310 311 /** 312 * Do a fulltext search 313 * 314 * This executes a full text search and returns the results. The query uses the standard 315 * DokuWiki search syntax. 316 * 317 * Snippets are provided for the first 15 results only. The title is either the first heading 318 * or the page id depending on the wiki's configuration. 319 * 320 * @link https://www.dokuwiki.org/search#syntax 321 * @param string $query The search query as supported by the DokuWiki search 322 * @return PageHit[] A list of matching pages 323 */ 324 public function searchPages($query) 325 { 326 $regex = []; 327 $data = ft_pageSearch($query, $regex); 328 $pages = []; 329 330 // prepare additional data 331 $idx = 0; 332 foreach ($data as $id => $score) { 333 if ($idx < FT_SNIPPET_NUMBER) { 334 $snippet = ft_snippet($id, $regex); 335 $idx++; 336 } else { 337 $snippet = ''; 338 } 339 340 $pages[] = new PageHit( 341 $id, 342 $snippet, 343 $score, 344 useHeading('navigation') ? p_get_first_heading($id) : $id 345 ); 346 } 347 return $pages; 348 } 349 350 /** 351 * Get recent page changes 352 * 353 * Returns a list of recent changes to wiki pages. The results can be limited to changes newer than 354 * a given timestamp. 355 * 356 * Only changes within the configured `$conf['recent']` range are returned. This is the default 357 * when no timestamp is given. 358 * 359 * @link https://www.dokuwiki.org/config:recent 360 * @param int $timestamp Only show changes newer than this unix timestamp 361 * @return PageChange[] 362 * @author Michael Klier <chi@chimeric.de> 363 * @author Michael Hamann <michael@content-space.de> 364 */ 365 public function getRecentPageChanges($timestamp = 0) 366 { 367 $recents = getRecentsSince($timestamp); 368 369 $changes = []; 370 foreach ($recents as $recent) { 371 $changes[] = new PageChange( 372 $recent['id'], 373 $recent['date'], 374 $recent['user'], 375 $recent['ip'], 376 $recent['sum'], 377 $recent['type'], 378 $recent['sizechange'] 379 ); 380 } 381 382 return $changes; 383 } 384 385 /** 386 * Get a wiki page's syntax 387 * 388 * Returns the syntax of the given page. When no revision is given, the current revision is returned. 389 * 390 * A non-existing page (or revision) will return an empty string usually. For the current revision 391 * a page template will be returned if configured. 392 * 393 * Read access is required for the page. 394 * 395 * @param string $page wiki page id 396 * @param int $rev Revision timestamp to access an older revision 397 * @return string the syntax of the page 398 * @throws AccessDeniedException 399 * @throws RemoteException 400 */ 401 public function getPage($page, $rev = 0) 402 { 403 $page = $this->checkPage($page, $rev, false); 404 405 $text = rawWiki($page, $rev); 406 if (!$text && !$rev) { 407 return pageTemplate($page); 408 } else { 409 return $text; 410 } 411 } 412 413 /** 414 * Return a wiki page rendered to HTML 415 * 416 * The page is rendered to HTML as it would be in the wiki. The HTML consist only of the data for the page 417 * content itself, no surrounding structural tags, header, footers, sidebars etc are returned. 418 * 419 * References in the HTML are relative to the wiki base URL unless the `canonical` configuration is set. 420 * 421 * If the page does not exist, an error is returned. 422 * 423 * @link https://www.dokuwiki.org/config:canonical 424 * @param string $page page id 425 * @param int $rev revision timestamp 426 * @return string Rendered HTML for the page 427 * @throws AccessDeniedException 428 * @throws RemoteException 429 */ 430 public function getPageHTML($page, $rev = 0) 431 { 432 $page = $this->checkPage($page, $rev); 433 434 return (string)p_wiki_xhtml($page, $rev, false); 435 } 436 437 /** 438 * Return some basic data about a page 439 * 440 * The call will return an error if the requested page does not exist. 441 * 442 * Read access is required for the page. 443 * 444 * @param string $page page id 445 * @param int $rev revision timestamp 446 * @param bool $author whether to include the author information 447 * @param bool $hash whether to include the MD5 hash of the page content 448 * @return Page 449 * @throws AccessDeniedException 450 * @throws RemoteException 451 */ 452 public function getPageInfo($page, $rev = 0, $author = false, $hash = false) 453 { 454 $page = $this->checkPage($page, $rev); 455 456 $result = new Page($page, $rev); 457 if ($author) $result->retrieveAuthor(); 458 if ($hash) $result->calculateHash(); 459 460 return $result; 461 } 462 463 /** 464 * Returns a list of available revisions of a given wiki page 465 * 466 * The number of returned pages is set by `$conf['recent']`, but non accessible revisions pages 467 * are skipped, so less than that may be returned. 468 * 469 * @link https://www.dokuwiki.org/config:recent 470 * @param string $page page id 471 * @param int $first skip the first n changelog lines, 0 starts at the current revision 472 * @return PageChange[] 473 * @throws AccessDeniedException 474 * @throws RemoteException 475 * @author Michael Klier <chi@chimeric.de> 476 */ 477 public function getPageHistory($page, $first = 0) 478 { 479 global $conf; 480 481 $page = $this->checkPage($page, 0, false); 482 483 $pagelog = new PageChangeLog($page); 484 $pagelog->setChunkSize(1024); 485 // old revisions are counted from 0, so we need to subtract 1 for the current one 486 $revisions = $pagelog->getRevisions($first - 1, $conf['recent']); 487 488 $result = []; 489 foreach ($revisions as $rev) { 490 if (!page_exists($page, $rev)) continue; // skip non-existing revisions 491 $info = $pagelog->getRevisionInfo($rev); 492 493 $result[] = new PageChange( 494 $page, 495 $rev, 496 $info['user'], 497 $info['ip'], 498 $info['sum'], 499 $info['type'], 500 $info['sizechange'] 501 ); 502 } 503 504 return $result; 505 } 506 507 /** 508 * Get a page's links 509 * 510 * This returns a list of links found in the given page. This includes internal, external and interwiki links 511 * 512 * If a link occurs multiple times on the page, it will be returned multiple times. 513 * 514 * Read access for the given page is needed and page has to exist. 515 * 516 * @param string $page page id 517 * @return Link[] A list of links found on the given page 518 * @throws AccessDeniedException 519 * @throws RemoteException 520 * @todo returning link titles would be a nice addition 521 * @todo hash handling seems not to be correct 522 * @todo maybe return the same link only once? 523 * @author Michael Klier <chi@chimeric.de> 524 */ 525 public function getPageLinks($page) 526 { 527 $page = $this->checkPage($page); 528 529 // resolve page instructions 530 $ins = p_cached_instructions(wikiFN($page)); 531 532 // instantiate new Renderer - needed for interwiki links 533 $Renderer = new Doku_Renderer_xhtml(); 534 $Renderer->interwiki = getInterwiki(); 535 536 // parse instructions 537 $links = []; 538 foreach ($ins as $in) { 539 switch ($in[0]) { 540 case 'internallink': 541 $links[] = new Link('local', $in[1][0], wl($in[1][0])); 542 break; 543 case 'externallink': 544 $links[] = new Link('extern', $in[1][0], $in[1][0]); 545 break; 546 case 'interwikilink': 547 $url = $Renderer->_resolveInterWiki($in[1][2], $in[1][3]); 548 $links[] = new Link('interwiki', $in[1][0], $url); 549 break; 550 } 551 } 552 553 return ($links); 554 } 555 556 /** 557 * Get a page's backlinks 558 * 559 * A backlink is a wiki link on another page that links to the given page. 560 * 561 * Only links from pages readable by the current user are returned. The page itself 562 * needs to be readable. Otherwise an error is returned. 563 * 564 * @param string $page page id 565 * @return string[] A list of pages linking to the given page 566 * @throws AccessDeniedException 567 * @throws RemoteException 568 */ 569 public function getPageBackLinks($page) 570 { 571 $page = $this->checkPage($page, 0, false); 572 573 return ft_backlinks($page); 574 } 575 576 /** 577 * Lock the given set of pages 578 * 579 * This call will try to lock all given pages. It will return a list of pages that were 580 * successfully locked. If a page could not be locked, eg. because a different user is 581 * currently holding a lock, that page will be missing from the returned list. 582 * 583 * You should always ensure that the list of returned pages matches the given list of 584 * pages. It's up to you to decide how to handle failed locking. 585 * 586 * Note: you can only lock pages that you have write access for. It is possible to create 587 * a lock for a page that does not exist, yet. 588 * 589 * Note: it is not necessary to lock a page before saving it. The `savePage()` call will 590 * automatically lock and unlock the page for you. However if you plan to do related 591 * operations on multiple pages, locking them all at once beforehand can be useful. 592 * 593 * @param string[] $pages A list of pages to lock 594 * @return string[] A list of pages that were successfully locked 595 */ 596 public function lockPages($pages) 597 { 598 $locked = []; 599 600 foreach ($pages as $id) { 601 $id = cleanID($id); 602 if ($id === '') continue; 603 if (auth_quickaclcheck($id) < AUTH_EDIT || checklock($id)) { 604 continue; 605 } 606 lock($id); 607 $locked[] = $id; 608 } 609 return $locked; 610 } 611 612 /** 613 * Unlock the given set of pages 614 * 615 * This call will try to unlock all given pages. It will return a list of pages that were 616 * successfully unlocked. If a page could not be unlocked, eg. because a different user is 617 * currently holding a lock, that page will be missing from the returned list. 618 * 619 * You should always ensure that the list of returned pages matches the given list of 620 * pages. It's up to you to decide how to handle failed unlocking. 621 * 622 * Note: you can only unlock pages that you have write access for. 623 * 624 * @param string[] $pages A list of pages to unlock 625 * @return string[] A list of pages that were successfully unlocked 626 */ 627 public function unlockPages($pages) 628 { 629 $unlocked = []; 630 631 foreach ($pages as $id) { 632 $id = cleanID($id); 633 if ($id === '') continue; 634 if (auth_quickaclcheck($id) < AUTH_EDIT || !unlock($id)) { 635 continue; 636 } 637 $unlocked[] = $id; 638 } 639 640 return $unlocked; 641 } 642 643 /** 644 * Save a wiki page 645 * 646 * Saves the given wiki text to the given page. If the page does not exist, it will be created. 647 * Just like in the wiki, saving an empty text will delete the page. 648 * 649 * You need write permissions for the given page and the page may not be locked by another user. 650 * 651 * @param string $page page id 652 * @param string $text wiki text 653 * @param string $summary edit summary 654 * @param bool $isminor whether this is a minor edit 655 * @return bool Returns true on success 656 * @throws AccessDeniedException no write access for page 657 * @throws RemoteException no id, empty new page or locked 658 * @author Michael Klier <chi@chimeric.de> 659 */ 660 public function savePage($page, $text, $summary = '', $isminor = false) 661 { 662 global $TEXT; 663 global $lang; 664 665 $page = $this->checkPage($page, 0, false, AUTH_EDIT); 666 $TEXT = cleanText($text); 667 668 669 if (!page_exists($page) && trim($TEXT) == '') { 670 throw new RemoteException('Refusing to write an empty new wiki page', 132); 671 } 672 673 // Check, if page is locked 674 if (checklock($page)) { 675 throw new RemoteException('The page is currently locked', 133); 676 } 677 678 // SPAM check 679 if (checkwordblock()) { 680 throw new RemoteException('The page content was blocked', 134); 681 } 682 683 // autoset summary on new pages 684 if (!page_exists($page) && empty($summary)) { 685 $summary = $lang['created']; 686 } 687 688 // autoset summary on deleted pages 689 if (page_exists($page) && empty($TEXT) && empty($summary)) { 690 $summary = $lang['deleted']; 691 } 692 693 // FIXME auto set a summary in other cases "API Edit" might be a good idea? 694 695 lock($page); 696 saveWikiText($page, $TEXT, $summary, $isminor); 697 unlock($page); 698 699 // run the indexer if page wasn't indexed yet 700 idx_addPage($page); 701 702 return true; 703 } 704 705 /** 706 * Appends text to the end of a wiki page 707 * 708 * If the page does not exist, it will be created. If a page template for the non-existant 709 * page is configured, the given text will appended to that template. 710 * 711 * The call will create a new page revision. 712 * 713 * You need write permissions for the given page. 714 * 715 * @param string $page page id 716 * @param string $text wiki text 717 * @param string $summary edit summary 718 * @param bool $isminor whether this is a minor edit 719 * @return bool Returns true on success 720 * @throws AccessDeniedException 721 * @throws RemoteException 722 */ 723 public function appendPage($page, $text, $summary = '', $isminor = false) 724 { 725 $currentpage = $this->getPage($page); 726 if (!is_string($currentpage)) { 727 $currentpage = ''; 728 } 729 return $this->savePage($page, $currentpage . $text, $summary, $isminor); 730 } 731 732 // endregion 733 734 // region media 735 736 /** 737 * List all media files in the given namespace (and below) 738 * 739 * Setting the `depth` to `0` and the `namespace` to `""` will return all media files in the wiki. 740 * 741 * When `pattern` is given, it needs to be a valid regular expression as understood by PHP's 742 * `preg_match()` including delimiters. 743 * The pattern is matched against the full media ID, including the namespace. 744 * 745 * @link https://www.php.net/manual/en/reference.pcre.pattern.syntax.php 746 * @param string $namespace The namespace to search. Empty string for root namespace 747 * @param string $pattern A regular expression to filter the returned files 748 * @param int $depth How deep to search. 0 for all subnamespaces 749 * @param bool $hash Whether to include a MD5 hash of the media content 750 * @return Media[] 751 * @author Gina Haeussge <osd@foosel.net> 752 */ 753 public function listMedia($namespace = '', $pattern = '', $depth = 1, $hash = false) 754 { 755 global $conf; 756 757 $namespace = cleanID($namespace); 758 759 $options = [ 760 'skipacl' => 0, 761 'depth' => $depth, 762 'hash' => $hash, 763 'pattern' => $pattern, 764 ]; 765 766 $dir = utf8_encodeFN(str_replace(':', '/', $namespace)); 767 $data = []; 768 search($data, $conf['mediadir'], 'search_media', $options, $dir); 769 return array_map(static fn($item) => new Media( 770 $item['id'], 771 0, // we're searching current revisions only 772 $item['mtime'], 773 $item['size'], 774 $item['perm'], 775 $item['isimg'], 776 $item['hash'] ?? '' 777 ), $data); 778 } 779 780 /** 781 * Get recent media changes 782 * 783 * Returns a list of recent changes to media files. The results can be limited to changes newer than 784 * a given timestamp. 785 * 786 * Only changes within the configured `$conf['recent']` range are returned. This is the default 787 * when no timestamp is given. 788 * 789 * @link https://www.dokuwiki.org/config:recent 790 * @param int $timestamp Only show changes newer than this unix timestamp 791 * @return MediaChange[] 792 * @author Michael Klier <chi@chimeric.de> 793 * @author Michael Hamann <michael@content-space.de> 794 */ 795 public function getRecentMediaChanges($timestamp = 0) 796 { 797 798 $recents = getRecentsSince($timestamp, null, '', RECENTS_MEDIA_CHANGES); 799 800 $changes = []; 801 foreach ($recents as $recent) { 802 $changes[] = new MediaChange( 803 $recent['id'], 804 $recent['date'], 805 $recent['user'], 806 $recent['ip'], 807 $recent['sum'], 808 $recent['type'], 809 $recent['sizechange'] 810 ); 811 } 812 813 return $changes; 814 } 815 816 /** 817 * Get a media file's content 818 * 819 * Returns the content of the given media file. When no revision is given, the current revision is returned. 820 * 821 * @link https://en.wikipedia.org/wiki/Base64 822 * @param string $media file id 823 * @param int $rev revision timestamp 824 * @return string Base64 encoded media file contents 825 * @throws AccessDeniedException no permission for media 826 * @throws RemoteException not exist 827 * @author Gina Haeussge <osd@foosel.net> 828 * 829 */ 830 public function getMedia($media, $rev = 0) 831 { 832 $media = cleanID($media); 833 if (auth_quickaclcheck($media) < AUTH_READ) { 834 throw new AccessDeniedException('You are not allowed to read this media file', 211); 835 } 836 837 $file = mediaFN($media, $rev); 838 if (!@ file_exists($file)) { 839 throw new RemoteException('The requested media file (revision) does not exist', 221); 840 } 841 842 $data = io_readFile($file, false); 843 return base64_encode($data); 844 } 845 846 /** 847 * Return info about a media file 848 * 849 * The call will return an error if the requested media file does not exist. 850 * 851 * Read access is required for the media file. 852 * 853 * @param string $media file id 854 * @param int $rev revision timestamp 855 * @param bool $author whether to include the author information 856 * @param bool $hash whether to include the MD5 hash of the media content 857 * @return Media 858 * @throws AccessDeniedException no permission for media 859 * @throws RemoteException if not exist 860 * @author Gina Haeussge <osd@foosel.net> 861 */ 862 public function getMediaInfo($media, $rev = 0, $author = false, $hash = false) 863 { 864 $media = cleanID($media); 865 if (auth_quickaclcheck($media) < AUTH_READ) { 866 throw new AccessDeniedException('You are not allowed to read this media file', 211); 867 } 868 if (!media_exists($media, $rev)) { 869 throw new RemoteException('The requested media file does not exist', 221); 870 } 871 872 $info = new Media($media, $rev); 873 if ($hash) $info->calculateHash(); 874 if ($author) $info->retrieveAuthor(); 875 876 return $info; 877 } 878 879 /** 880 * Returns the pages that use a given media file 881 * 882 * The call will return an error if the requested media file does not exist. 883 * 884 * Read access is required for the media file. 885 * 886 * Since API Version 13 887 * 888 * @param string $media file id 889 * @return string[] A list of pages linking to the given page 890 * @throws AccessDeniedException no permission for media 891 * @throws RemoteException if not exist 892 */ 893 public function getMediaUsage($media) 894 { 895 $media = cleanID($media); 896 if (auth_quickaclcheck($media) < AUTH_READ) { 897 throw new AccessDeniedException('You are not allowed to read this media file', 211); 898 } 899 if (!media_exists($media)) { 900 throw new RemoteException('The requested media file does not exist', 221); 901 } 902 903 return ft_mediause($media); 904 } 905 906 /** 907 * Uploads a file to the wiki 908 * 909 * The file data has to be passed as a base64 encoded string. 910 * 911 * @link https://en.wikipedia.org/wiki/Base64 912 * @param string $media media id 913 * @param string $base64 Base64 encoded file contents 914 * @param bool $overwrite Should an existing file be overwritten? 915 * @return bool Should always be true 916 * @throws RemoteException 917 * @author Michael Klier <chi@chimeric.de> 918 */ 919 public function saveMedia($media, $base64, $overwrite = false) 920 { 921 $media = cleanID($media); 922 $auth = auth_quickaclcheck(getNS($media) . ':*'); 923 924 if ($media === '') { 925 throw new RemoteException('Empty or invalid media ID given', 231); 926 } 927 928 // clean up base64 encoded data 929 $base64 = strtr($base64, [ 930 "\n" => '', // strip newlines 931 "\r" => '', // strip carriage returns 932 '-' => '+', // RFC4648 base64url 933 '_' => '/', // RFC4648 base64url 934 ' ' => '+', // JavaScript data uri 935 ]); 936 937 $data = base64_decode($base64, true); 938 if ($data === false) { 939 throw new RemoteException('Invalid base64 encoded data', 234); 940 } 941 942 if ($data === '') { 943 throw new RemoteException('Empty file given', 235); 944 } 945 946 // save temporary file 947 global $conf; 948 $ftmp = $conf['tmpdir'] . '/' . md5($media . clientIP()); 949 @unlink($ftmp); 950 io_saveFile($ftmp, $data); 951 952 $res = media_save(['name' => $ftmp], $media, $overwrite, $auth, 'rename'); 953 if (is_array($res)) { 954 throw new RemoteException('Failed to save media: ' . $res[0], 236); 955 } 956 return (bool)$res; // should always be true at this point 957 } 958 959 /** 960 * Deletes a file from the wiki 961 * 962 * You need to have delete permissions for the file. 963 * 964 * @param string $media media id 965 * @return bool Should always be true 966 * @throws AccessDeniedException no permissions 967 * @throws RemoteException file in use or not deleted 968 * @author Gina Haeussge <osd@foosel.net> 969 * 970 */ 971 public function deleteMedia($media) 972 { 973 $media = cleanID($media); 974 975 $auth = auth_quickaclcheck($media); 976 $res = media_delete($media, $auth); 977 if ($res & DOKU_MEDIA_DELETED) { 978 return true; 979 } elseif ($res & DOKU_MEDIA_NOT_AUTH) { 980 throw new AccessDeniedException('You are not allowed to delete this media file', 212); 981 } elseif ($res & DOKU_MEDIA_INUSE) { 982 throw new RemoteException('Media file is still referenced', 232); 983 } elseif (!media_exists($media)) { 984 throw new RemoteException('The media file requested to delete does not exist', 221); 985 } else { 986 throw new RemoteException('Failed to delete media file', 233); 987 } 988 } 989 990 // endregion 991 992 993 /** 994 * Convenience method for page checks 995 * 996 * This method will perform multiple tasks: 997 * 998 * - clean the given page id 999 * - disallow an empty page id 1000 * - check if the page exists (unless disabled) 1001 * - check if the user has the required access level (pass AUTH_NONE to skip) 1002 * 1003 * @param string $id page id 1004 * @param int $rev page revision 1005 * @param bool $existCheck 1006 * @param int $minAccess 1007 * @return string the cleaned page id 1008 * @throws AccessDeniedException 1009 * @throws RemoteException 1010 */ 1011 private function checkPage($id, $rev = 0, $existCheck = true, $minAccess = AUTH_READ) 1012 { 1013 $id = cleanID($id); 1014 if ($id === '') { 1015 throw new RemoteException('Empty or invalid page ID given', 131); 1016 } 1017 1018 if ($existCheck && !page_exists($id, $rev)) { 1019 throw new RemoteException('The requested page (revision) does not exist', 121); 1020 } 1021 1022 if ($minAccess && auth_quickaclcheck($id) < $minAccess) { 1023 throw new AccessDeniedException('You are not allowed to read this page', 111); 1024 } 1025 1026 return $id; 1027 } 1028} 1029