Apibot 0.40 examples

From Apibot
Revision as of 02:29, 4 December 2012 by Grigor Gatchev (talk | contribs) (some examples for the Bridge interface)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The Bridge interface

This is the interface similar to most MediaWiki bots (including Apibot 0.3x).

Some examples how to use it from your PHP code follow. In all of them is assumed that the bot is in a subdirectory of the current one, named 'Apibot'.

First of all, you must include the PHP files you need. For the Bridge interface, these are:

  • the bot global settings file (the bot will go even without them, but they might be handy)
  • the bot accounts file (currently the bot will not work anonymously - a matter of wiki etiquette)
  • the mains.php file (most bot modules need some standard infrastructure provided by the Mains class)
  • the bridge.php file (this is where the Bridge class, which you need, is implemented)

Copy and paste in your PHP file the following code:

require_once ( dirname ( __FILE__ ) . '/Apibot/settings.php' );    // the bot general settings
require_once ( dirname ( __FILE__ ) . '/Apibot/logins.php' );      // your logins are described here
require_once ( dirname ( __FILE__ ) . '/Apibot/mains/mains.php' ); // standard infrastructure most bot modules need
require_once ( dirname ( __FILE__ ) . '/Apibot/mains/bridge.php' );// the command bridge interface itself

Then, you have to create a Mains class object, and to use it to create a Bridge class object. The latter exports the functions that work with the wiki, or return different Query objects that can requests lists of wiki objects (pages, revisions, log entries, recent changes...).

Copy and paste in your PHP file the following code, under the code from above:

$mains = new Mains ( $logins['My_Account@en.wikipedia.org'], $bot_settings ); // create the standard infrastructure object
$bridge = new Bridge ( $mains );                                              // create the command bridge object

Examples for the non-Query Bridge functions

These functions typically change the wiki info (pages contents, user rights), do some things, or retrieve HTML code.

Copy and paste in your PHP their code under the code for including the modules needed and creating the Mains and Bridge modules. Modify it to suit your needs, and run it. :-)

Most functions shown here support more parameters, which can be found in their descriptions. Also, most will return either some fetch (a page object, HTML text or other), or a Boolean value telling whether their action was successful.

Edit a page

$page = $bridge->fetch_editable ( "My Pride of a Page" );  // get the page I work on
$page->replace_string ( "Teh", "The" );                    // replace everywhere in it this nasty typo
$bridge->edit ( $page, "Fixed a nagging typo", true );     // update the page with this comment and a Minor change flag

Block an user

$bridge->block ( "Nasty Vandal", "You deserved it!" );  // this person is really harmful - end with it!

Delete page (by title)

$bridge->delete_title ( "My Failed Attempt", "This was a garbage, sorry" );  // no need to clutter the wiki

(On most wikis you will need administrator rights to be able to delete pages.)

Delete page (by pageid)

Pageids are numeric IDs that uniquely identify a page. Unlike the page titles that can be changed, a pageid identifies a page for as long as it exists.

$bridge->delete_pageid ( 32187, "Created by mistake" );  // no need to clutter the wiki

(On most wikis you will need administrator rights to be able to delete pages.)

Send an email to another user

Some MediaWiki installations allow sending an e-mail to another user. All you need is to know their username. Other wikis do not allow this. Some allow it only to users with certain privileges.

$bridge->emailuser ( "My Friend", $subject, $message_text );  // $subject and $message_text are set to the obvious.

Expand page templates

This function allows you to see the wikitext as if all its templates were directly embedded in it instead of just called.

$bridge->expandtemplates ( $text );  // $text contains some wikitext

Import text from interwiki

On a multi-language installation, you can import the text of an another language wiki article.

$bridge->import_interwiki ( "My New Page", "Will translate this tomorrow", "de" );  // import from the German wiki

Import text from a XML file

You can import text of one or more pages from an appropriately structured XML file.

$bridge->import_xml ( $xml_file, "These pages were prepared offline - get them!" ); // $xml_file contains the file

Move (rename) a page (by title)

$bridge->move_title ( "Old Title", "New Title", "This name suits it better" );

(On some wikis you might need certain privileges to move pages.)

Move (rename) a page (by pageid)

$bridge->move_title ( 473843, "New Title", "This name suits it better" );  // 473843 is the pageid of the page

(On some wikis you might need certain privileges to move pages.)

Parse (render to HTML) a page

$html = $bridge->parse_page ( "My Beloved Page" );

($html will contain the HTML code for the page.)

Parse (render to HTML) arbitrary text

$html = $bridge->parse_text ( $text );  // $text contains the text to be parsed to HTML

($html will contain the HTML code for the text.)

Patrol a recentchange by ID

Patrolling is a procedure in which you mark a change (via the recentchanges list), as a form of cooperation between editors. With this you say: "I looked at the change and took what action was necessary, if any. No need to waste your time on it."

$bridge->patrol ( 387393783 );  // 387393783 is the RCID you want to mark as patrolled.

(On most wikis you need certain privileges to be able to mark changes as patrolled.)

Protect a page

Some pages are vandalized rather often. It might be wise to protect them from changes, at least by the users without certain privileges, for a while.

$bridge->protect ( "Disputed Page", "Calm down that edit war!", $protections );  // $protections contains a desc

(On most wikis you need certain privileges to be able to protect pages.)

Purge

Sometimes a page cache lags behind the changes in it. In some of these cases it might be better to get it moving.

$bridge->purge ( "Lagging Page" );

Rollback user changes

If a vandal has made a lot of changes in a page, it is useful to reverse them down to a good (made by another user) version.

$bridge->rollback ( "Vandalized Page", "Cleaning the muck", "Nasty Vandal" );

Unblock an user

$bridge->unblock ( "Framed Innocent", "Sorry, that was a mistake - my apologies!" );

Undelete deleted page revisions

$bridge->undelete ( "Page Title", "Deleted by mistake", $timestamps ); // $timestamps are these of the deleted revisions

Undo page edits

$bridge->undo ( "Page Title", "Misguided changes", $from_revid, $to_revid );  // revision IDs to start with and go until

Unwatch (mark page as not watched)

$bridge->unwatch ( "Page Title" );

(You will probably use the bot to unwatch pages from your account. :-) )

Upload a file

$bridge->upload_file ( "My Photo.JPG", "Will use it on my user page", $file_body );

(There are also other page upload functions.)

Changes user rights

$bridge->userrights ( "Elected For Sysop", "Giving him the privileges", array ( "sysop" ), array() );

(The first array contains the groups the user must gain. The second one contains the group s/he must lose.) (In most wikis you need certain privileges to change user rights.)

Watch (mark page as watched)

$bridge->watch ( "Page Title" );

(You will probably use the bot to watch pages from your account. :-) )

Examples for the Query Bridge functions

There are a lot of Query functions. All of them return a Query object, which can be used to retrieve lists of data specific to it. The syntax of all is very similar:

$query_revs = $bridge->query_title_revisions ( $title );
$query_l_af = $bridge->query_list_allfiles();

All of them can take two additional parameters. The first is an array with parameters you can use to direct the data retrieving, for example to retrieve page revisions from this to this date and time. The second is config settings for this query. If you need to supply settings but omit params, use NULL for them.

$query_revs = $bridge->query_title_revisions ( $title, $params, $settings );
$query_revs = $bridge->query_title_revisions ( $title, $params );
$query_revs = $bridge->query_title_revisions ( $title, NULL, $settings );

$query_l_af = $bridge->query_list_allfiles ( $params, $settings );
$query_l_af = $bridge->query_list_allfiles ( $params );
$query_l_af = $bridge->query_list_allfiles ( NULL, $settings );

Queries are typically used in this way:

$result = $query->xfer();
while ( $result )
{
  foreach ( $query->data as $element )
  {
     // do your element processing
  }
  $result = $query->next();
}

Queries also support a lot of other functions - parameters setting, etc.