Add user-agent support

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
 
     strategy:
       matrix:
-        php: [ '8.0', '8.1', '8.2', '8.3' ]
+        php: [ '8.1', '8.2', '8.3', '8.5' ]
 
     steps:
     - name: Checkout

README.md

@@ -79,6 +79,16 @@ The default cache times are as follows:
 You can enable logging by passing `WikisourceApi::setLogger()` any object
 that implements [PSR-3's](http://www.php-fig.org/psr/psr-3/) `LoggerInterface`.
 
+## User agent
+
+Don't forget to set a User-Agent with some contact details,
+conforming to the [WMF User-Agent Policy](https://foundation.wikimedia.org/wiki/Special:MyLanguage/Policy:Wikimedia_Foundation_User-Agent_Policy).
+
+```php
+$wsApi = new \Wikisource\Api\WikisourceApi();
+$wgApi->setUserAgent( 'my-example-tool.toolforge.org' );
+```
+
 ## Issues
 
 Please report all issues via Phabricator (tag them with the

src/WikidataQuery.php

@@ -17,6 +17,9 @@ class WikidataQuery {
 	/** @var \Psr\Log\LoggerInterface The logger to use */
 	protected $logger;
 
+	/** @var string HTTP user agent. */
+	protected $userAgent = '';
+
 	/** @var string The Sparql query to run. */
 	protected $query;
 
@@ -28,6 +31,16 @@ public function __construct( $query ) {
 		$this->query = $query;
 	}
 
+	/**
+	 * Set the user agent that will be used when sending API requests.
+	 *
+	 * @param string $userAgent
+	 * @return void
+	 */
+	public function setUserAgent( string $userAgent ): void {
+		$this->userAgent = $userAgent;
+	}
+
 	/**
 	 * Get the results of this query.
 	 * @return string[] Array of results keyed by the names given in the Sparql query.
@@ -48,7 +61,11 @@ public function fetch() {
 	 */
 	protected function getXml( $query ) {
 		$url = "https://query.wikidata.org/bigdata/namespace/wdq/sparql?query=" . urlencode( $query );
-		$client = new Client();
+		$client = new Client( [
+			'headers' => [
+				'User-Agent' => $this->userAgent,
+			],
+		] );
 		$response = $client->request( 'GET', $url );
 		return new SimpleXMLElement( $response->getBody()->getContents() );
 	}

src/WikisourceApi.php

@@ -24,6 +24,9 @@ class WikisourceApi {
 	/** @var \Psr\Log\LoggerInterface The logger to use. */
 	protected $logger;
 
+	/** @var string The HTTP user agent to send with API requests. */
+	protected $userAgent = 'Wikisource PHP API; packagist.org/packages/wikisource/api';
+
 	/**
 	 * Construct a new WikisourceApi object. The logger will default to NullLogger until you set
 	 * something else via WikisourceApi::setLogger().
@@ -44,6 +47,24 @@ public function setLogger( LoggerInterface $logger ) {
 		$this->logger = $logger;
 	}
 
+	/**
+	 * Set the user agent that will be used when sending API requests to Wikisources, Wikidata etc.
+	 *
+	 * @param string $userAgent
+	 * @return void
+	 */
+	public function setUserAgent( string $userAgent ): void {
+		$this->userAgent = $userAgent;
+	}
+
+	/**
+	 * Get the user agent to use when sending API requests.
+	 * @return string
+	 */
+	public function getUserAgent(): string {
+		return $this->userAgent;
+	}
+
 	/**
 	 * Enable caching
 	 * @param CacheItemPoolInterface $pool The cache pool.
@@ -116,6 +137,7 @@ public function fetchWikisources( $cacheLifetime = null ) {
 				. "?lang rdfs:label ?langName . FILTER(LANG(?langName) = ?langCode || "
 				. "( ?langCode = 'mul' && LANG(?langName) = 'en' )) . " . "}";
 			$wdQuery = new WikidataQuery( $query );
+			$wdQuery->setUserAgent( $this->getUserAgent() );
 			$data = $wdQuery->fetch();
 			if ( !is_numeric( $cacheLifetime ) ) {
 				$cacheLifetime = 60 * 60 * 24 * 30;