Difference between revisions of "Apibot 0.40 examples"

From Apibot
Jump to: navigation, search
(some examples for the Bridge interface)
 
(more info, more compact presentation)
Line 1: Line 1:
== The Bridge interface ==
+
== 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 (but does require you to know the basics of using Apibot). For an average computer user this will be about an hour of learning. :-)
  
This is the interface similar to most MediaWiki bots (including Apibot 0.3x).
+
For the rest, read further:
  
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'.
+
== The Mains object ==
  
First of all, you must include the PHP files you need. For the Bridge interface, these are:
+
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''.
  
* the bot global settings file (the bot will go even without them, but they might be handy)
+
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.
* the bot accounts file (currently the bot will not work anonymously - a matter of wiki etiquette)
 
* the <code>mains.php</code> file (most bot modules need some standard infrastructure provided by the <code>Mains</code> class)
 
* the <code>bridge.php</code> file (this is where the <code>Bridge</code> class, which you need, is implemented)
 
  
Copy and paste in your PHP file the following code:
+
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>
 
<pre>
require_once ( dirname ( __FILE__ ) . '/Apibot/settings.php' );   // the bot general settings
+
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
require_once ( dirname ( __FILE__ ) . '/Apibot/logins.php' );     // your logins are described here
+
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/Apibot/mains/mains.php' ); // standard infrastructure most bot modules need
+
require_once ( dirname ( __FILE__ ) . '/apibot/mains/mains.php' );
require_once ( dirname ( __FILE__ ) . '/Apibot/mains/bridge.php' );// the command bridge interface itself
+
 
 +
$mains = new Mains ( $logins['My_Username@en.wikipedia.org'], $bot_settings );
 
</pre>
 
</pre>
 +
(Hint: Copy and paste these. The file paths here assume that Apibot is in a subdirectory of the current directory, named "apibot".)
  
Then, you have to create a <code>Mains</code> class object, and to use it to create a <code>Bridge</code> class object. The latter exports the functions that work with the wiki, or return different <code>Query</code> objects that can requests lists of wiki objects (pages, revisions, log entries, recent changes...).
+
== The Bridge interface ==
  
Copy and paste in your PHP file the following code, under the code from above:
+
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>
 
<pre>
$mains = new Mains ( $logins['My_Account@en.wikipedia.org'], $bot_settings ); // create the standard infrastructure object
+
require_once ( dirname ( __FILE__ ) . '/apibot/bridge.php' );
$bridge = new Bridge ( $mains );                                             // create the command bridge object
+
 
 +
$bridge = new Bridge ( $mains );
 
</pre>
 
</pre>
  
=== Examples for the non-Query Bridge functions ===
+
=== Query 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 <code>Mains</code> and <code>Bridge</code> modules. Modify it to suit your needs, and run it. :-)
+
The Bridge interface gives you the means to query the wiki. MediaWiki can supply many types of info about the wiki. Accordingly, the Bridge interface allows for many different types of queries.
  
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.
+
The common scheme is that you call a Bridge function that creates for you a Query 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.
  
==== Edit a page ====
+
Here are some examples on creating a Query object:
 
<pre>
 
<pre>
$page = $bridge->fetch_editable ( "My Pride of a Page" ); // get the page I work on
+
$query_revs = $bridge->query_title_revisions ( $title );
$page->replace_string ( "Teh", "The" );                    // replace everywhere in it this nasty typo
+
$query_l_au = $bridge->query_list_allusers();
$bridge->edit ( $page, "Fixed a nagging typo", true );     // update the page with this comment and a Minor change flag
 
 
</pre>
 
</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 );
  
==== Block an user ====
+
$query_l_af = $bridge->query_list_allfiles ( $params, $settings );
<pre>
+
$query_l_af = $bridge->query_list_allfiles ( $params );
$bridge->block ( "Nasty Vandal", "You deserved it!" ); // this person is really harmful - end with it!
+
$query_l_af = $bridge->query_list_allfiles ( NULL, $settings );
 
</pre>
 
</pre>
  
==== Delete page (by title) ====
+
Query objects can supply wiki information according to their type. Here is the typical way to use them:
 
<pre>
 
<pre>
$bridge->delete_title ( "My Failed Attempt", "This was a garbage, sorry" ); // no need to clutter the wiki
+
$result = $query->xfer();
 +
while ( $result )
 +
{
 +
  foreach ( $query->data as $element )
 +
  {
 +
    // process the data element
 +
  }
 +
  $result = $query->next();
 +
}
 
</pre>
 
</pre>
(On most wikis you will need administrator rights to be able to delete pages.)
+
Queries also export some other functions - setting parameters to them, etc.
 +
 
 +
See also:
 +
 
 +
* [[Apibot 0.40 Bridge Query functions|Bridge Query functions list]]
 +
* [[Apibot 0.40 Action 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.
  
==== 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.
 
 
<pre>
 
<pre>
$bridge->delete_pageid ( 32187, "Created by mistake" );  // no need to clutter the wiki
 
</pre>
 
(On most wikis you will need administrator rights to be able to delete pages.)
 
  
==== Send an email to another user ====
+
// Edit a page
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.
+
$page = $bridge->fetch_editable ( "My Pride of a Page" );  // get the page I work on
<pre>
+
$page->replace_string ( "Teh", "The" );                    // replace everywhere in it this nasty typo
$bridge->emailuser ( "My Friend", $subject, $message_text ); // $subject and $message_text are set to the obvious.
+
$bridge->edit ( $page, "Fixed a nagging typo", true );    // update the page with this comment and a Minor change flag
</pre>
+
 
 +
// 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 ====
+
// Expand page templates (as if they are directly embedded in the text instead of called by name):
This function allows you to see the wikitext as if all its templates were directly embedded in it instead of just called.
 
<pre>
 
 
$bridge->expandtemplates ( $text );  // $text contains some wikitext
 
$bridge->expandtemplates ( $text );  // $text contains some wikitext
</pre>
 
  
==== Import text from interwiki ====
+
// Import text from interwiki (on a multi-language installation):
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" );
<pre>
 
$bridge->import_interwiki ( "My New Page", "Will translate this tomorrow", "de" ); // import from the German wiki
 
</pre>
 
  
==== Import text from a XML file ====
+
// Import text from a XML file:
You can import text of one or more pages from an appropriately structured XML file.
 
<pre>
 
 
$bridge->import_xml ( $xml_file, "These pages were prepared offline - get them!" ); // $xml_file contains the file
 
$bridge->import_xml ( $xml_file, "These pages were prepared offline - get them!" ); // $xml_file contains the file
</pre>
 
  
==== Move (rename) a page (by title) ====
+
// Move (rename) a page (on some wikis you might need certain rights):
<pre>
+
// ... by title:
 
$bridge->move_title ( "Old Title", "New Title", "This name suits it better" );
 
$bridge->move_title ( "Old Title", "New Title", "This name suits it better" );
</pre>
+
// ... by pageid:
(On some wikis you might need certain privileges to move pages.)
 
 
 
==== Move (rename) a page (by pageid) ====
 
<pre>
 
 
$bridge->move_title ( 473843, "New Title", "This name suits it better" );  // 473843 is the pageid of the page
 
$bridge->move_title ( 473843, "New Title", "This name suits it better" );  // 473843 is the pageid of the page
</pre>
 
(On some wikis you might need certain privileges to move pages.)
 
  
==== Parse (render to HTML) a page ====
+
// Parse (render to HTML) a page:
<pre>
+
$html = $bridge->parse_page ( "My Beloved Page" ); // $html will contain the HTML code for the page.
$html = $bridge->parse_page ( "My Beloved Page" );
 
</pre>
 
($html will contain the HTML code for the page.)
 
  
==== Parse (render to HTML) arbitrary text ====
+
// Parse (render to HTML) arbitrary text:
<pre>
 
 
$html = $bridge->parse_text ( $text );  // $text contains the text to be parsed to HTML
 
$html = $bridge->parse_text ( $text );  // $text contains the text to be parsed to HTML
</pre>
 
($html will contain the HTML code for the text.)
 
  
==== Patrol a recentchange by ID ====
+
// Patrol a recentchange by ID (mark it to tell the other users "Already checked - don't waste time on it"):
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. On most wikis you need certain rights.
<pre>
 
$bridge->patrol ( 387393783 );  // 387393783 is the RCID you want to mark as patrolled.
 
</pre>
 
(On most wikis you need certain privileges to be able to mark changes as patrolled.)
 
  
==== Protect a page ====
+
// Protect a page (require mininal rights to change it; on most wikis you need certain rights to do this):
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.
 
<pre>
 
 
$bridge->protect ( "Disputed Page", "Calm down that edit war!", $protections );  // $protections contains a desc
 
$bridge->protect ( "Disputed Page", "Calm down that edit war!", $protections );  // $protections contains a desc
</pre>
 
(On most wikis you need certain privileges to be able to protect pages.)
 
  
==== Purge ====
+
// Purge page cache:
Sometimes a page cache lags behind the changes in it. In some of these cases it might be better to get it moving.
 
<pre>
 
 
$bridge->purge ( "Lagging Page" );
 
$bridge->purge ( "Lagging Page" );
</pre>
 
  
==== Rollback user changes ====
+
// Rollback (last user changes back to another user's change):
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.
 
<pre>
 
 
$bridge->rollback ( "Vandalized Page", "Cleaning the muck", "Nasty Vandal" );
 
$bridge->rollback ( "Vandalized Page", "Cleaning the muck", "Nasty Vandal" );
</pre>
 
  
==== Unblock an user ====
+
// Unblock an user:
<pre>
 
 
$bridge->unblock ( "Framed Innocent", "Sorry, that was a mistake - my apologies!" );
 
$bridge->unblock ( "Framed Innocent", "Sorry, that was a mistake - my apologies!" );
</pre>
 
  
==== Undelete deleted page revisions ====
+
// Undelete deleted page revisions:
<pre>
 
 
$bridge->undelete ( "Page Title", "Deleted by mistake", $timestamps ); // $timestamps are these of the deleted revisions
 
$bridge->undelete ( "Page Title", "Deleted by mistake", $timestamps ); // $timestamps are these of the deleted revisions
</pre>
 
  
==== Undo page edits ====
+
// Undo page edits:
<pre>
 
 
$bridge->undo ( "Page Title", "Misguided changes", $from_revid, $to_revid );  // revision IDs to start with and go until
 
$bridge->undo ( "Page Title", "Misguided changes", $from_revid, $to_revid );  // revision IDs to start with and go until
</pre>
 
  
==== Unwatch (mark page as not watched) ====
+
// Unwatch (mark page as not watched; typically you do this for your account, not for a bot one :-) ):
<pre>
 
 
$bridge->unwatch ( "Page Title" );
 
$bridge->unwatch ( "Page Title" );
</pre>
 
(You will probably use the bot to unwatch pages from your account. :-) )
 
  
==== Upload a file ====
+
// Upload a file:
<pre>
 
 
$bridge->upload_file ( "My Photo.JPG", "Will use it on my user page", $file_body );
 
$bridge->upload_file ( "My Photo.JPG", "Will use it on my user page", $file_body );
</pre>
+
// (There are also other page upload functions.)
(There are also other page upload functions.)
 
  
==== Changes user rights ====
+
// Changes user rights:
<pre>
 
 
$bridge->userrights ( "Elected For Sysop", "Giving him the privileges", array ( "sysop" ), array() );
 
$bridge->userrights ( "Elected For Sysop", "Giving him the privileges", array ( "sysop" ), array() );
</pre>
+
// (The first array contains the groups the user must gain. The second one contains the group s/he must lose.)
(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.)
(In most wikis you need certain privileges to change user rights.)
 
  
==== Watch (mark page as watched) ====
+
// Watch (mark page as watched; typically you do this for your account, not for a bot one :-) ):
<pre>
 
 
$bridge->watch ( "Page Title" );
 
$bridge->watch ( "Page Title" );
 
</pre>
 
</pre>
(You will probably use the bot to watch pages from your account. :-) )
 
  
=== Examples for the Query Bridge functions ===
+
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 to be significantly easier and requiring less PHP knowledge than the classic Bridge interface.
  
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:
+
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 and power the resulting Frankenstein. :-)
 +
 
 +
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 take the redirects away from the 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>
 
<pre>
$query_revs = $bridge->query_title_revisions ( $title );
+
require_once ( dirname ( __FILE__ ) . '/apibot/line/feeders/query/list/allpages.php' );
$query_l_af = $bridge->query_list_allfiles();
+
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>
 
</pre>
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.
+
Or, let's say that a vandal spoiled hundreds of pages overnight. Why rollback all by hand? Let the bot do the job:
 
<pre>
 
<pre>
$query_revs = $bridge->query_title_revisions ( $title, $params, $settings );
+
require_once ( dirname ( __FILE__ ) . '/apibot/line/feeders/query/list/usercontribs.php' );
$query_revs = $bridge->query_title_revisions ( $title, $params );
+
require_once ( dirname ( __FILE__ ) . '/apibot/line/filters/misc/unique.php' );
$query_revs = $bridge->query_title_revisions ( $title, NULL, $settings );
+
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 );
  
$query_l_af = $bridge->query_list_allfiles ( $params, $settings );
+
$feeder->feed();
$query_l_af = $bridge->query_list_allfiles ( $params );
 
$query_l_af = $bridge->query_list_allfiles ( NULL, $settings );
 
 
</pre>
 
</pre>
 +
(We set a feeder that supplies all contributions of the vandal. Then we link to it a filter that removes duplicates - let's save some resources. Then, we link a writer that rollbacks the page mentioned in the user contribution, or whatever page title contains the data passed to it. Finally, we start the feeder. :-) )
  
Queries are typically used in this way:
+
See also:
<pre>
+
 
$result = $query->xfer();
+
* [[Apibot 0.40 Line classes|Assembly Line classes]]
while ( $result )
 
{
 
  foreach ( $query->data as $element )
 
  {
 
    // do your element processing
 
  }
 
  $result = $query->next();
 
}
 
</pre>
 
Queries also support a lot of other functions - parameters setting, etc.
 

Revision as of 23:49, 8 December 2012

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 (but does require you to know 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 logins.php. The bot settings are typically defined in an array, named $bot_settings and defined in settings.php. Finally, the Mains class is defined in the file mains/mains.php.

To create a Mains object, put somewhere in the beginning of your PHP file lines like these:

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 );

(Hint: Copy and paste these. The file paths here assume that Apibot is in a subdirectory of the current directory, named "apibot".)

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 Bridge class, implemented in the file bridge.php. Insert in your PHP file, under the lines that create the $mains object, lines like the following:

require_once ( dirname ( __FILE__ ) . '/apibot/bridge.php' );

$bridge = new Bridge ( $mains );

Query functions

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

The common scheme is that you call a Bridge function that creates for you a Query 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.

Here are some examples on creating a Query object:

$query_revs = $bridge->query_title_revisions ( $title );
$query_l_au = $bridge->query_list_allusers();

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:

$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 );

Query objects can supply wiki information according to their type. Here is the typical way to use them:

$result = $query->xfer();
while ( $result )
{
  foreach ( $query->data as $element )
  {
     // process the data element
  }
  $result = $query->next();
}

Queries also export some other functions - setting parameters to them, etc.

See also:

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.


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

See also:

The Assembly line interface

This is the newer interface of Apibot. Most testers find it to be significantly 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 and power the resulting Frankenstein. :-)

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 take the redirects away from the 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! :-)

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();

Or, let's say that a vandal spoiled hundreds of pages overnight. Why rollback all by hand? Let the bot do the job:

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();

(We set a feeder that supplies all contributions of the vandal. Then we link to it a filter that removes duplicates - let's save some resources. Then, we link a writer that rollbacks the page mentioned in the user contribution, or whatever page title contains the data passed to it. Finally, we start the feeder. :-) )

See also: