Typed properties

Author: thomascorthals

CHANGELOG.md

@@ -17,6 +17,9 @@ 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
+ - Solarium\Core\Query\Helper::formatDate() throws a `TypeError` instead of returning `false` if called with an incompatibly typed parameter
 
 ### 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

@@ -100,73 +100,75 @@ This example shows all available events and how to use the events to create a ve
 ```php
 <?php
 
-require_once(__DIR__.'/init.php');
 use Solarium\Core\Event\Events;
+use Solarium\Core\Event\PreExecuteRequest;
+
+require_once(__DIR__.'/init.php');
 
 // 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(string $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(PreExecuteRequest $event): void
     {
         $this->timer('preExecuteRequest');
 
@@ -176,37 +178,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');
     }
@@ -252,11 +254,12 @@ The second example shows how to replace the built-in select querytype with a cus
 ```php
 <?php
 
-require_once(__DIR__.'/init.php');
 use Solarium\Client;
 use Solarium\Core\Plugin\AbstractPlugin;
 use Solarium\QueryType\Select\Query\Query as Select;
 
+require_once(__DIR__.'/init.php');
+
 // This is a custom query class that could have some customized logic
 class MyQuery extends Select
 {
@@ -266,7 +269,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, array $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,28 @@ 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.
+
+Code that calls a method with parameters of an incompatible type will result in a `TypeError` where
+they were previously coerced into a compatible type by PHP's type juggling.
+
 ### 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 +303,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 +314,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 +505,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