Difference between revisions of "Apibot 0.40 examples"

From Apibot
Jump to: navigation, search
(some examples for the Bridge interface)
 
m (2 replacements)
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
== The Bridge interface ==
+
You can find some examples at the links below:
  
This is the interface similar to most MediaWiki bots (including Apibot 0.3x).
+
* [[Bridge examples|Bridge interface examples]]
 
+
* [[Assembly line examples|Assembly line interface examples]]
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 <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:
 
 
 
<pre>
 
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
 
</pre>
 
 
 
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...).
 
 
 
Copy and paste in your PHP file the following code, under the code from above:
 
 
 
<pre>
 
$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
 
</pre>
 
 
 
=== 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 <code>Mains</code> and <code>Bridge</code> 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 ====
 
<pre>
 
$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
 
</pre>
 
 
 
==== Block an user ====
 
<pre>
 
$bridge->block ( "Nasty Vandal", "You deserved it!" );  // this person is really harmful - end with it!
 
</pre>
 
 
 
==== Delete page (by title) ====
 
<pre>
 
$bridge->delete_title ( "My Failed Attempt", "This was a garbage, sorry" );  // no need to clutter the wiki
 
</pre>
 
(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.
 
<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 ====
 
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.
 
<pre>
 
$bridge->emailuser ( "My Friend", $subject, $message_text );  // $subject and $message_text are set to the obvious.
 
</pre>
 
 
 
==== 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.
 
<pre>
 
$bridge->expandtemplates ( $text );  // $text contains some wikitext
 
</pre>
 
 
 
==== Import text from interwiki ====
 
On a multi-language installation, you can import the text of an another language wiki article.
 
<pre>
 
$bridge->import_interwiki ( "My New Page", "Will translate this tomorrow", "de" );  // import from the German wiki
 
</pre>
 
 
 
==== 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
 
</pre>
 
 
 
==== Move (rename) a page (by title) ====
 
<pre>
 
$bridge->move_title ( "Old Title", "New Title", "This name suits it better" );
 
</pre>
 
(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
 
</pre>
 
(On some wikis you might need certain privileges to move pages.)
 
 
 
==== Parse (render to HTML) a page ====
 
<pre>
 
$html = $bridge->parse_page ( "My Beloved Page" );
 
</pre>
 
($html will contain the HTML code for the page.)
 
 
 
==== Parse (render to HTML) arbitrary text ====
 
<pre>
 
$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 ====
 
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."
 
<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 ====
 
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
 
</pre>
 
(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.
 
<pre>
 
$bridge->purge ( "Lagging Page" );
 
</pre>
 
 
 
==== 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.
 
<pre>
 
$bridge->rollback ( "Vandalized Page", "Cleaning the muck", "Nasty Vandal" );
 
</pre>
 
 
 
==== Unblock an user ====
 
<pre>
 
$bridge->unblock ( "Framed Innocent", "Sorry, that was a mistake - my apologies!" );
 
</pre>
 
 
 
==== Undelete deleted page revisions ====
 
<pre>
 
$bridge->undelete ( "Page Title", "Deleted by mistake", $timestamps ); // $timestamps are these of the deleted revisions
 
</pre>
 
 
 
==== Undo page edits ====
 
<pre>
 
$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) ====
 
<pre>
 
$bridge->unwatch ( "Page Title" );
 
</pre>
 
(You will probably use the bot to unwatch pages from your account. :-) )
 
 
 
==== Upload a file ====
 
<pre>
 
$bridge->upload_file ( "My Photo.JPG", "Will use it on my user page", $file_body );
 
</pre>
 
(There are also other page upload functions.)
 
 
 
==== Changes user rights ====
 
<pre>
 
$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.)
 
(In most wikis you need certain privileges to change user rights.)
 
 
 
==== Watch (mark page as watched) ====
 
<pre>
 
$bridge->watch ( "Page Title" );
 
</pre>
 
(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:
 
<pre>
 
$query_revs = $bridge->query_title_revisions ( $title );
 
$query_l_af = $bridge->query_list_allfiles();
 
</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.
 
<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>
 
 
 
Queries are typically used in this way:
 
<pre>
 
$result = $query->xfer();
 
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.
 

Latest revision as of 02:50, 14 April 2014

You can find some examples at the links below: