View source for Apibot 0.40 examples

== Using the bot ==

To use the bot, you will typically create a PHP file. In it, you include some bot modules, create some bot objects and have the objects do the work you need.

This PHP file is the only one you have to write yourself. It usually requires very little PHP knowledge, just knowing the basics of using Apibot. For an average computer user this will be about an hour of learning. :-)

For the rest, read further:

== The Mains object ==

If you build a house, or factory, or pretty much anything else, you should provide it with electricity, water, phone, Internet etc. Collectively, all these utilities are often called ''mains''.

Apibot has its Mains, too - a set of objects that provide the different basic functions and utilities for the bot. They are contained in the Mains class. An object of this class is needed to create almost every bot module.

To create an object of the Mains class, you need a wiki login and (optionally) a set of bot settings. In Apibot, wiki logins are typically stored in an array called $logins, which is described in a file called <code>logins.php</code>. The bot settings are typically defined in an array, named <code>$bot_settings</code> and defined in <code>settings.php</code>. Finally, the Mains class is defined in the file <code>mains/mains.php</code>.

To create a Mains object, put somewhere in the beginning of your PHP file lines like these:
<pre>
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/mains/mains.php' );

$mains = new Mains ( $logins['My_Username@en.wikipedia.org'], $bot_settings );
</pre>
(Hint: Copy and paste these. The file paths here assume that Apibot is in a subdirectory of the current directory, named "<code>apibot</code>", and that the <code>$logins</code> array contains a login with the key <code>My_Username@en.wikipedia.org</code>.)

== The Bridge interface ==

Apibot has two interfaces - Bridge and Assembly line. Bridge is the classic one, similar to most MediaWiki bots (including Apibot 0.3x).

To use it, you must create an object of the <code>Bridge</code> class, implemented in the file <code>bridge.php</code>. Insert in your PHP file, under the lines that create the <code>$mains</code> object, lines like the following:
<pre>
require_once ( dirname ( __FILE__ ) . '/apibot/bridge.php' );

$bridge = new Bridge ( $mains );
</pre>

=== Query functions ===

The Bridge interface gives you the means to query the wiki for information. MediaWiki can supply many types of info. Accordingly, the Bridge interface allows for many different types of queries.

The common scheme is that you call a Bridge function that returns a <code>Query</code> object of a specific type. Some of the functions need no parameters at all (but can be given some). For example, the query that will list the wiki users needs no vital info. Other query functions need some key info - for example, the query that will list the revisions of a page will need the page title or pageid.

Here are some examples on creating a Query object:
<pre>
$query_revs = $bridge->query_title_revisions ( $title );
$query_l_au = $bridge->query_list_allusers();
</pre>
All query functions 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 don't want to supply a parameter, specify NULL for it, or just leave it out if it is the last one. For example:
<pre>
$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 );
</pre>

Query objects can supply wiki information according to their type. Here is the typical way to use them:
<pre>
$result = $query->xfer();
while ( $result )
{
  foreach ( $query->data as $element )
  {
     // process the data element
  }
  $result = $query->next();
}
</pre>
Queries also export some other functions - setting parameters to them, etc.

See also:

* [[Apibot 0.40 Bridge Query functions|Bridge Query functions list]]
* [[Action_Query functions|Bridge Query member functions]]

=== Non-Query functions ===

These functions typically change the wiki info (pages contents, user rights), do some things, or retrieve HTML code. By calling them, you roll the ball. :-)

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.

<pre>

// 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!" );

// Delete a page (on most wikis you will need administrator rights)
// ... by title:
$bridge->delete_title ( "My Failed Attempt", "This was a garbage, sorry" );
// ... by pageid (these are unique numeric page identifiers that do not change with renaming the page):
$bridge->delete_pageid ( 32187, "Created by mistake" );

// Send an email to another user, by username (some wikis do not allow this, or require certain rights):
$bridge->emailuser ( "My Friend", $subject, $message_text );

// Expand page templates (as if they are directly embedded in the text instead of called by name):
$expanded_text = $bridge->expandtemplates ( $text );  // $text contains some wikitext

// Import text from interwiki (on a multi-language installation):
$bridge->import_interwiki ( "My New Page", "Will translate this tomorrow", "de" );

// Import text from a XML file:
$bridge->import_xml ( $xml_file, "These pages were prepared offline - get them!" ); // $xml_file contains the file

// Move (rename) a page (on some wikis you might need certain rights):
// ... by title:
$bridge->move_title ( "Old Title", "New Title", "This name suits it better" );
// ... by pageid:
$bridge->move_title ( 473843, "New Title", "This name suits it better" );  // 473843 is the pageid of the page

// 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

// Patrol a recentchange by ID (mark it to tell the other users "Already checked - don't waste time on it"):
$bridge->patrol ( 387393783 );  // 387393783 is the RCID you want to mark. On most wikis you need certain rights.

// Protect a page (require mininal rights to change it; on most wikis you need certain rights to do this):
$bridge->protect ( "Disputed Page", "Calm down that edit war!", $protections );  // $protections contains a desc

// Purge page cache:
$bridge->purge ( "Lagging Page" );

// Rollback (last user changes back to another user's change):
$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; typically you do this for your account, not for a bot one :-) ):
$bridge->unwatch ( "Page Title" );

// 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; typically you do this for your account, not for a bot one :-) ):
$bridge->watch ( "Page Title" );
</pre>

See also:

* [[Apibot 0.40 Bridge Non-Query functions|Bridge Non-Query functions list]]

== The Assembly line interface ==

This is the newer interface of Apibot. Most testers find it easier and requiring less PHP knowledge than the classic Bridge interface.

It is based on the Unix-like ideology of chaining simple tools to do complex tasks. To use it, you create objects that are specialized in some element of info processing, string them one to another and power up your Frankenstein monster. :-)

For example, let's fix a popular typo in all wiki articles. Copy-paste the code below in your PHP file, possibly with your changes.

After including the needed files, we create first a ''feeder'' - object that will supply the data to be processed. (In this case - all wiki articles.)

Then, we create a ''filter'' that will remove the redirects from the conveyer belt (these are not articles), and link it to the feeder.

Then, we create a ''worker'' that replaces the typo in the text (and provides a report for the page edit subject). We tell it what to replace and with what, and link it to the filter. (See how the line grows? :-) )

Then, we create a ''writer'' that submits the edited page (if it was changed) back to the wiki, and link it to the worker.

Finally, we kick the feeder to start feeding. Voila! :-)
<pre>
require_once ( dirname ( __FILE__ ) . '/apibot/line/feeders/query/list/allpages.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/line/filters/page/text/non_redirect.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/line/workers/edit/replace_strings.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/line/writers/wiki/edit.php' );

$feeder = new Feeder_Query_List_Allpages ( $mains );
$feeder->set_param ( 'ns', 0 );  // will move over namespace 0 - that of the articles

$filter_nr = new Filter_IsNonRedirect ( $mains ); // redirects are not articles
$filter_nr->link_to ( $feeder );

$replaces = array (
  'string' => 'Teh ',
  'with' => 'The ',
  'report' => '$1 typo(s) fixed',
);
$worker_rs = new Worker_EditPage_ReplaceStrings ( $mains, $replaces );
$worker_rs->link_to ( $filter_nr );

$writer_edit = new Writer_Edit ( $mains );
$writer_edit->link_to ( $worker_rs );

$feeder->feed();
</pre>
Or, let's say that a vandal spoiled hundreds of pages overnight. Why rollback all by hand? Let the bot do the job:
<pre>
require_once ( dirname ( __FILE__ ) . '/apibot/line/feeders/query/list/usercontribs.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/line/filters/misc/unique.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/line/writers/wiki/rollback.php' );

$feeder = new Feeder_Query_List_Usercontribs ( $mains );
$feeder->set_list_param ( 'user', "Nasty Vandal" );  // the vandal username, obviously

$filter = new Filter_Unique ( $mains );
$filter->link_to ( $feeder );

$writer = new Writer_Wiki_Rollback ( $mains );
$writer->user = "Nasty Vandal";
$writer->link_to ( $filter );

$feeder->feed();
</pre>
(Create a feeder that supplies all contributions of the vandal. Then link to it a filter that removes duplicates - let's save some resources. Then, link a writer that rollbacks the page mentioned in the user contribution, or whatever page title contains the data passed to the filter. Finally, start the feeder. :-) )

See also:

* [[Apibot 0.40 Line classes|Assembly Line classes]]