Bridge Non-Query functions

From Apibot

Jump to: navigation, search

This is a list of all non-query functions in the Bridge class.

Unlike the Query functions, which are fully dependent on the MediaWiki API, some non-query functions can also act through a backend that uses the MW web interface. This is often used while working with MW versions that support the required action through their web interface, but not through their API interface.

These functions use as backends the Tasks classes, defined in the files in the /tasks subdirectory. The results are what the objects of these classes return. The objects, in turn, will use the API_Task_* and/or Web_Task_* (where they exist) classes as backends.

Contents

Fetching pages

fetch_title()

Syntax
fetch_title ( $title, $properties = NULL, $revid = NULL, $section = NULL, $log_fetch = NULL )
Parameters
$title The title of the page to fetch
$properties The page properties to fetch. (Structured as an array. The keys are the property names, and the values are arrays or (pipe-separated) strings with the settings for this property.) By default, requires most of the prop and info property info, plus info from the last page revision.
$revid Revision ID to fetch (default - the last one).
$section Section No. to fetch (default - the entire page text).
$log_fetch Whether to mark the fetch in the bot logfile (default - yes).
Result
A page array or object, suitable for editing the page (unless $properties has been set to require different page properties), if the fetch is successful; false otherwise.
Other
Backends: API

fetch_pageid()

Syntax
fetch_pageid ( $pageid, $properties = NULL, $revid = NULL, $section = NULL, $log_fetch = NULL )
Parameters
$pageid The pageid of the page to fetch
$properties The page properties to fetch. (Structured as an array. The keys are the property names, and the values are arrays or (pipe-separated) strings with the settings for this property.) By default, requires most of the prop and info property info, plus info from the last page revision.
$revid Revision ID to fetch (default - the last one).
$section Section No. to fetch (default - the entire page text).
$log_fetch Whether to mark the fetch in the bot logfile (default - yes).
Result
A page array or object, suitable for editing the page (unless $properties has been set to require different page properties), if the fetch is successful; false otherwise.
Other
Backends: API

fetch_revid()

Syntax
fetch_revid ( $revid, $properties = NULL, $section = NULL, $log_fetch = NULL )
Parameters
$revid The revid of a revision of the page to fetch. (Also, this revision will be the one fetched with the page.)
$properties The page properties to fetch. (Structured as an array. The keys are the property names, and the values are arrays or (pipe-separated) strings with the settings for this property.) By default, requires most of the prop and info property info, plus info from the last page revision.
$section Section No. to fetch (default - the entire page text).
$log_fetch Whether to mark the fetch in the bot logfile (default - yes).
Result
A page array or object, suitable for editing the page (unless $properties has been set to require different page properties), if the fetch is successful; false otherwise.
Other
Backends: API

fetch_editable()

(Very similar to fetch_title(), but sacrifices the $properties parameter to gain simplicity and a Web backend.)

Syntax
fetch_editable ( $title, $revid = NULL, $section = NULL, $log_fetch = NULL )
Parameters
$title The title of the page to fetch
$revid Revision ID to fetch (default - the last one).
$section Section No. to fetch (default - the entire page text).
$log_fetch Whether to mark the fetch in the bot logfile (default - yes).
Result
A page array or object, suitable for editing the page, if the fetch is successful; false otherwise.
Other
Backends: API, Web

Modifying page contents

edit()

Syntax
edit ( $page, $summary, $is_minor = NULL, $is_bot = NULL, $watch = NULL, $recreate = NULL, $createonly = NULL, $nocreate = NULL )
Parameters
$page A page array or object, as returned by a fetch_* function, with possibly changed text. (The function will refuse to submit the text if it was not changed.)
$summary A summary to post to describe what the edit was about.
$is_minor Whether to mark the edit as minor.
$is_bot Whether to mark the edit as made by a bot. (Not used by the Web backend. There the bot mark depends on whether the account belongs to a bot.)
$watch Whether to add this page to the account watchlist (true - add it; false - remove it from the watchlist, if in it; NULL - keep the current status).
$recreate Whether to create the page anew if it was deleted.
$createonly Do not edit existing pages - only create one if it doesn't exist.
$nocreate If the page does not exist, do not attempt to create it.
Result
The edit results, as returned by the wiki, if the edit was successful; false otherwise.
Other
Backends: API, Web

undo()

Syntax
undo ( $title, $summary, $undo_revid = NULL, $to_revid = NULL, $is_minor = NULL, $is_bot = NULL, $watch = NULL )
Parameters
$title The title of the page to undo revisions on. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
$summary A summary to post to describe what the undo was about.
$undo_revid The revid that must be undone. Must be the last page revision, or the undo will fail.
$to_revid The revid that must be re-instated as the last good one. (If omitted / NULL, just one revision will be undone.)
$is_minor Whether to mark the undo as minor.
$is_bot Whether to mark the undo as made by a bot.
$watch Whether to add this page to the account watchlist (true - add it; false - remove it from the watchlist, if in it; NULL - keep the current status).
Result
The undo results, as returned by the wiki, if the undo was successful; false otherwise.
Other
Backends: API

rollback()

Syntax
rollback ( $title, $reason, $user, $markbot = NULL )
Parameters
$title The title of the page to rollback. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
$reason A reason for the rollback.
$user The user whose edits must be rolled back.
$markbot Whether to mark the undo as made by a bot.
Result
The rollback results, as returned by the wiki, if the rollback was successful; false otherwise.
Other
Backends: API

Importing pages

import_interwiki()

Syntax
import_interwiki ( $title, $summary, $iwcode, $fullhistory = NULL, $into_namespace = NULL, $templates = NULL )
Parameters
$title The title of the page to rollback. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
$summary A summary for the import.
$iwcode The code of the interwiki to import the page from.
$fullhistory Whether to import the pages with all of their history (true), or not (false).
$into_namespace Namespace ID to import the pages into.
$templates Whether to import also the templates used in the page (true), or not (false).
Result
The import results, as returned by the wiki, if the import was successful; false otherwise.
Other
Backends: API

import_xml()

Syntax
import_xml ( $xml_upload, $summary )
Parameters
$xml_upload A XML file containing the various attributes of one or more pages.
$summary A summary for the import.
Result
The import results, as returned by the wiki, if the import was successful; false otherwise.
Other
Backends: API

Uploading files

upload_file()

Syntax
upload_file ( $filename, $comment, $file_body, $text = NULL, $watch = NULL, $ignorewarnings = NULL )
Parameters
$filename The desired filename. (Will be used to construct the title of the file page.)
$comment A comment about the upload. Also used as the initial page text for new files if text parameter not provided
$file_body The body of the file, in binary form.
$text Initial page text, if the file is new. (If empty, $comment will be used.)
$watch Whether to add this page to the account watchlist (true - add it; false - remove it from the watchlist, if in it; NULL - keep the current status).
$ignorewarnings Ignore any warnings that may arise during the upload / file accepting.
Result
The upload results, as returned by the wiki, if the upload was successful; false otherwise.
Other
Backends: API

upload_url()

Syntax
upload_file ( $filename, $comment, $url, $text = NULL, $watch = NULL, $ignorewarnings = NULL, $asyncdownload = NULL )
Parameters
$filename The desired filename. (Will be used to construct the title of the file page.)
$comment A comment about the upload. Also used as the initial page text for new files if text parameter not provided
$url The URL of the file.
$text Initial page text, if the file is new. (If empty, $comment will be used.)
$watch Whether to add this page to the account watchlist (true - add it; false - remove it from the watchlist, if in it; NULL - keep the current status).
$ignorewarnings Ignore any warnings that may arise during the upload / file accepting.
$asyncdownload Retrieve the file asynchronously. (Excluded in the latest MediaWiki versions.)
Result
The upload results, as returned by the wiki, if the upload was successful; false otherwise.
Other
Backends: API

Changing page protections

protect()

Syntax
protect ( $title, $reason, $protections, $expiry = NULL, $cascade = false )
Parameters
$title The title of the page to move. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
$reason A reason for the move.
$protections An array with keys named for page actions and values containing the group privileges that must be required. For example: array ( 'edit' => "autoconfirmed", 'delete' => "sysop", 'move' => "sysop" ).
$expiry How long the protection should last. An array with GNU-format timestamps, matching by order the given protections. he timestamps infinite, indefinite and never result in a protection that will never expire. Timestamps like next Monday 16:04:57 or 9:28 PM tomorrow are also allowed, see the GNU web site for details. Not setting this parameter is equal to setting it to infinite.
$cascade Whether to protect also all pages and templates including in this one (true), or not (false).
Result
The move results, as returned by the wiki, if the move was successful; false otherwise.
Other
Backends: API

Including / excluding pages to / from watchlist

watch()

Syntax
watch ( $title )
Parameters
$title The title of the page to include in the account watchlist. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
Result
true if the action was successful; false otherwise.
Other
Backends: API

unwatch()

Syntax
unwatch ( $title )
Parameters
$title The title of the page to exclude from the account watchlist. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
Result
true if the action was successful; false otherwise.
Other
Backends: API

Moving pages

move_title()

Syntax
move_title ( $title, $to_title, $reason, $noredirect = NULL, $movetalk = NULL, $movesubpages = NULL, $watch = NULL )
Parameters
$title The title of the page to move. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
$to_title The new title for the page.
$reason A reason for the move.
$noredirect Whether to leave a redirecting page with the old name (false), or not (true).
$movetalk Whether to move the talk page together with the main page (true), or not (false).
$movesubpages Whether to move the subpages of this page under matching new names (true), or not (false).
$watch Whether to add this page to the account watchlist (true - add it; false - remove it from the watchlist, if in it; NULL - keep the current status).
Result
The move results, as returned by the wiki, if the move was successful; false otherwise.
Other
Backends: API

move_pageid()

Syntax
move_pageid ( $pageid, $to_title, $reason, $noredirect = NULL, $movetalk = NULL, $movesubpages = NULL, $watch = NULL )
Parameters
$pageid The pageid of the page to move. (If a page or another dataobject is passed instead, and its pageid property is set, its value will be used. If an array is passed instead, and its key pageid is set, its value will be used.)
$to_title The new title for the page.
$reason A reason for the move.
$noredirect Whether to leave a redirecting page with the old name (false), or not (true).
$movetalk Whether to move the talk page together with the main page (true), or not (false).
$movesubpages Whether to move the subpages of this page under matching new names (true), or not (false).
$watch Whether to add this page to the account watchlist (true - add it; false - remove it from the watchlist, if in it; NULL - keep the current status).
Result
The move results, as returned by the wiki, if the move was successful; false otherwise.
Other
Backends: API

Deleting / undeleting pages

delete_title()

Syntax
delete_title ( $title, $reason, $watch = NULL, $oldimage = NULL )
Parameters
$title The title of the page to delete. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
$reason A reason for the deletion.
$watch Whether to add this page to the account watchlist (true - add it; false - remove it from the watchlist, if in it; NULL - keep the current status).
$oldimage A name of an old image to delete as provided by iiprop=archivename. (Not used by the Web backend.)
Result
The delete results, as returned by the wiki, if the delete was successful; false otherwise.
Other
Backends: API, Web

delete_pageid()

Syntax
delete_pageid ( $pageid, $reason, $watch = NULL, $oldimage = NULL )
Parameters
$pageid The pageid of the page to delete. (If a page or another dataobject is passed instead, and its pageid property is set, its value will be used. If an array is passed instead, and its key pageid is set, its value will be used.)
$reason A reason for the deletion.
$watch Whether to add this page to the account watchlist (true - add it; false - remove it from the watchlist, if in it; NULL - keep the current status).
$oldimage A name of an old image to delete as provided by iiprop=archivename.
Result
The delete results, as returned by the wiki, if the delete was successful; false otherwise.
Other
Backends: API

undelete()

Syntax
undelete ( $title, $reason, $timestamps = NULL )
Parameters
$title The title of the page to delete. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
$reason A reason for the deletion.
$timestamps An array with the timestamps of the deleted revisions to be undeleted, If empty / NULL, all deleted revisions of this title will be undeleted.
Result
The undelete results, as returned by the wiki, if the undelete was successful; false otherwise.
Other
Backends: API

Expanding page templates and rendering

expandtemplates()

Syntax
expandtemplates ( $text, $title = NULL )
Parameters
$text A text to expand the templates used in it.
$title Expand the templates as if the text belongs to this page. (Influences how eg. templates like {{PAGENAME}} will be expanded.)
Result
The text with the templates in it expanded (as if their text is pasted in instead of their names) if the expand was successful; false otherwise.
Other
Backends: API

parse_page()

Syntax
parse_page ( $title, $prop = NULL, $pst = NULL, $uselang = NULL )
Parameters
$title Parse this page. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
$prop A list of the parsed page properties to get. (See the MediaWiki docs for a complete list.)
$pst Do a pre-save-transform - expand tildes, etc (true, or not (false).
$uselang A language code to use while parsing language-dependent content.
Result
The parsed page properties (HTML, sections etc) if the parse was successful; false otherwise.
Other
Backends: API

parse_text()

Syntax
parse_text ( $text, $title = NULL, $prop = NULL, $pst = NULL, $uselang = NULL )
Parameters
$text The text that must be parsed.
$title Parse the text as if it is on this page. (If a page or another dataobject is passed instead, and its title property is set, its value will be used. If an array is passed instead, and its key title is set, its value will be used.)
$prop A list of the parsed page properties to get. (See the MediaWiki docs for a complete list.)
$pst Do a pre-save-transform - expand tildes, etc (true, or not (false).
$uselang A language code to use while parsing language-dependent content.
Result
The parsed page properties (HTML, sections etc) if the parse was successful; false otherwise.
Other
Backends: API

User-related functions

block()

Syntax
block ( $user, $reason, $expiry = NULL, $anononly = NULL, $nocreate = NULL, $autoblock = NULL, $noemail = NULL )
Parameters
$user The name of the user that must be blocked. (If a user or another dataobject is passed instead, and its user property is set, its value will be used. If an array is passed instead, and its key user is set, its value will be used.)
$reason Reason for the block.
$expiry A timestamp (GNU format) for the block expiration. Empty / NULL means infinite.
$anononly Only anonymous edits from this IP will be blocked (if true). If an user has (or creates) an account, they will be able to edit.
$nocreate Whether users cannot create accounts from this IP (true), or not (false).
$autoblock If true, automatically block the last IP address this user logged in from, and subsequently block all logins from this IP.
$noemail If true, prevents the user from sending email via the MediaWiki email facility.
Result
The block results, as returned by the wiki, if the block is successful; false otherwise.
Other
Backends: API

unblock()

Syntax
unblock ( $user, $reason, $block_id = NULL )
Parameters
$user The name of the user that must be inblocked. (If a user or another dataobject is passed instead, and its user property is set, its value will be used. If an array is passed instead, and its key user is set, its value will be used.)
$reason Reason for the unblock.
$block_id ID of the block that must be cancelled. If empty, the last active block for this user is cancelled.
Result
The unblock results, as returned by the wiki, if the unblock is successful; false otherwise.
Other
Backends: API

userrights()

Syntax
userrights ( $user, $reason, $add_groups = NULL, $remove_groups = NULL )
Parameters
$user The name of the user whose rights must be changed. (If a user or another dataobject is passed instead, and its user property is set, its value will be used. If an array is passed instead, and its key user is set, its value will be used.)
$reason Reason for the rights change.
$add_groups An array (or pipe-separated string) with the names of the groups the user must acquire.
$remove_groups An array (or pipe-separated string) with the names of the groups the user must lose.
Result
The rights change results, as returned by the wiki, if the change is successful; false otherwise.
Other
Backends: API

emailuser()

Syntax
emailuser ( $user, $subject, $text = NULL, $ccme = NULL )
Parameters
$user The name of the user to send the email to. (If a user or another dataobject is passed instead, and its user property is set, its value will be used. If an array is passed instead, and its key user is set, its value will be used.)
$subject A subject for the message.
$text A text for the message.
$ccme If true, send a CC to the sender's account, too.
Result
true if the email was sent successfully; false otherwise.
Other
Backends: API

createaccount()

Syntax
createaccount ( $user, $password, $domain = NULL, $email = NULL, $realname = NULL, $mailpassword = NULL, $reason = NULL, $language = NULL )
Parameters
$user The username to register.
$password The password to set for this username.
$domain A domain to authenticate with.
$email Set this as the new user's email address.
$realname Set this as the new user's real name.
$mailpassword If true, set a randomly-generated password and mail it to the specified user email address. (In this case, the $password parameter is ignored.)
$reason Optional reason for registering this username (will show in the MediaWiki logs).
$language Set this as the default language for the new user.
Result
true if the user was registered successfully; false otherwise.
Other
Available: since v0.40.6
Backends: API

Patrolling recentchanges

patrol()

Syntax
patrol ( $rcid )
Parameters
$rcid The ID of the recentchange to be marked as patrolled.
Result
true if the recentchange was marked as patrolled successfully; false otherwise.
Other
Backends: API

Other

xfer()

Transfers some info over the Net.

Syntax
xfer ( $uri, $vars = array(), $files = array(), $mustbeposted = false )
Parameters
$uri The URI (eg. URL) to be hit.
$vars An array with the variables to be submitted (the keys are the variable names, and the matching values are their values).
$files An array with the files that must be uploaded (the keys are the file names, and the matching values are their bodies).
$mustbeposted If true, the data will be sent through a POST type request. Otherwise, the data will be sent through a GET request if small enough, and through POST if larger.
Result
The data that are received from the transfer, or false if the transfer failed.
Other
Available: since v0.40.6
Personal tools