Typed properties

Author: thomascorthals

CHANGELOG.md

@@ -17,6 +17,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  - Added `void` return type to `Solarium\Core\Plugin\PluginInterface::deinitPlugin()` method signature
  - Added `void` return type to `Solarium\Core\Plugin\AbstractPlugin::initPluginType()` method signature
  - Changed return type of some Facets methods from `self`to `static`
+ - Replaced class property type hints with type declarations
+ - Added union type declarations to method signatures
 
 ### Removed
 - Solarium\Component\Result\Stats\FacetValue::getFacets(), always returned `null`

README.md

@@ -32,6 +32,7 @@ composer require solarium/solarium
 
 When upgrading from an earlier version, you should be aware of a number of pitfalls.
 
+* [Pitfalls when upgrading to 7.0.0](https://solarium.readthedocs.io/en/stable/getting-started/#pitfalls-when-upgrading-to-700)
 * [Pitfall when upgrading to 6.3.6](https://solarium.readthedocs.io/en/stable/getting-started/#pitfall-when-upgrading-to-636)
 * [Pitfall when upgrading to 6.3.2](https://solarium.readthedocs.io/en/stable/getting-started/#pitfall-when-upgrading-to-632)
 * [Pitfall when upgrading to 6.3](https://solarium.readthedocs.io/en/stable/getting-started/#pitfall-when-upgrading-to-63)

docs/client-and-adapters.md

@@ -107,9 +107,12 @@ The cURL adapter supports the use of a proxy. Use `$adapter->setProxy($proxy)` t
 You can extend the cURL adapter and override the `createHandle()` method to set additional options you require for the cURL transfer.
 
 ```php
+use Solarium\Core\Client\Endpoint;
+use Solarium\Core\Client\Request;
+
 class MyAdapter extends Solarium\Core\Client\Adapter\Curl
 {
-    public function createHandle($request, $endpoint)
+    public function createHandle(Request $request, Endpoint $endpoint): \CurlHandle
     {
         $handle = parent::createHandle($request, $endpoint);
 
@@ -151,9 +154,12 @@ The HTTP adapter supports the use of a proxy. Use `$adapter->setProxy($proxy)` t
 You can extend the HTTP adapter and override the `createContext()` method to set additional options you require for the stream.
 
 ```php
+use Solarium\Core\Client\Endpoint;
+use Solarium\Core\Client\Request;
+
 class MyAdapter extends Solarium\Core\Client\Adapter\Http
 {
-    public function createContext($request, $endpoint)
+    public function createContext(Request $request, Endpoint $endpoint)
     {
         $context = parent::createContext($request, $endpoint);
 

docs/customizing-solarium.md

@@ -106,67 +106,67 @@ use Solarium\Core\Event\Events;
 // this very simple plugin shows a timing for each event and display some request debug info
 class BasicDebug extends Solarium\Core\Plugin\AbstractPlugin
 {
-    protected $start;
-    protected $output = array();
+    protected float $start;
+    protected array $output = [];
 
     // This method is called when the plugin is registered with the client.
     protected function initPluginType(): void
     {
         $this->start = microtime(true);
 
         $dispatcher = $this->client->getEventDispatcher();
-        $dispatcher->addListener(Events::PRE_CREATE_REQUEST, array($this, 'preCreateRequest'));
-        $dispatcher->addListener(Events::POST_CREATE_REQUEST, array($this, 'postCreateRequest'));
-        $dispatcher->addListener(Events::PRE_EXECUTE_REQUEST, array($this, 'preExecuteRequest'));
-        $dispatcher->addListener(Events::POST_EXECUTE_REQUEST, array($this, 'postExecuteRequest'));
-        $dispatcher->addListener(Events::PRE_CREATE_RESULT, array($this, 'preCreateResult'));
-        $dispatcher->addListener(Events::POST_CREATE_RESULT, array($this, 'postCreateResult'));
-        $dispatcher->addListener(Events::PRE_EXECUTE, array($this, 'preExecute'));
-        $dispatcher->addListener(Events::POST_EXECUTE, array($this, 'postExecute'));
-        $dispatcher->addListener(Events::PRE_CREATE_QUERY, array($this, 'preCreateQuery'));
-        $dispatcher->addListener(Events::POST_CREATE_QUERY, array($this, 'postCreateQuery'));
+        $dispatcher->addListener(Events::PRE_CREATE_REQUEST, [$this, 'preCreateRequest']);
+        $dispatcher->addListener(Events::POST_CREATE_REQUEST, [$this, 'postCreateRequest']);
+        $dispatcher->addListener(Events::PRE_EXECUTE_REQUEST, [$this, 'preExecuteRequest']);
+        $dispatcher->addListener(Events::POST_EXECUTE_REQUEST, [$this, 'postExecuteRequest']);
+        $dispatcher->addListener(Events::PRE_CREATE_RESULT, [$this, 'preCreateResult']);
+        $dispatcher->addListener(Events::POST_CREATE_RESULT, [$this, 'postCreateResult']);
+        $dispatcher->addListener(Events::PRE_EXECUTE, [$this, 'preExecute']);
+        $dispatcher->addListener(Events::POST_EXECUTE, [$this, 'postExecute']);
+        $dispatcher->addListener(Events::PRE_CREATE_QUERY, [$this, 'preCreateQuery']);
+        $dispatcher->addListener(Events::POST_CREATE_QUERY, [$this, 'postCreateQuery']);
     }
 
     // This method is called if the plugin is removed from the client.
     public function deinitPlugin(): void
     {
         $dispatcher = $this->client->getEventDispatcher();
-        $dispatcher->removeListener(Events::PRE_CREATE_REQUEST, array($this, 'preCreateRequest'));
-        $dispatcher->removeListener(Events::POST_CREATE_REQUEST, array($this, 'postCreateRequest'));
-        $dispatcher->removeListener(Events::PRE_EXECUTE_REQUEST, array($this, 'preExecuteRequest'));
-        $dispatcher->removeListener(Events::POST_EXECUTE_REQUEST, array($this, 'postExecuteRequest'));
-        $dispatcher->removeListener(Events::PRE_CREATE_RESULT, array($this, 'preCreateResult'));
-        $dispatcher->removeListener(Events::POST_CREATE_RESULT, array($this, 'postCreateResult'));
-        $dispatcher->removeListener(Events::PRE_EXECUTE, array($this, 'preExecute'));
-        $dispatcher->removeListener(Events::POST_EXECUTE, array($this, 'postExecute'));
-        $dispatcher->removeListener(Events::PRE_CREATE_QUERY, array($this, 'preCreateQuery'));
-        $dispatcher->removeListener(Events::POST_CREATE_QUERY, array($this, 'postCreateQuery'));
+        $dispatcher->removeListener(Events::PRE_CREATE_REQUEST, [$this, 'preCreateRequest']);
+        $dispatcher->removeListener(Events::POST_CREATE_REQUEST, [$this, 'postCreateRequest']);
+        $dispatcher->removeListener(Events::PRE_EXECUTE_REQUEST, [$this, 'preExecuteRequest']);
+        $dispatcher->removeListener(Events::POST_EXECUTE_REQUEST, [$this, 'postExecuteRequest']);
+        $dispatcher->removeListener(Events::PRE_CREATE_RESULT, [$this, 'preCreateResult']);
+        $dispatcher->removeListener(Events::POST_CREATE_RESULT, [$this, 'postCreateResult']);
+        $dispatcher->removeListener(Events::PRE_EXECUTE, [$this, 'preExecute']);
+        $dispatcher->removeListener(Events::POST_EXECUTE, [$this, 'postExecute']);
+        $dispatcher->removeListener(Events::PRE_CREATE_QUERY, [$this, 'preCreateQuery']);
+        $dispatcher->removeListener(Events::POST_CREATE_QUERY, [$this, 'postCreateQuery']);
     }
 
-    protected function timer($event)
+    protected function timer($event): void
     {
         $time = round(microtime(true) - $this->start, 5);
         $this->output[] = '['.$time.'] ' . $event;
     }
 
-    public function display()
+    public function display(): void
     {
         echo implode('<br/>', $this->output);
     }
 
-    public function preCreateRequest()
+    public function preCreateRequest(): void
     {
         $this->timer('preCreateRequest');
     }
 
-    public function postCreateRequest()
+    public function postCreateRequest(): void
     {
         $this->timer('postCreateRequest');
     }
 
     // This method uses the available param(s) (see plugin abstract class).
     // You can access or modify data this way.
-    public function preExecuteRequest($event)
+    public function preExecuteRequest($event): void
     {
         $this->timer('preExecuteRequest');
 
@@ -176,37 +176,37 @@ class BasicDebug extends Solarium\Core\Plugin\AbstractPlugin
         $this->output[] = 'Request URI: ' . $event->getRequest()->getUri();
     }
 
-    public function postExecuteRequest()
+    public function postExecuteRequest(): void
     {
         $this->timer('postExecuteRequest');
     }
 
-    public function preCreateResult()
+    public function preCreateResult(): void
     {
         $this->timer('preCreateResult');
     }
 
-    public function postCreateResult()
+    public function postCreateResult(): void
     {
         $this->timer('postCreateResult');
     }
 
-    public function preExecute()
+    public function preExecute(): void
     {
         $this->timer('preExecute');
     }
 
-    public function postExecute()
+    public function postExecute(): void
     {
         $this->timer('postExecute');
     }
 
-    public function preCreateQuery()
+    public function preCreateQuery(): void
     {
         $this->timer('preCreateResult');
     }
 
-    public function postCreateQuery()
+    public function postCreateQuery(): void
     {
         $this->timer('postCreateResult');
     }
@@ -266,7 +266,7 @@ class MyQuery extends Select
 // this very simple plugin that modifies the default querytype mapping
 class QueryCustomizer extends AbstractPlugin
 {
-    public function initPlugin($client, $options)
+    public function initPlugin($client, $options): void
     {
         $client->registerQueryType(
             Client::QUERY_SELECT,

docs/documents.md

@@ -112,7 +112,7 @@ $doc2->name = 'testdoc-2';
 $doc2->price = 340;
 
 // add the documents and a commit command to the update query
-$update->addDocuments(array($doc1, $doc2));
+$update->addDocuments([$doc1, $doc2]);
 $update->addCommit();
 
 // this executes the query and returns the result
@@ -158,36 +158,36 @@ $update = $client->createUpdate();
 $doc1 = $update->createDocument();
 $doc1->id = 123;
 $doc1->name = 'testdoc-1';
-$doc1->childdocs = array(
-    array(
+$doc1->childdocs = [
+    [
         'id' => 1230,
         'name' => 'childdoc-1-1',
         'price' => 465,
-    ),
-    array(
+    ],
+    [
         'id' => 1231,
         'name' => 'childdoc-1-2',
         'price' => 545,
-    ),
-);
+    ],
+];
 
 // and a second one where child documents are added one by one
 $doc2 = $update->createDocument();
 $doc2->setField('id', 124);
 $doc2->setField('name', 'testdoc-2');
-$doc2->addField('childdocs', array(
+$doc2->addField('childdocs', [
     'id' => 1240,
     'name' => 'childdoc-2-1',
     'price' => 360,
-));
-$doc2->addField('childdocs', array(
+]);
+$doc2->addField('childdocs', [
     'id' => 1241,
     'name' => 'childdoc-2-2',
     'price' => 398,
-));
+]);
 
 // add the documents and a commit command to the update query
-$update->addDocuments(array($doc1, $doc2));
+$update->addDocuments([$doc1, $doc2]);
 $update->addCommit();
 
 // this executes the query and returns the result

docs/getting-started.md

@@ -90,14 +90,25 @@ Upgrading
 
 When upgrading from an earlier version, you should be aware of a number of pitfalls.
 
-### Pitfall when upgrading to 6.3.8
+### Pitfalls when upgrading to 7.0.0
+
+Solarium 7.0.0 added type declarations throughout the codebase for:
+- class properties
+- union types in method signatures
+- `void` return types
 
 Plugins extending from `Solarium\Core\Plugin\AbstractPlugin` must add `void` return types to the signatures for
 the following methods (when defined):
 - `initPlugin()`
 - `deinitPlugin()`
 - `initPluginType()`
 
+Any other classes extending from the codebase will run into fatal errors if they violate PHP's
+[variance](https://www.php.net/manual/en/language.oop5.variance.php) rules. Inherited properties
+must add an invariant type declaration. Inherited methods that didn't declare a return type must
+add one that's covariant. Method parameters don't need to have a type declaration, but if they
+do have one it must be contravariant.
+
 ### Pitfall when upgrading to 6.3.6
 
 Using a config object is no longer supported. You have to convert it to an array before passing
@@ -289,9 +300,9 @@ The `$config` array has the following contents:
 ```php
 <?php
 
-$config = array(
-    'endpoint' => array(
-        'localhost' => array(
+$config = [
+    'endpoint' => [
+        'localhost' => [
             'host' => '127.0.0.1',
             'port' => 8983,
             'path' => '/',
@@ -300,9 +311,9 @@ $config = array(
             // 'collection' => 'techproducts',
             // Set the `hostContext` for the Solr web application if it's not the default 'solr':
             // 'context' => 'solr',
-        )
-    )
-);
+        ],
+    ],
+];
 ```
 
 ### Selecting documents
@@ -491,7 +502,7 @@ $doc2->name = 'testdoc-2';
 $doc2->price = 340;
 
 // add the documents and a commit command to the update query
-$update->addDocuments(array($doc1, $doc2));
+$update->addDocuments([$doc1, $doc2]);
 $update->addCommit();
 
 // this executes the query and returns the result

docs/plugins.md

@@ -66,7 +66,7 @@ $buffer->setBufferSize(10); // this is quite low, in most cases you can use a mu
 // also register an event hook to display what is happening
 $client->getEventDispatcher()->addListener(
     Events::PRE_FLUSH,
-    function (PreFlushEvent $event) {
+    function (PreFlushEvent $event): void {
         echo 'Flushing buffer (' . count($event->getBuffer()) . ' docs)<br/>';
     }
 );
@@ -75,11 +75,11 @@ $client->getEventDispatcher()->addListener(
 for ($i=1; $i<=25; $i++) {
 
     // create a new document with dummy data and add it to the buffer
-    $data = array(
+    $data = [
         'id' => 'test_'.$i,
         'name' => 'test for buffered add',
         'price' => $i,
-    );
+    ];
     $buffer->createDocument($data);
 
     // alternatively you could create document instances yourself and use the addDocument(s) method
@@ -162,7 +162,7 @@ $buffer->setBufferSize(10); // this is quite low, in most cases you can use a mu
 // also register an event hook to display what is happening
 $client->getEventDispatcher()->addListener(
     Events::PRE_FLUSH,
-    function (PreFlushEvent $event) {
+    function (PreFlushEvent $event): void {
         echo 'Flushing buffer (' . count($event->getBuffer()) . ' deletes)<br/>';
     }
 );
@@ -222,13 +222,13 @@ $customizer = $client->getPlugin('customizerequest');
 
 // add a persistent HTTP header (using array input values)
 $customizer->createCustomization(
-    array(
+    [
         'key' => 'auth',
         'type' => 'header',
         'name' => 'X-my-auth',
         'value' => 'mypassword',
-        'persistent' => true
-    )
+        'persistent' => true,
+    ]
 );
 
 // add a persistent GET param (using fluent interface)
@@ -402,7 +402,7 @@ $client = new Solarium\Client($adapter, $eventDispatcher, $config);
 $filter = $client->getPlugin('minimumscorefilter');
 $query = $client->createQuery($filter::QUERY_TYPE);
 $query->setQuery('a');
-$query->setFields(array('id'));
+$query->setFields(['id']);
 $query->setFilterRatio(.5);
 $query->setFilterMode($query::FILTER_MODE_MARK);
 
@@ -508,13 +508,13 @@ $parallel = $client->getPlugin('parallelexecution');
 // If you don't have to plugin the example still works, just without the delay.
 $customizer = $client->getPlugin('customizerequest');
 $customizer->createCustomization(
-    array(
+    [
         'key' => 'delay',
         'type' => 'param',
         'name' => 'delay',
         'value' => '500',
-        'persistent' => true
-    )
+        'persistent' => true,
+    ]
 );
 
 // create two queries to execute
@@ -697,7 +697,7 @@ $client = new Solarium\Client($adapter, $eventDispatcher, $config);
 
 // get a select query instance
 $query = $client->createSelect();
-$query->setFields(array('id'));
+$query->setFields(['id']);
 
 // cursor functionality can be used for efficient deep paging (since Solr 4.7)
 $query->setCursorMark('*');