[ Index ]

PHP Cross Reference of DokuWiki

title

Body

[close]

/inc/Remote/ -> ApiCore.php (summary)

(no description)

File Size: 1001 lines (33 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

ApiCore:: (29 methods):
  getMethods()
  getAPIVersion()
  getWikiTitle()
  getWikiTime()
  login()
  logoff()
  whoAmI()
  aclCheck()
  listPages()
  getAllPages()
  searchPages()
  getRecentPageChanges()
  getPage()
  getPageHTML()
  getPageInfo()
  getPageHistory()
  getPageLinks()
  getPageBackLinks()
  lockPages()
  unlockPages()
  savePage()
  appendPage()
  listMedia()
  getRecentMediaChanges()
  getMedia()
  getMediaInfo()
  saveMedia()
  deleteMedia()
  checkPage()


Class: ApiCore  - X-Ref

Provides the core methods for the remote API.
The methods are ordered in 'wiki.<method>' and 'dokuwiki.<method>' namespaces

getMethods()   X-Ref
Returns details about the core methods

return: array

getAPIVersion()   X-Ref
Return the API version

This is the version of the DokuWiki API. It increases whenever the API definition changes.

When developing a client, you should check this version and make sure you can handle it.

return: int

getWikiTitle()   X-Ref
Returns the wiki title

link: https://www.dokuwiki.org/config:title
return: string

getWikiTime()   X-Ref
Return the current server time

Returns a Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).

You can use this to compensate for differences between your client's time and the
server's time when working with last modified timestamps (revisions).

return: int A unix timestamp

login($user, $pass)   X-Ref
Login

This will use the given credentials and attempt to login the user. This will set the
appropriate cookies, which can be used for subsequent requests.

Use of this mechanism is discouraged. Using token authentication is preferred.

param: string $user The user name
param: string $pass The password
return: int If the login was successful

logoff()   X-Ref
Log off

Attempt to log out the current user, deleting the appropriate cookies

Use of this mechanism is discouraged. Using token authentication is preferred.

return: int 0 on failure, 1 on success

whoAmI()   X-Ref
Info about the currently authenticated user

return: User

aclCheck($page, $user = '', $groups = [])   X-Ref
Check ACL Permissions

This call allows to check the permissions for a given page/media and user/group combination.
If no user/group is given, the current user is used.

Read the link below to learn more about the permission levels.

link: https://www.dokuwiki.org/acl#background_info
param: string $page A page or media ID
param: string $user username
param: string[] $groups array of groups
return: int permission level

listPages($namespace = '', $depth = 1, $hash = false)   X-Ref
List all pages in the given namespace (and below)

Setting the `depth` to `0` and the `namespace` to `""` will return all pages in the wiki.

Note: author information is not available in this call.

param: string $namespace The namespace to search. Empty string for root namespace
param: int $depth How deep to search. 0 for all subnamespaces
param: bool $hash Whether to include a MD5 hash of the page content
return: Page[] A list of matching pages

getAllPages($hash = false)   X-Ref
Get all pages at once

This is uses the page index and is quicker than iterating which is done in listPages()

see: listPages()
return: Page[] A list of all pages

searchPages($query)   X-Ref
Do a fulltext search

This executes a full text search and returns the results. The query uses the standard
DokuWiki search syntax.

Snippets are provided for the first 15 results only. The title is either the first heading
or the page id depending on the wiki's configuration.

link: https://www.dokuwiki.org/search#syntax
param: string $query The search query as supported by the DokuWiki search
return: PageHit[] A list of matching pages

getRecentPageChanges($timestamp = 0)   X-Ref
Get recent page changes

Returns a list of recent changes to wiki pages. The results can be limited to changes newer than
a given timestamp.

Only changes within the configured `$conf['recent']` range are returned. This is the default
when no timestamp is given.

link: https://www.dokuwiki.org/config:recent
author: Michael Klier <chi@chimeric.de>
author: Michael Hamann <michael@content-space.de>
param: int $timestamp Only show changes newer than this unix timestamp
return: PageChange[]

getPage($page, $rev = 0)   X-Ref
Get a wiki page's syntax

Returns the syntax of the given page. When no revision is given, the current revision is returned.

A non-existing page (or revision) will return an empty string usually. For the current revision
a page template will be returned if configured.

Read access is required for the page.

param: string $page wiki page id
param: int $rev Revision timestamp to access an older revision
return: string the syntax of the page

getPageHTML($page, $rev = 0)   X-Ref
Return a wiki page rendered to HTML

The page is rendered to HTML as it would be in the wiki. The HTML consist only of the data for the page
content itself, no surrounding structural tags, header, footers, sidebars etc are returned.

References in the HTML are relative to the wiki base URL unless the `canonical` configuration is set.

If the page does not exist, an error is returned.

link: https://www.dokuwiki.org/config:canonical
param: string $page page id
param: int $rev revision timestamp
return: string Rendered HTML for the page

getPageInfo($page, $rev = 0, $author = false, $hash = false)   X-Ref
Return some basic data about a page

The call will return an error if the requested page does not exist.

Read access is required for the page.

param: string $page page id
param: int $rev revision timestamp
param: bool $author whether to include the author information
param: bool $hash whether to include the MD5 hash of the page content
return: Page

getPageHistory($page, $first = 0)   X-Ref
Returns a list of available revisions of a given wiki page

The number of returned pages is set by `$conf['recent']`, but non accessible revisions pages
are skipped, so less than that may be returned.

link: https://www.dokuwiki.org/config:recent
author: Michael Klier <chi@chimeric.de>
param: string $page page id
param: int $first skip the first n changelog lines, 0 starts at the current revision
return: PageChange[]

getPageLinks($page)   X-Ref
Get a page's links

This returns a list of links found in the given page. This includes internal, external and interwiki links

If a link occurs multiple times on the page, it will be returned multiple times.

Read access for the given page is needed and page has to exist.

author: Michael Klier <chi@chimeric.de>
param: string $page page id
return: Link[] A list of links found on the given page

getPageBackLinks($page)   X-Ref
Get a page's backlinks

A backlink is a wiki link on another page that links to the given page.

Only links from pages readable by the current user are returned. The page itself
needs to be readable. Otherwise an error is returned.

param: string $page page id
return: string[] A list of pages linking to the given page

lockPages($pages)   X-Ref
Lock the given set of pages

This call will try to lock all given pages. It will return a list of pages that were
successfully locked. If a page could not be locked, eg. because a different user is
currently holding a lock, that page will be missing from the returned list.

You should always ensure that the list of returned pages matches the given list of
pages. It's up to you to decide how to handle failed locking.

Note: you can only lock pages that you have write access for. It is possible to create
a lock for a page that does not exist, yet.

Note: it is not necessary to lock a page before saving it. The `savePage()` call will
automatically lock and unlock the page for you. However if you plan to do related
operations on multiple pages, locking them all at once beforehand can be useful.

param: string[] $pages A list of pages to lock
return: string[] A list of pages that were successfully locked

unlockPages($pages)   X-Ref
Unlock the given set of pages

This call will try to unlock all given pages. It will return a list of pages that were
successfully unlocked. If a page could not be unlocked, eg. because a different user is
currently holding a lock, that page will be missing from the returned list.

You should always ensure that the list of returned pages matches the given list of
pages. It's up to you to decide how to handle failed unlocking.

Note: you can only unlock pages that you have write access for.

param: string[] $pages A list of pages to unlock
return: string[] A list of pages that were successfully unlocked

savePage($page, $text, $summary = '', $isminor = false)   X-Ref
Save a wiki page

Saves the given wiki text to the given page. If the page does not exist, it will be created.
Just like in the wiki, saving an empty text will delete the page.

You need write permissions for the given page and the page may not be locked by another user.

author: Michael Klier <chi@chimeric.de>
param: string $page page id
param: string $text wiki text
param: string $summary edit summary
param: bool $isminor whether this is a minor edit
return: bool Returns true on success

appendPage($page, $text, $summary = '', $isminor = false)   X-Ref
Appends text to the end of a wiki page

If the page does not exist, it will be created. If a page template for the non-existant
page is configured, the given text will appended to that template.

The call will create a new page revision.

You need write permissions for the given page.

param: string $page page id
param: string $text wiki text
param: string $summary edit summary
param: bool $isminor whether this is a minor edit
return: bool Returns true on success

listMedia($namespace = '', $pattern = '', $depth = 1, $hash = false)   X-Ref
List all media files in the given namespace (and below)

Setting the `depth` to `0` and the `namespace` to `""` will return all media files in the wiki.

When `pattern` is given, it needs to be a valid regular expression as understood by PHP's
`preg_match()` including delimiters.
The pattern is matched against the full media ID, including the namespace.

link: https://www.php.net/manual/en/reference.pcre.pattern.syntax.php
author: Gina Haeussge <osd@foosel.net>
param: string $namespace The namespace to search. Empty string for root namespace
param: string $pattern A regular expression to filter the returned files
param: int $depth How deep to search. 0 for all subnamespaces
param: bool $hash Whether to include a MD5 hash of the media content
return: Media[]

getRecentMediaChanges($timestamp = 0)   X-Ref
Get recent media changes

Returns a list of recent changes to media files. The results can be limited to changes newer than
a given timestamp.

Only changes within the configured `$conf['recent']` range are returned. This is the default
when no timestamp is given.

link: https://www.dokuwiki.org/config:recent
author: Michael Klier <chi@chimeric.de>
author: Michael Hamann <michael@content-space.de>
param: int $timestamp Only show changes newer than this unix timestamp
return: MediaChange[]

getMedia($media, $rev = 0)   X-Ref
Get a media file's content

Returns the content of the given media file. When no revision is given, the current revision is returned.

link: https://en.wikipedia.org/wiki/Base64
author: Gina Haeussge <osd@foosel.net>
param: string $media file id
param: int $rev revision timestamp
return: string Base64 encoded media file contents

getMediaInfo($media, $rev = 0, $author = false, $hash = false)   X-Ref
Return info about a media file

The call will return an error if the requested media file does not exist.

Read access is required for the media file.

author: Gina Haeussge <osd@foosel.net>
param: string $media file id
param: int $rev revision timestamp
param: bool $author whether to include the author information
param: bool $hash whether to include the MD5 hash of the media content
return: Media

saveMedia($media, $base64, $overwrite = false)   X-Ref
Uploads a file to the wiki

The file data has to be passed as a base64 encoded string.

link: https://en.wikipedia.org/wiki/Base64
author: Michael Klier <chi@chimeric.de>
param: string $media media id
param: string $base64 Base64 encoded file contents
param: bool $overwrite Should an existing file be overwritten?
return: bool Should always be true

deleteMedia($media)   X-Ref
Deletes a file from the wiki

You need to have delete permissions for the file.

author: Gina Haeussge <osd@foosel.net>
param: string $media media id
return: bool Should always be true

checkPage($id, $rev = 0, $existCheck = true, $minAccess = AUTH_READ)   X-Ref
Convenience method for page checks

This method will perform multiple tasks:

- clean the given page id
- disallow an empty page id
- check if the page exists (unless disabled)
- check if the user has the required access level (pass AUTH_NONE to skip)

param: string $id page id
param: int $rev page revision
param: bool $existCheck
param: int $minAccess
return: string the cleaned page id