diff --git a/README.md b/README.md index 3c657e7..b4b81ac 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,51 @@ # Boz-MW This is another MediaWiki API handler in PHP. +## Showcase + +Here some usage examples: + + // autoload classes + require 'autoload.php'; + + // enable verbose messages + \cli\Log::$DEBUG = true; + + echo "Simple Italian Wikipedia API query:\n"; + $WIT = \wm\WikipediaIt::getInstance(); + $response = $WIT->fetch( [ + 'action' => 'query', + 'prop' => 'info', + 'titles' => [ + 'Pagina principale' + ] + ] ); + print_r( $response ); + + echo "Simple Italian Wikipedia API query with continuation support:\n"; + $categories = \wm\WikipediaIt::getInstance()->createQuery( [ + 'action' => 'query', + 'prop' => 'categories', + 'titles' => 'Gallus gallus domesticus' + ] ); + while( $categories->hasNext() ) { + $response = $categories->fetchNext(); + print_r( $response ); + } + + echo "Simple POST request (every POST do an implicit login):\n"; + \mw\API::$DEFAULT_USERNAME = 'My username'; + \mw\API::$DEFAULT_PASSWORD = 'My bot password'; + $wit = \wm\WikipediaIt::getInstance(); + $response = $WIT->post( [ + 'action' => 'edit', + 'title' => 'Special:Nothing', + 'text' => 'My wikitext', + 'summary' => 'My edit summary', + 'token' => $wit->getToken( 'csrf' ), + ] ); + print_r( $response ); + ## Known usage * [wiki-users-leaflet](https://github.com/valerio-bozzolan/wiki-users-leaflet/) hosted at [WMF Labs](https://tools.wmflabs.org/it-wiki-users-leaflet/) diff --git "a/class-mw\\API.php" "b/class-mw\\API.php" index 526a86b..4252237 100644 --- "a/class-mw\\API.php" +++ "b/class-mw\\API.php" @@ -1,290 +1,267 @@ . # MediaWiki namespace mw; /** * Make HTTP request to a MediaWiki API */ class API extends \network\HTTPRequest { /** * MediaWiki tokens handler * * @var mw\Tokens */ private $tokens; /** * Default MediaWiki login username * * @var string */ static $DEFAULT_USERNAME; /** * Default MediaWiki login password * * @var string */ static $DEFAULT_PASSWORD; /** * Default MediaWiki API maxlag * * @var int */ static $DEFAULT_MAXLAG = 5; /** * Default MediaWiki API result format * * @var string */ static $DEFAULT_FORMAT = 'json'; /** * Username used for the login. */ private $username; - /** - * Frequent API response token to continue a result set. - * - * @var mixed - */ - private $continue = null; - /** * Flag to avoid duplicate logins */ private $logged = false; /** * Last API response * * @var mixed */ private $last = null; /** * Constructor * * @param $api string API endpoint */ public function __construct( $api ) { - parent::__construct( $api, [], [] ); + parent::__construct( $api, [] ); $this->tokens = new Tokens( $this ); } + /** + * Create an API query with continuation handler + * + * @param $data array Data + * @return mw\APIQuery + */ + public function createQuery( $data ) { + return new APIQuery( $this, $data ); + } + /** * Effectuate an HTTP POST request but only after a login. * * @param $data array GET/POST data * @param $args array Internal arguments * @override \network\HTTPRequest#post() * @return mixed */ public function post( $data = [], $args = [] ) { if( ! $this->isLogged() ) { $this->login(); } return parent::post( $data, $args ); } /** - * Check if there are other requests to do to fetch the whole result set. - * - * @return bool - */ - public function hasNext() { - // Note that as default continue is NULL - return false !== $this->continue; - } - - /** - * Fetch the next result set. + * Fetch results * + * @param $data array GET/POST data * @return mixed */ - public function fetchNext() { - $data = $this->getData(); - - if( $this->continue ) { - self::log('INFO', "Will continue"); - foreach( $this->continue as $arg => $value ) { - $data[ $arg ] = $value; - } + public function fetch( $data = [], $args = [] ) { + if( [] === $data ) { + throw \InvalidArgumentException( 'empty data' ); } - - $next = $this->fetch( $data ); - - $this->continue = isset( $next->continue ) - ? $next->continue - : false; - - return $next; + return parent::fetch( $data, $args ); } /** * Require some tokens * * @return self */ public function requireTokens( $tokens ) { $this->tokens->require( $tokens ); return $this; } /** * Get the value of a token * * @param $token string Token name * @return string Token value */ public function getToken( $token ) { return $this->tokens->get( $token ); } /** * Invalidate a token * * @param $token string Token name * @return self */ public function invalidateToken( $token ) { $this->tokens->invalidate( $token ); return $this; } /** * Check if it's already logged in. * * @return bool */ public function isLogged() { return $this->logged; } /** * Login into MediaWiki using an username/password pair. * * Yes, I'm talking about a bot password. */ public function login( $username = null, $password = null ) { // Can use a default set of credentials if( ! $username && ! $password ) { $username = self::$DEFAULT_USERNAME; $password = self::$DEFAULT_PASSWORD; } if( ! $username || ! $password ) { throw new \Exception( sprintf( 'you must call %1$s#login( $username, $password ) or '. 'set %1$s::$DEFAULT_USERNAME and %1$s::$DEFAULT_PASSWORD ' . 'before POSTing', __CLASS__ ) ); } // Login $response = parent::post( [ 'action' => 'login', 'lgname' => $username, 'lgpassword' => $password, 'lgtoken' => $this->getToken( Tokens::LOGIN ), + ], [ + 'sensitive' => true ] ); if( ! isset( $response->login->result ) || $response->login->result !== 'Success' ) { throw new \Exception("login failed"); } $this->username = $response->login->lgusername; $this->logged = true; return $this; } - /** - * Set GET/POST data. - * - * As default, it propose a maxlag and a format. - * - * @param $data array GET/POST data - * @override \network\HTTPRequest#setData() - */ - public function setData( $data ) { - $this->continue = null; - $data = array_replace( [ - 'maxlag' => self::$DEFAULT_MAXLAG, - 'format' => self::$DEFAULT_FORMAT - ], $data ); - return parent::setData( $data ); - } - /** * Filters the data before using it. * * Array elements are imploded by a pipe * NULL values are unset * * @override network\HTTPRequest::onDataReady() * @param $data array GET/POST data * @return array */ protected function onDataReady( $data ) { + + // Some default values + $data = array_replace( [ + 'maxlag' => self::$DEFAULT_MAXLAG, + 'format' => self::$DEFAULT_FORMAT, + ], $data ); + foreach( $data as $k => $v ) { if( null === $v ) { unset( $data[ $k ] ); } elseif( is_array( $v ) ) { $data[ $k ] = implode( '|', $v ); } } if( $this->isLogged() ) { $data = array_replace( [ 'assertuser' => $this->username ], $data ); } return $data; } /** * JSON decode and check formal API errors * * @param $result mixed Result * @override \network\HTTPRequest#onFetched() * @throws \mw\API\Exception */ protected function onFetched( $result ) { $result = json_decode( $result ); + if( isset( $result->warnings ) ) { + Log::warn( $result->warnings->main->{'*'} ); + } if( isset( $result->error ) ) { $exception = API\Exception::createFromApiError( $result->error ); if( $exception instanceof MaxLagException ) { // Retry after some time when server lags - self::log( 'WARN', "Lag!" ); + Log::warn( "Lag!" ); $args = array_replace( [ 'wait' => self::WAIT_DOS ], $this->getArgs() ); $result = $this->fetch( $data , $args ); } else { throw $exception; } } return $this->last = $result; } } diff --git "a/class-mw\\APIQuery.php" "b/class-mw\\APIQuery.php" new file mode 100644 index 0000000..8f45974 --- /dev/null +++ "b/class-mw\\APIQuery.php" @@ -0,0 +1,98 @@ +. + +# MediaWiki +namespace mw; + +use cli\Log; + +/** + * MediaWiki API query with continuation handler + */ +class APIQuery { + + /** + * MediaWiki API object + * + * @var mw\API + */ + private $api; + + /** + * Data of the GET/POST request + * + * @var array + */ + private $data; + + /** + * MediaWiki continuation parameter + * + * @var mixed + */ + private $continue = null; + + /** + * Construct + * + * @param $api mw\API + * @param $data array + */ + public function __construct( $api, $data ) { + $this->api = $api; + $this->data = $data; + } + + /** + * Check if there are other requests to do to fetch the whole result set. + * + * @return bool + */ + public function hasNext() { + return $this->continue !== false; + } + + /** + * Fetch the next results + * + * @return mixed + */ + public function fetchNext() { + $data = $this->data; + if( $this->continue ) { + Log::info( "Continuing" ); + foreach( $this->continue as $arg => $value ) { + $data[ $arg ] = $value; + } + } + return $this->fetch( $data ); + } + + /** + * Fetch results + * + * @param $data array GET/POST data + * @return mixed + */ + private function fetch( $data ) { + $latest = $this->api->fetch( $data ); + $this->continue = isset( $latest->continue ) + ? $latest->continue + : false; + return $latest; + } +} diff --git "a/class-mw\\Site.php" "b/class-mw\\Site.php" index fc2a74e..15f1157 100644 --- "a/class-mw\\Site.php" +++ "b/class-mw\\Site.php" @@ -1,246 +1,214 @@ . # MediaWiki namespace mw; class Site { /** * MediaWiki API * * @var API */ private $api; /** * Site namespaces * * @var array Array of namespaces */ private $namespaces = []; /** * A sort of internal UID * * @var null|string E.g. 'enwiki' */ private $uid; /** * Constructor * * @param $url string MediaWiki API URL */ public function __construct( $url ) { - $this->api = self::createApi( $url ); + $this->api = new API( $url ); + } + + /** + * Create an API query with continuation handler + * + * @param $data array GET/POST data arguments + * @return mw\APIQuery + */ + public function createQuery( $data ) { + return $this->getApi()->createQuery( $data ); } /** * Make an HTTP GET request to the API * * @param $data array HTTP GET data * @return mixed API result */ public function fetch( $data ) { return $this->getApi()->fetch( $data ); } /** * Make an HTTP POST request to the API * * This method will call the API#login() method. * * @param $data array HTTP GET data * @return mixed API result */ public function post( $data ) { return $this->getApi()->post( $data ); } /** * Require some tokens * * @return self */ public function requireTokens( $tokens ) { $this->getApi()->requireTokens( $tokens ); return $this; } /** * Get the value of a token * * @param $token string Token name * @return string Token value */ public function getToken( $token ) { return $this->getApi()->getToken( $token ); } /** * Invalidate a token * * @param $token string Token name * @return self */ public function invalidateToken( $token ) { $this->getApi()->invalidateToken( $token ); return $this; } /** * Make a login * * @see API#login() * @param $username string MediaWiki username * @param $password string MediaWiki password * @return self */ public function login( $username = null, $password = null ) { $this->getApi()->login( $username, $password ); return $this; } - /** - * Check if we can continue fetching the next result set - * - * @see API#hasNext() - * @return bool - */ - public function hasNext() { - return $this->getApi()->hasNext(); - } - - /** - * Fetch the next result set - * - * @see API#fetchNext() - * @return mixed Response - */ - public function fetchNext() { - return $this->getApi()->fetchNext(); - } - - /** - * Set the default API data - * - * @see API#setData() - * @data array HTTP GET/POST data - * @return self - */ - public function setApiData( $data ) { - $this->getApi()->setData( $data ); - return $this; - } - /** * Check if a certain namespace ID is registered * * @param int $id Namespace ID * @return bool */ public function hasNamespace( $id ) { return array_key_exists( $id, $this->namespaces ); } /** * Get the namespace related to the specified ID * * @param int $id Namespace ID * @return Ns Corresponding namespace */ public function getNamespace( $id ) { if( ! $this->hasNamespace( $id ) ) { throw new \Exception( sprintf( 'missing namespace %d', $id ) ); } return $this->namespaces[ $id ]; } /** * Set/overwrite a namespace * * @param $namespace Ns Namespace to be set/overwrited * @return self */ public function setNamespace( Ns $namespace ) { $id = $namespace->getID(); $this->namespaces[ $id ] = $namespace; return $this; } /** * Stupid shortcut for setting multiple namespaces * * @param $namespaces array Array of namespaces * @return self */ public function setNamespaces( $namespaces ) { foreach( $namespaces as $namespace ) { $this->setNamespace( $namespace ); } return $this; } /** * Set the UID * * @param string E.g. 'enwiki' * @return self */ public function setUID( $uid ) { $this->uid = $uid; return $this; } /** * Get internal MediaWiki API object * * @return API */ public function getApi() { return $this->api; } /** * Get the UID * * @return null|string e.g. 'enwiki' */ public function getUID() { return $this->uid; } /** * Create a Wikitext object * * @return Wikitext */ public function createWikitext( $wikitext ) { return new Wikitext( $this, $wikitext ); } - - /** - * Create a MediaWiki API object from an API URL - * - * @param $url string API URL - * @return API - */ - private static function createApi( $url ) { - return new API( $url ); - } } diff --git "a/class-network\\HTTPRequest.php" "b/class-network\\HTTPRequest.php" index 589945d..b5fb1d9 100644 --- "a/class-network\\HTTPRequest.php" +++ "b/class-network\\HTTPRequest.php" @@ -1,448 +1,400 @@ . -# MediaWiki +# Network namespace network; +use cli\Log; + /** * HTTP request handler for GET and POST requests. */ class HTTPRequest { /** * Class version * * To be incremented every time do you notice this number. * * @var string */ const VERSION = 0.4; /** * Source code URL * * @var string */ const REPO = 'https://github.com/valerio-bozzolan/boz-mw'; /** * Wait seconds before each GET request. */ static $WAIT = 0.2; /** * Wait seconds before each POST request * * @var float */ static $WAIT_POST = 0.2; /** * Wait seconds before each lag * * @var float */ const WAIT_DOS = 5; /** * Full HTTP URL to the API endpoint * * @var string */ private $api; /** * HTTP GET/POST data * * @var array */ private $data; /** * Internal arguments * * @param array */ private $args; /** * Latest HTTP response headers * * @var array */ private $latestHttpResponseHeaders = []; /** * HTTP cookies * * @var array */ private $cookies = []; - /** - * Flag for debug mode - * - * @var bool - */ - private $debug = false; - /** * Constructor. * * @param $api string API endpoint - * @param $data array GET/POST data * @param $args array Internal arguments */ - public function __construct( $api, $data = [], $args = [] ) { + public function __construct( $api, $args = [] ) { $this->api = $api; - $this->setData( $data ); $this->setArgs( $args ); } /** * Statical constructor. * * @return network\HTTPRequest */ - public static function factory( $api, $data = [], $args = [] ) { - return new self( $api, $data, $args ); - } - - /** - * Get current HTTP GET/POST data. - * - * @return array - */ - public function getData() { - return $this->data; + public static function factory( $api, $args = [] ) { + return new self( $api, $args ); } /** * Get internal arguments. * * @return array */ public function getArgs() { return $this->args; } - /** - * Check if debug mode is enabled - * - * @return bool - */ - public function isDebug() { - return $this->debug; - } - - /** - * Set HTTP GET/POST data for same future requests. - * - * @param $data array GET/POST data - * @return self - */ - public function setData( $data ) { - $this->data = $data; - return $this; - } - - /** - * Toggle debug mode - * - * @return self - */ - public function setDebug( $debug ) { - $this->debug = $debug; - return $this; - } - /** * Set internal arguments * + * method: GET, POST etc. + * user-agent: HTTP user agent + * sensitive: flag to indicate if the data is sensitive and should not be printed as usual in the log + * wait: microseconds to wait after every GET request + * wait-post: microseconds to wait after every POST request + * headers: HTTP headers + * * @param $args array Internal arguments * @return self */ public function setArgs( $args ) { $this->args = array_replace( [ 'method' => 'GET', + 'user-agent' => sprintf( 'boz-mw HTTPRequest.php/%s %s', self::VERSION, self::REPO ), + 'sensitive' => false, 'wait' => self::$WAIT, 'wait-post' => self::$WAIT_POST, - 'user-agent' => sprintf( 'boz-mw HTTPRequest.php/%s %s', self::VERSION, self::REPO ), - 'headers' => [] + 'headers' => [], ], $args ); return $this; } /** * Make an HTTP GET query * * @param $data array GET data * @param $args array Internal arguments * @return mixed Response */ public function fetch( $data = [], $args = [] ) { - $data = array_replace( $this->data, $data ); + $args = array_replace( $this->args, $args ); // Eventually post-process the data before using $data = static::onDataReady( $data ); // HTTP query using file_get_contents() $url = $this->api; $query = http_build_query( $data ); $context = [ 'http' => [] ]; $context['http']['method'] = $args['method']; if( $args['user-agent'] ) { $args['headers'][] = self::header( 'User-Agent', $args['user-agent'] ); } if( $this->haveCookies() ) { $args['headers'][] = $this->getCookieHeader(); } + if( $query ) { if( 'POST' === $args['method'] ) { $args['headers'][] = self::header('Content-Type', 'application/x-www-form-urlencoded' ); $context['http']['content'] = $query; } else { $url .= "?$query"; } } - if( $args['headers'] ) { - $context['http']['header'] = self::implodeHTTPHeaders( $args['headers'] ); + + if( 'GET' === $args['method'] ) { + Log::info( "GET $url" ); + } else { + Log::sensitive( "{$args['method']} $url $query", "{$args['method']} $url" ); } - if( $this->isDebug() ) { - self::log('DEBUG', $url ); - self::log('DEBUG', $args['method'] ); - if( $args['method'] === 'POST' ) { - self::log('DEBUG', $query ); - } + if( $args['headers'] ) { + $context['http']['header'] = self::implodeHTTPHeaders( $args['headers'] ); } if( $args['wait'] ) { - self::log('INFO', sprintf( - "Waiting %.2f s...", + Log::info( sprintf( + "Waiting %.2f s.", $args['wait'] ) ); usleep( $args['wait'] * 1000000 ); } - self::log('INFO', sprintf( - "%s request", - $args['method'] - ) ); - $stream_context = stream_context_create( $context ); $result = file_get_contents( $url, false, $stream_context ); // Here $http_response_header exists magically (PHP merda!) $this->loadHTTPResponseHeaders( $http_response_header ); if( isset( $this->latestHttpResponseHeaders['HTTP/1.1 500 Internal Server Error'] ) ) { - self::log( 'WARN', "500 Internal Server Error!"); + Log::warn( "500 Internal Server Error!" ); $args = array_replace( [ 'wait' => self::WAIT_DOS ], $args ); return $this->fetch( $data , $args ); } - self::log('INFO', "Fetched"); + Log::info( "Fetched" ); return static::onFetched( $result ); } /** * Effectuate an HTTP POST. + * + * @param $data array POST data + * @param $args Internal arguments + * @return mixed Response */ public function post( $data = [], $args = [] ) { - $args = array_replace( [ - 'method' => 'POST', - 'wait' => $this->args['wait-post'] - ], $args ); + $args = array_replace( + [ 'wait' => $this->args['wait-post'] ], + $args, + [ 'method' => 'POST' ] + ); return $this->fetch( $data, $args ); } /** * Get latest HTTP response headers. * * @return array */ public function getLatestHTTPResponseHeaders() { return $this->latestHttpResponseHeaders; } /** * Check if cookies are set * * @return bool */ public function haveCookies() { return isset( $this->cookies ); } /** * Get cookies * * @return array */ public function getCookies() { return $this->cookies; } /** * Set an HTTP cookie name => value pair. * * @param $name string Cookie name * @param $value string Cookie value * @return self */ public function setCookie( $name, $value ) { $this->cookies[ $name ] = $value; return $this; } public function getCookieHeader() { $cookies = []; foreach( $this->getCookies() as $name => $value ) { $cookies[] = urlencode( $name ) . '=' . urlencode( $value ); } return self::headerRaw( 'Cookie', implode( '; ', $cookies ) ); } public function getHTTPCookies() { return $this->cookies; } /** * Set an HTTP cookie in its raw form. * * @param $cookie string Cookie text */ private function setRawCookie( $cookie ) { $parts = explode(';', $cookie); if( isset( $parts[0] ) ) { $name_value = explode('=', $parts[0] ); if( 2 === count( $name_value ) ) { list( $name, $value ) = $name_value; $this->setCookie( $name, $value ); } } } /** * Load HTTP response headers, filling cookies. */ private function loadHTTPResponseHeaders( $http_response_headers ) { $this->latestHttpResponseHeaders = self::parseHTTPResponseHeaders( $http_response_headers ); if( isset( $this->latestHttpResponseHeaders['Set-Cookie'] ) ) { foreach( $this->latestHttpResponseHeaders['Set-Cookie'] as $cookie ) { $this->setRawCookie( $cookie ); } } } private function implodeHTTPHeaders( $headers ) { if( ! $headers ) { return null; } $s = ''; foreach( $headers as $header ) { $s .= "$header\r\n"; } return $s; } /** * Group HTTP headers by keys. * * @return array */ private static function parseHTTPResponseHeaders( $http_response_headers ) { $headers = []; foreach( $http_response_headers as $header ) { $header_parts = explode(':', $header, 2); if( 2 === count( $header_parts ) ) { list( $name, $value ) = $header_parts; if( ! isset( $headers[ $name ] ) ) { $headers[ $name ] = []; } $headers[ $name ][] = ltrim( $value ); } } return $headers; } /** * Make an HTTP header raw string from a name => value pair. * * The value will be URL-encoded. * * @param $name string HTTP header name * @param $value string HTTP header value * @return string HTTP header */ private static function header( $name, $value ) { return self::headerRaw( $name, urlencode( $value ) ); } /** * Make an HTTP header raw string from a name => value pair. * * The value is not URL-encoded. * */ private static function headerRaw( $name, $value ) { return sprintf( '%s: %s', $name, $value ); } - /** - * Print a tedious message to the output. - * - * @param $type string Something like 'warn' - * @param $msg string Log message - */ - protected static function log( $type, $msg ) { - printf("# [%s] \t %s\n", $type, $msg); - } - /** * Can be overrided to post-process the data before its use * * @param $data GET/POST data * @return array GET/POST data post-processed */ protected function onDataReady( $data ) { return $data; } /** * Callback to be overloaded * * This is called every time something is fetched. * * @param $result mixed Result * @return mixed Result */ protected function onFetched( $result ) { return $result; } }