Difference between revisions of "Bridge examples"

From Apibot
Jump to: navigation, search
(+ search / replace example)
m (fixed path)
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
The examples here assume that:
+
Here you can see some examples of typical bot tasks, implemented through the Apibot Bridge interface. (See [[Assembly line examples|here]] for examples using the Assembly line interface.)
 +
 
 +
Most of these would include a query (returned by a [[Bridge Query functions|Bridge Query function]]) that provides all pages matching certain conditions, and a piece of code that works on each of these pages, typically using some [[Bridge Non-Query functions|non-query Bridge functions]].
 +
 
 +
The examples assume that:
 
* Apibot is in a subdirectory of the current directory, named "<code>apibot</code>"
 
* Apibot is in a subdirectory of the current directory, named "<code>apibot</code>"
* the <code>$logins</code> array (probably defined in the file <code>logins.php</code>) contains a bot login with the key <code>My_Bot@en.wikipedia.org</code>.
+
* the <code>$logins</code> array variable (probably defined in the file <code>logins.php</code>) contains a bot login with the key <code>My_Bot@en.wikipedia.org</code>.
* the <code>$bot_settings</code> array (probably defined in the file <code>settings.php</code>) contains the bot settings.
+
* the <code>$bot_settings</code> array variable (probably defined in the file <code>settings.php</code>) contains the bot settings.
  
 
== Fix some popular typos in all articles ==
 
== Fix some popular typos in all articles ==
Line 12: Line 16:
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/mains/mains.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/bridge.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );
  
# Create the Mains object.
+
# Create the Core object.
$mains = new Mains ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
+
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
  
 
# Create the Bridge object.
 
# Create the Bridge object.
$bridge = new Bridge ( $mains );
+
$bridge = new Bridge ( $core );
  
 
$query_params = array();  // no special "core" params for the query object
 
$query_params = array();  // no special "core" params for the query object
Line 33: Line 37:
 
while ( $query_result )
 
while ( $query_result )
 
{
 
{
   foreach ( $query->data as $page )
+
   foreach ( $query->data as $page_data )
 
   {
 
   {
 
     // page text was not fetched by the query - do this
 
     // page text was not fetched by the query - do this
Line 57: Line 61:
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/mains/mains.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/bridge.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );
  
# Create the Mains object.
+
# Create the Core object.
$mains = new Mains ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
+
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
  
 
# Create the Bridge object.
 
# Create the Bridge object.
$bridge = new Bridge ( $mains );
+
$bridge = new Bridge ( $core );
  
 
$query = $bridge->query_list_search ( $query_params, $query_settings );
 
$query = $bridge->query_list_search ( $query_params, $query_settings );
Line 82: Line 86:
 
     $page->replace_string ( "Burma", "Myanmar" );
 
     $page->replace_string ( "Burma", "Myanmar" );
  
     $bridge->edit ( $page, "Burma -> Myanmar" );
+
     $bridge->edit ( $page, "Burma replaced with Myanmar" );
 
   }
 
   }
 
}
 
}
Line 97: Line 101:
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/mains/mains.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/bridge.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );
  
# Create the Mains object.
+
# Create the Core object.
$mains = new Mains ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
+
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
  
 
# Create the Bridge object.
 
# Create the Bridge object.
$bridge = new Bridge ( $mains );
+
$bridge = new Bridge ( $core );
  
 
$query = $bridge->query_list_backlinks ( $query_params, $query_settings );
 
$query = $bridge->query_list_backlinks ( $query_params, $query_settings );
Line 126: Line 130:
 
   }
 
   }
 
}
 
}
 
 
</pre>
 
</pre>
  
Line 139: Line 142:
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/mains/mains.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/bridge.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );
  
# Create the Mains object.
+
# Create the Core object.
$mains = new Mains ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
+
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
  
 
# Create the Bridge object.
 
# Create the Bridge object.
$bridge = new Bridge ( $mains );
+
$bridge = new Bridge ( $core );
  
 
$query = $bridge->query_list_categorymembers ( $query_params, $query_settings );
 
$query = $bridge->query_list_categorymembers ( $query_params, $query_settings );
  
$query->title = $mains->info->namespace_basic_name ( "Category" ) . ":Old Category";
+
$query->title = $core->info->namespace_basic_name ( "Category" ) . ":Old Category";
  
 
$query_result = $query->xfer();
 
$query_result = $query->xfer();
Line 168: Line 171:
 
   }
 
   }
 
}
 
}
 +
</pre>
 +
 +
== Replace a template in all pages ==
 +
 +
Often someone makes a new wiki template that is better and more powerful version of an old one.
 +
 +
Let's replace the old template ("Template:Old Template") with the new one ("Template:New Template") everywhere.
 +
 +
Also, to make the things more interesting, the templates are not completely compatible. The parameter "chairman" in Old Template is replaced by "chairperson" in New Template. We should take into account this, too.
 +
 +
<pre>
 +
# Include the needed modules.
 +
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 +
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
 +
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
 +
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );
 +
 +
# Create the Core object.
 +
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
 +
 +
# Create the Bridge object.
 +
$bridge = new Bridge ( $core );
 +
 +
$query = $bridge->query_list_embeddedin ( $query_params, $query_settings );
 +
 +
$query->title = $core->info->namespace_basic_name ( "Template" ) . ":Old Template";
 +
 +
$query_result = $query->xfer();
 +
 +
while ( $query_result )
 +
{
 +
  foreach ( $query->data as $page_data )
 +
  {
 +
    $page = $bridge->fetch_title ( $page_data );
 +
 +
    $page->replace_template_name ( "Old Template", "New Template" );
 +
    $page->replace_template_paramname ( "New Template", "chairman", "chairperson" );
  
 +
    $bridge->edit ( $page, "Replaced Old Template with New Template" );
 +
  }
 +
}
 
</pre>
 
</pre>
  
Line 179: Line 222:
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/mains/mains.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/bridge.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );
  
# Create the Mains object.
+
# Create the Core object.
$mains = new Mains ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
+
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
  
 
# Create the Bridge object.
 
# Create the Bridge object.
$bridge = new Bridge ( $mains );
+
$bridge = new Bridge ( $core );
  
 
$query = $bridge->query_list_recentchanges ( $query_params, $query_settings );
 
$query = $bridge->query_list_recentchanges ( $query_params, $query_settings );
Line 208: Line 251:
  
 
$bridge->emailuser ( "My Account", "New pages for the last day", $email_text );
 
$bridge->emailuser ( "My Account", "New pages for the last day", $email_text );
 
 
</pre>
 
</pre>
  
Line 219: Line 261:
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
 
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/mains/mains.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/common/bridge.php' );
+
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );
  
# Create the Mains object.
+
# Create the Core object.
$mains = new Mains ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
+
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );
  
 
# Create the Bridge object.
 
# Create the Bridge object.
$bridge = new Bridge ( $mains );
+
$bridge = new Bridge ( $core );
  
 
$query = $bridge->query_list_usercontribs ( $query_params, $query_settings );
 
$query = $bridge->query_list_usercontribs ( $query_params, $query_settings );
Line 244: Line 286:
 
// If your bot has admin rights, you may save yourself future rollbacks:
 
// If your bot has admin rights, you may save yourself future rollbacks:
 
$bridge->block ( "Nasty Vandal", "You deserved it!" );
 
$bridge->block ( "Nasty Vandal", "You deserved it!" );
 
 
</pre>
 
</pre>

Latest revision as of 01:29, 10 November 2014

Here you can see some examples of typical bot tasks, implemented through the Apibot Bridge interface. (See here for examples using the Assembly line interface.)

Most of these would include a query (returned by a Bridge Query function) that provides all pages matching certain conditions, and a piece of code that works on each of these pages, typically using some non-query Bridge functions.

The examples assume that:

  • Apibot is in a subdirectory of the current directory, named "apibot"
  • the $logins array variable (probably defined in the file logins.php) contains a bot login with the key My_Bot@en.wikipedia.org.
  • the $bot_settings array variable (probably defined in the file settings.php) contains the bot settings.

Fix some popular typos in all articles

The pages in the Main namespace are typically called articles, and are the reason for the wiki existence. Spelling typos are not welcome there. Let's fix some.

# Include the needed modules.
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );

# Create the Core object.
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );

# Create the Bridge object.
$bridge = new Bridge ( $core );

$query_params = array();   // no special "core" params for the query object
$query_settings = array(); // no special settings, either

$query = $bridge->query_list_allpages ( $query_params, $query_settings );

$query->namespace = 0;
$query->filterredir = "non-redirects";  // redirect pages don't need check

# Cycle the query and process the pages.
$query_result = $query->xfer();
while ( $query_result )
{
  foreach ( $query->data as $page_data )
  {
    // page text was not fetched by the query - do this
    $page = $bridge->fetch_title ( $page_data['title'] );

    $page->replace_string ( "Teh", "The" );
    $page->replace_string ( "Apiobt", "Apibot" );

    $bridge->edit ( $page, "Fixed some typos" );
  }
  $query_result = $query->next();
}

Change a specific text everywhere

If you make a lot of possible changes in a text, like fixing 1000s of popular typos, it might be worth parsing all articles. However, if you have to change a specific text, it might be better to check only the pages that contain it.

You see an impossibly old wiki that still refers to Myanmar as Burma. Its admin asks you to help replacing the old name everywhere:

# Include the needed modules.
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );

# Create the Core object.
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );

# Create the Bridge object.
$bridge = new Bridge ( $core );

$query = $bridge->query_list_search ( $query_params, $query_settings );

$query->search = "Burma";  // find this string
$query->what   = "text";   // ... in the article text
$query->namespace = 0;     // ... in the wiki articles only

$query_result = $query->xfer();

while ( $query_result )
{
  foreach ( $query->data as $page_data )
  {
    $page = $bridge->fetch_title ( $page_data['title'] );

    $page->replace_string ( "Burma", "Myanmar" );

    $bridge->edit ( $page, "Burma replaced with Myanmar" );
  }
}

Fix all wikilinks pointing to a moved page

A page was moved, but there are a lot of links to it in the wiki. What about fixing them to avoid the need for a redirect?

Assuming that old page title was "Old Title", and the new is "New Title":

# Include the needed modules.
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );

# Create the Core object.
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );

# Create the Bridge object.
$bridge = new Bridge ( $core );

$query = $bridge->query_list_backlinks ( $query_params, $query_settings );

$query->title = "Old Title";

$query_result = $query->xfer();

while ( $query_result )
{
  foreach ( $query->data as $subpage_data )
  {
    $page = $bridge->fetch_title ( $subpage_data );

    $page->replace_wikilink_target ( NULL, NULL, NULL,
      "Old Title", NULL, NULL, "New Title" );
    // parameters are: leading colon, interwiki, namespace, name, anchor, text,
    // new title, replacements count (omitted here). Regex parts may be used.

    $bridge->edit ( $page, "Fixed some wikilinks" );
  }
}

Move pages from a category to another one

What if you need to move a lot of pages from one category to another? (In this example - all of them.)

Assuming that you have to move pages from "Old Category" to "New Category"

# Include the needed modules.
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );

# Create the Core object.
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );

# Create the Bridge object.
$bridge = new Bridge ( $core );

$query = $bridge->query_list_categorymembers ( $query_params, $query_settings );

$query->title = $core->info->namespace_basic_name ( "Category" ) . ":Old Category";

$query_result = $query->xfer();

while ( $query_result )
{
  foreach ( $query->data as $page_data )
  {
    $page = $bridge->fetch_title ( $page_data );

    // if you need to move only some pages, check here if this is one of them.
    // If not, continue the foreach.

    $page->replace_category ( "Old Category", "New Category" );

    $bridge->edit ( $page, "Moved from Old Category to New Category" );
  }
}

Replace a template in all pages

Often someone makes a new wiki template that is better and more powerful version of an old one.

Let's replace the old template ("Template:Old Template") with the new one ("Template:New Template") everywhere.

Also, to make the things more interesting, the templates are not completely compatible. The parameter "chairman" in Old Template is replaced by "chairperson" in New Template. We should take into account this, too.

# Include the needed modules.
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );

# Create the Core object.
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );

# Create the Bridge object.
$bridge = new Bridge ( $core );

$query = $bridge->query_list_embeddedin ( $query_params, $query_settings );

$query->title = $core->info->namespace_basic_name ( "Template" ) . ":Old Template";

$query_result = $query->xfer();

while ( $query_result )
{
  foreach ( $query->data as $page_data )
  {
    $page = $bridge->fetch_title ( $page_data );

    $page->replace_template_name ( "Old Template", "New Template" );
    $page->replace_template_paramname ( "New Template", "chairman", "chairperson" );

    $bridge->edit ( $page, "Replaced Old Template with New Template" );
  }
}

Send by e-mail to an editor a list of the newly created pages

In some wikis it might be useful to see what new pages are created. Let's have a daily list of them sent to you by e-mail.

# Include the needed modules.
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );

# Create the Core object.
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );

# Create the Bridge object.
$bridge = new Bridge ( $core );

$query = $bridge->query_list_recentchanges ( $query_params, $query_settings );

$query->start = date ( 'Y-m-d 00:00:00', time() );
$query->end   = date ( 'Y-m-d 00:00:00', $query->start - 86400 );

$query_result = $query->xfer();

$email_text = "List of the pages created from " . $query->start .
  " to " . $query->end . "\n\n";

while ( $query_result )
{
  foreach ( $query->data as $rc )
  {
    if ( $rc['type'] == "new" )
      $email_text .= "* [[" . $rc['title'] . "]]\n";
  }
}

$bridge->emailuser ( "My Account", "New pages for the last day", $email_text );

Revert all edits done by a prolific vandal

A vandal (going by the account "Nasty Vandal") messed up overnight a thousand pages in your favorite wiki. What about reverting all of his "contributions"?

# Include the needed modules.
require_once ( dirname ( __FILE__ ) . '/apibot/settings.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/logins.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/core/core.php' );
require_once ( dirname ( __FILE__ ) . '/apibot/interfaces/bridge/bridge.php' );

# Create the Core object.
$core = new Core ( $logins['My_Bot@en.wikipedia.org'], $bot_settings );

# Create the Bridge object.
$bridge = new Bridge ( $core );

$query = $bridge->query_list_usercontribs ( $query_params, $query_settings );

$query->user = "Nasty Vandal";

$query_result = $query->xfer();

while ( $query_result )
{
  foreach ( $query->data as $contrib )
  {
    $bridge->rollback ( $contrib['title'], "No vandalisms, please", "Nasty Vandal", true );
  }
}

// If your bot has admin rights, you may save yourself future rollbacks:
$bridge->block ( "Nasty Vandal", "You deserved it!" );