- Features
- Download
- Install
- Command line tools
- API framework showcase
- Start: select your wiki
- Basic API query
- API query with continuation
- Login and Edit API query
- Quick start bot wizard and serious-business error management
- Wikidata SPARQL query
- Wikidata edit API
- Upload API query
- Where to test
- How to add another Wiki
- How to contribute? How to pull request?
- Other examples?
- Troubleshooting
- Testing Unit Files
- Known usages
First steps with boz-mw MediaWiki API framework
This is boz-mw, another MediaWiki API handler in PHP with batteries included! It has a tons of features that will make your head spin!
This is a library to interact with MediaWiki and Wikibase APIs. There are also some boz-mw command line tools.
Features
You may ask what we can offer to you:
- read/write support for Wikidata
- read/write support for Wikimedia Commons' Structured Data
- file upload support for Wikimedia Commons
- support for some other known wiki(s)
- support for your custom wiki
- lightweight project, well designed using OOP
- it does not require Composer, but it's on Composer
- it supports all versions from PHP 5.5 to PHP 8.2
Actually, this framework is useful for:
- developers, to create bots
- command line users for our #Command line tools
Download
git clone https://gitpull.it/source/boz-mw.git
Install
apt install php-cli php-curl
Command line tools
See command line tools.
Command line script replace.php
The replace.php allows you to do some sobstitutions in a wiki.
Command line script mega-export.php
The mega-export.php allows you to export the _full_ page history of whatever page.
API framework showcase
Here some usage examples.
Start: select your wiki
First of all you should init a wiki:
<?php require 'boz-mw/autoload-with-laser-cannon.php'; // load Wikidata $wikidata = wikidata(); // load Wikidata (this is the same) // $wikidata = wiki( 'wikidatawiki' ); // load Wikidata (this is the same) // $wikidata = \wm\Wikidata::instance(); // load Wikipedia in Italian (this is the same) $itwiki = itwiki(); // load Wikipedia in Italian (this is the same) // $itwiki = wiki( 'itwiki' ); // load Wikimedia Commons $commons = commons(); // load Wikimedia Commons (this is the same) // $commons = wiki( 'commonswiki' ); // load Wikimedia Commons (this is the same) // $commons = \wm\Commons::instance(); // load Meta-Wiki $meta = meta(); // load Meta-wiki (this is the same) // $meta = wiki( 'metawiki' ); // load Meta-wiki this is the same // $meta = \wm\MetaWiki::instance();
Basic API query
To obtain a simple information from the server (no continuation support):
<?php require 'boz-mw/autoload-with-laser-cannon.php'; // load it.wiki $wiki = itwiki(); $response = $wiki->fetch( [ 'action' => 'query', 'prop' => 'info', 'titles' => 'Pagina principale', ] ); // get the first result (the only one) $page = $response->query->pages[ 0 ]; // show interesting information print_r( $page->title ); print_r( $page->pageid );
Note: See MediaWiki API action=query documentation.
API query with continuation
To obtain a long result set from the server (with continuation support):
<?php require 'boz-mw/autoload-with-laser-cannon.php'; $wiki = itwiki(); $request = $wiki->createQuery( [ 'action' => 'query', 'list' => 'categorymembers', 'cmtitle' => 'Categoria:Software con licenza GNU GPL', ] ); // automatic query continuation foreach( $request as $response ) { // loop each category member $pages = $response->query->categorymembers ?? []; foreach( $pages as $page ) { // do something var_dump( $page->pageid ); var_dump( $page->ns ); var_dump( $page->title ); print_r( $page ); } }
Login and Edit API query
<?php require 'boz-mw/autoload-with-laser-cannon.php'; // insert here your bot username and password from your wiki // https://meta.wikimedia.org/wiki/Special:BotPasswords $bot_user = ''; $bot_password = ''; // pick a wiki $wiki = itwiki(); // login $wiki->login( $bot_user, $bot_password ); // save a page // if something bad happen here, it will quit your program (throwing a detailed exception) $response = $wiki->edit( [ 'title' => 'Wikipedia:Pagina delle prove', 'text' => 'My test wikitext with boz-mw (sorry for this test)', 'summary' => 'My test edit summary with boz-mw (sorry for this test)', ] ); // do something here // a number var_dump( $response->edit->pageid ); // a number var_dump( $response->edit->oldrevid ); // a number var_dump( $response->edit->newrevid );
This example works. If you run this example this page will be edited:
Please do not abuse!
Quick start bot wizard and serious-business error management
Do you need to configure your bot with its username and password? We have a wizard for that!
<?php require 'boz-mw/autoload-with-laser-cannon.php'; /* * Check your configuration * * A nice wizard will help you if it does not exist <3 */ config_wizard( 'config.php' ); /* * Login in your wiki * * It uses your bot username and password from your config. */ $wiki = itwiki()->login(); /* * Set the page you want to edit * * This is an not-writable example to try what happens! <3 */ $page_title = 'Special:Nothing'; /** * Try to save the page * * The "try" block is useful to "catch" errors instead of dying. * */ try { // try to save a page $response = $wiki->edit( [ 'title' => $page_title, 'text' => 'My test wikitext with boz-mw (sorry for this test)', 'summary' => 'My test edit summary with boz-mw (sorry for this test)', ] ); // if you are here everything was OK // do something here // a number var_dump( $response->edit->pageid ); // a number var_dump( $response->edit->oldrevid ); // a number var_dump( $response->edit->newrevid ); /** * The catch block can be used to detect a specific exception * * Some of them: * MaxLagException * PageCannotExistException * EditConflictException * ProtectedPageException * ReadApiDeniedException * ReadOnlyException * PermissionDeniedException * PageCannotExistException * * and more! * * In this case we will detect the 'page cannot exist' exception. */ } catch( API\PageCannotExistException $e ) { echo "Sorry but you are editing a page that cannot exist. \n"; // generic error handler } catch( Exception $e ) { // other exceptions echo "Something unexpected happened: "; echo $e->getMessage(); echo "\n"; } // do something in any case echo "End. \n";
This example works. If you run this example this page will be edited:
Please do not abuse!
\mw\API::$DEFAULT_USERNAME = '': \mw\API::$DEFAULT_PASSWORD = '';
Wikidata SPARQL query
What if you want to list all the cats from Wikidata?
<?php require 'boz-mw/autoload-with-laser-cannon.php'; $wikidata = wikidata(); // you should know how to build a SPARQL query $query = 'SELECT ?item ?itemLabel WHERE {'; $query .= ' ?item wdt:P31 wd:Q146 '; $query .= ' SERVICE wikibase:label { bd:serviceParam wikibase:language "en". } '; $query .= '}'; // query Wikidata and decode the response $rows = $wikidata::querySPARQL( $query ); // for each cat foreach( $rows as $row ) { // example: 'http://www.wikidata.org/entity/Q5317221' $url = $row->item->value; // example: 'Q5317221' $id = basename( $url ); // example: 'Dusty the Klepto Kitty' $itemLabel = $row->itemLabel->value; echo "Found cat ID: $id. Name: $itemLabel \n"; }
Wikidata edit API
<?php require 'boz-mw/autoload-with-laser-cannon.php'; $data = new \wb\DataModel(); // add a Commons category $statement = new \wb\StatementCommonsCategory( 'P373', 'Test category name' ); $data->addClaim( $statement ); // set a new label value $label = \wb\Label( 'en', "New label" ); $data->setLabel( $label ); // save \wm\Wikidata::instance()->editEntity( 'id' => 'Q4115189', 'data' => $data->getJSON(), ] );
Upload API query
Uploading a file requires to respect the RFC1341 about an HTTP multipart request.
Well, we made it easy:
<?php require 'boz-mw/autoload.php'; // this can be an URL or a local pathname $photo_url = 'http://.../libre-image.jpg'; $wiki->upload( [ 'comment' => 'upload file about...', 'text' => 'bla bla [[bla]]', 'filename' => 'Libre image.jpg', \network\ContentDisposition::createFromNameURLType( 'file', $photo_url, 'image/jpg' ), ] );
Eventually see the ContentDisposition class for some other constructors.
Where to test
Please use your own wiki to test this framework or at least use the Wikimedia Wikis' Sandboxes!
Some known pages you can destroy:
- https://www.wikidata.org/wiki/Q4115189
- https://it.wikipedia.org/wiki/Wikipedia:Pagina_delle_prove_di_Wikidata
- https://en.wikipedia.org/wiki/Wikipedia:Wikidata/Wikidata_Sandbox
- etc.
How to add another Wiki
Thank you for adding another wiki!
To create another wiki, create a file similar to this one:
https://gitpull.it/source/boz-mw/browse/master/include/web/LandscapeforWiki.php
Then, mention it in the list called MediaWikis::allClasses(). Example:
https://gitpull.it/source/boz-mw/browse/master/include/web/MediaWikis.php
Feel free to commit your wiki in the core and send upstream! So other can contribute.
How to contribute? How to pull request?
Thank you for your code contributions! Follow the instructions in the Download and Install sections. Then:
Please start creating a Task here first:
Describe your problem / goal. Then we can help you in sharing your patch with upstream.
After you created the Task, the best method is, run this command from your local repository:
arc diff
And follow the wizard.
Other examples?
Feel free to fork and improve this documentation! Or just look inside the /include directory where there is some inline documentation for you!
Troubleshooting
You can enable debug mode with bozmw_debug(). Example:
<?php require 'boz-mw/autoload-with-laser-cannon.php'; bozmw_debug(); // other code
Testing Unit Files
To run the Unit tests, just execute this in the main directory:
phpunit --bootstrap=phpunit/load.php --testdox phpunit
Known usages
- Last Author
- valerio.bozzolan
- Last Edited
- Mar 7 2023, 20:29