adjust documentation for Client and Adapter changes in 5.2 (#773)

docs/client-and-adapters.md

@@ -17,7 +17,16 @@ The adapters are the actual implementations for communication with Solr. They ha
 
 ### Authentication
 
-The Http, Curl and Pecl adapter support authentication. To use this set the authentication on the request object using the setAuthentication() method. For the ZendHttp adapter you set the authentication using the ZendHttp api or config.
+The Http and Curl adapter support authentication. To use this set the authentication on the request object using the setAuthentication() method.
+
+### HTTP request timeout handling
+
+Setting a timeout for the HTTP request handling is the responsibility of the Adapters.
+The two build-in Adapters `Curl` and `Http` are implementing `TimeoutAwareInterface` and expose a `setTimeout`
+method to give you control over the timeout value that is used.
+
+If you are using any other adapter like the build-in `Psr18Adapter` you need to take care of handling
+the timeouts yourself and configure the HTTP client properly that is used to perform the requests.
 
 Endpoints
 ---------
@@ -43,13 +52,7 @@ As this is the default adapter you don't need any settings or API calls to use i
 The curl adapter support the use of a proxy. Use the adapter option `proxy` to enable this.
 
 
-Guzzle adapter
-==============
-
-todo
-
-
-HttpAdapter
+Http adapter
 ===========
 
 This adapter has no dependencies on other classes or any special PHP extensions as it uses basic PHP streams. This makes it a safe choice, but it has no extra options. If you need detailed control over your request or response you should probably use another adapter, but for most standard cases it will do just fine.
@@ -64,10 +67,11 @@ require(__DIR__.'/init.php');
 htmlHeader();
 
 // create a client instance
-$client = new Solarium\Client($config);
-
-// set the adapter to curl
-$client->setAdapter('Solarium\Core\Client\Adapter\Http');
+$client = new Solarium\Client(
+    new Solarium\Core\Client\Adapter\Http(), 
+    new Symfony\Component\EventDispatcher\EventDispatcher(),
+    $config
+);
 
 // get a select query instance
 $query = $client->createSelect();
@@ -100,34 +104,29 @@ htmlFooter();
 
 ```
 
-Zend2Http adapter
-================
-
-The ZendHttp adapter makes use of the Zend\_Http component in Zend Framework (version 3). So to use this adapter you need to have ZF available. By using Zend\_Http all the features of this component are available:
+Psr-18 adapter
+============
 
--   multiple adapter implementations
--   keepalive
--   cookies / sessions
--   redirection support
--   http authentication
--   and much more, see the [http://framework.zend.com/manual/en/zend.http.html Zend Http manual](http://framework.zend.com/manual/en/zend.http.html_Zend_Http_manual "wikilink")
+Since Solarium 5.2 there is also a `Psr18Adapter` which can be used with any PSR-18 compliant HTTP client.
 
-The base functionality is the same as the default adapter. The only difference is that this adapter allows you to set Zend\_Http options and also offers access to the Zend\_Http instance.
+Example:
 
 ```php
 <?php
 
-require(__DIR__.'/init.php');
-htmlHeader();
-
-// create a client instance
-$client = new Solarium\Client($config);
-
-// set the adapter to zendhttp and get a zendhttp client instance reference
-$client->setAdapter('Solarium\Core\Client\Adapter\Zend2Http');
+use Nyholm\Psr7\Factory\Psr17Factory;
+use Solarium\Client;
+use Http\Adapter\Guzzle6\Client as GuzzlePsrClient;
+use Solarium\Core\Client\Adapter\Psr18Adapter;
+use Symfony\Component\EventDispatcher\EventDispatcher;
 
-htmlFooter();
+$adapter = new Psr18Adapter(
+    new GuzzlePsrClient(),
+    new Psr17Factory(),
+    new Psr17Factory()
+);
 
+$client = new Client($adapter, new EventDispatcher());
 ```
 
 Custom adapter
@@ -138,6 +137,5 @@ You can also use a custom adapter, with these steps:
 -   Create your custom adapter class. It should implement Solarium\\Core\\Client\\Adapter\\AdapterInterface.
 -   You can take a look at the existing implementations as an example.
 -   Make sure your class is available to Solarium, by including it manually or through autoloading.
--   Call the 'setAdapter' method on your Solarium client instance with your own adapters' classname as argument (or use the 'adapter' config setting)
+-   Inject your custom adapter instance into the constructor of the Client
 -   Now use Solarium as you normally would, all communication to Solr will be done using your adapter. The adapter class will only be instantiated on the first communication to Solr, not directly after calling 'setAdapter' (lazy loading)
-

docs/customizing-solarium.md

@@ -38,9 +38,10 @@ htmlHeader();
 // And you can use only a part of the flow. You could for instance use the query object and request builder,
 // but execute the request in your own code.
 
+// ...
 
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // create a select query instance
 $query = $client->createSelect();
@@ -200,7 +201,11 @@ htmlHeader();
 
 // create a client instance and register the plugin
 $plugin = new BasicDebug();
-$client = new Solarium\Client($config);
+
+// ...
+
+// create a client instance
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);;
 $client->registerPlugin('debugger', $plugin);
 
 // execute a select query and display the results

docs/documents.md

@@ -36,8 +36,10 @@ Example usage
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get a select query instance
 $query = $client->createQuery($client::QUERY_SELECT);
@@ -144,8 +146,10 @@ Example usage
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get an update query instance
 $update = $client->createUpdate();
@@ -185,4 +189,4 @@ You can easily use your own 'document' types, for instance to directly map Solr
 
 -   make sure the class is available (already loaded or can be autoloaded)
 -   set the 'documentclass' option of your query to your own classname
--   the class must implement the same interface as the original document class.
+-   the class must implement the same interface as the original document class.

docs/getting-started.md

@@ -28,7 +28,7 @@ See [<https://packagist.org>](https://packagist.org) for other packages.
 ```json
 {
     "require": {
-        "solarium/solarium": "~5.0.0"
+        "solarium/solarium": "^5.2"
     }
 }
 ```
@@ -55,7 +55,11 @@ htmlHeader();
 echo 'Solarium library version: ' . Solarium\Client::VERSION . ' - ';
 
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client(
+    new Solarium\Core\Client\Adapter\Curl(), // or any other adapter implementing AdapterInterface
+    new Symfony\Component\EventDispatcher\EventDispatcher(),
+    $config
+);
 
 // create a ping query
 $ping = $client->createPing();
@@ -147,7 +151,11 @@ require(__DIR__.'/init.php');
 htmlHeader();
 
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client(
+    new Solarium\Core\Client\Adapter\Curl(), // or any other adapter implementing AdapterInterface
+    new Symfony\Component\EventDispatcher\EventDispatcher(),
+    $config
+);
 
 // get a select query instance
 $query = $client->createQuery($client::QUERY_SELECT);
@@ -193,7 +201,11 @@ require(__DIR__.'/init.php');
 htmlHeader();
 
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client(
+    new Solarium\Core\Client\Adapter\Curl(), // or any other adapter implementing AdapterInterface
+    new Symfony\Component\EventDispatcher\EventDispatcher(),
+    $config
+);
 
 // get a select query instance
 $query = $client->createSelect();
@@ -242,7 +254,11 @@ require(__DIR__.'/init.php');
 htmlHeader();
 
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client(
+    new Solarium\Core\Client\Adapter\Curl(), // or any other adapter implementing AdapterInterface
+    new Symfony\Component\EventDispatcher\EventDispatcher(),
+    $config
+);
 
 // get an update query instance
 $update = $client->createUpdate();
@@ -271,7 +287,11 @@ require(__DIR__.'/init.php');
 htmlHeader();
 
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client(
+    new Solarium\Core\Client\Adapter\Curl(), // or any other adapter implementing AdapterInterface
+    new Symfony\Component\EventDispatcher\EventDispatcher(),
+    $config
+);
 
 // get an update query instance
 $update = $client->createUpdate();
@@ -304,7 +324,11 @@ require(__DIR__.'/init.php');
 htmlHeader();
 
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client(
+    new Solarium\Core\Client\Adapter\Curl(), // or any other adapter implementing AdapterInterface
+    new Symfony\Component\EventDispatcher\EventDispatcher(),
+    $config
+);
 
 // get an update query instance
 $update = $client->createUpdate();

docs/plugins.md

@@ -261,8 +261,10 @@ require(__DIR__.'/init.php');
 
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // enable the plugin and get a query instance
 $filter = $client->getPlugin('minimumscorefilter');
@@ -464,8 +466,10 @@ require(__DIR__.'/init.php');
 
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get a select query instance
 $query = $client->createSelect();

docs/queries/analysis-query/analysis-document.md

@@ -34,8 +34,10 @@ Example
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get an analysis document query
 $query = $client->createAnalysisDocument();

docs/queries/analysis-query/analysis-field.md

@@ -37,8 +37,10 @@ Example
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get an analysis document query
 $query = $client->createAnalysisField();

docs/queries/extract-query.md

@@ -36,8 +36,10 @@ Example
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get an extract query instance and add settings
 $query = $client->createExtract();

docs/queries/ping-query.md

@@ -38,8 +38,10 @@ htmlHeader();
 // check solarium version available
 echo 'Solarium library version: ' . Solarium\Client::VERSION . ' - ';
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // create a ping query
 $ping = $client->createPing();

docs/queries/query-helper/escaping.md

@@ -8,8 +8,10 @@ An example of term escaping in use for a query that would fail without escaping:
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get a select query instance
 $query = $client->createSelect();

docs/queries/query-helper/placeholders.md

@@ -38,8 +38,10 @@ Example
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get a select query instance
 $query = $client->createSelect();

docs/queries/query-helper/query-helper.md

@@ -36,8 +36,10 @@ Example
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get a select query instance and a query helper instance
 $query = $client->createSelect();

docs/queries/realtimeget-query.md

@@ -35,8 +35,10 @@ Example
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get an update query instance
 $update = $client->createUpdate();

docs/queries/select-query/building-a-select-query/adding-filterqueries.md

@@ -21,8 +21,10 @@ Examples
 require(__DIR__.'/init.php');
 htmlHeader();
 
+// ...
+
 // create a client instance
-$client = new Solarium\Client($config);
+$client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get a select query instance
 $query = $client->createSelect();