From 4d9a24079f617dbb2ebd26bb358803d2d4101ff1 Mon Sep 17 00:00:00 2001
From: thomascorthals <thomas_corthals@hotmail.com>
Date: Mon, 2 Oct 2023 11:21:55 +0200
Subject: [PATCH] Fix BC issue introduced in #1087 (#1098)

---
 CHANGELOG.md                                  |  2 ++
 README.md                                     |  6 ++--
 src/Component/QueryTrait.php                  |  2 +-
 .../AbstractTechproductsTestCase.php          | 30 +++++++++++++++++++
 .../Query/CustomQueryInterfaceQuery.php       | 20 +++++++++++++
 tests/Integration/Query/CustomSelfQuery.php   | 19 ++++++++++++
 tests/Integration/Query/CustomStaticQuery.php | 19 ++++++++++++
 7 files changed, 94 insertions(+), 4 deletions(-)
 create mode 100644 tests/Integration/Query/CustomQueryInterfaceQuery.php
 create mode 100644 tests/Integration/Query/CustomSelfQuery.php
 create mode 100644 tests/Integration/Query/CustomStaticQuery.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f606f570f..75015c6dd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Changed
 - Spatial component distance type changed from int to float
+- Revert return type for Solarium\Component\QueryTrait::setQuery() from `self` to `QueryInterface` for backward compatibility with custom query classes that override this method
+
 
 ## [6.3.2]
 ### Added
diff --git a/README.md b/README.md
index a1a4fb63f..fec281049 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ Please see the [docs](http://solarium.readthedocs.io/en/stable/) for a more deta
 
 ## Requirements
 
-Solarium 6.4.x only supports PHP 8.0 and up.
+Solarium 6.3.2 and up only supports PHP 8.0 and up.
 
 It's highly recommended to have cURL enabled in your PHP environment. However if you don't have cURL available you can
 switch from using cURL (the default) to a pure PHP based HTTP client adapter which works for the essential stuff but
@@ -28,9 +28,9 @@ Example:
 composer require solarium/solarium
 ```
 
-### Pitfall when upgrading to 6.4
+### Pitfall when upgrading to 6.3.2
 
-Support for PHP 7 was removed in Solarium 6.4.0. Upgrade to PHP 8 first to use the latest Solarium version.
+Support for PHP 7 was removed in Solarium 6.3.2. Upgrade to PHP 8 first to use the latest Solarium version.
 
 ### Pitfall when upgrading to 6.3
 
diff --git a/src/Component/QueryTrait.php b/src/Component/QueryTrait.php
index 800b285b4..f0680845a 100644
--- a/src/Component/QueryTrait.php
+++ b/src/Component/QueryTrait.php
@@ -24,7 +24,7 @@ trait QueryTrait
      *
      * @return self Provides fluent interface
      */
-    public function setQuery(string $query, array $bind = null): self
+    public function setQuery(string $query, array $bind = null): QueryInterface
     {
         if (null !== $bind) {
             $helper = $this->getHelper();
diff --git a/tests/Integration/AbstractTechproductsTestCase.php b/tests/Integration/AbstractTechproductsTestCase.php
index 37e1780a3..9129d7f11 100644
--- a/tests/Integration/AbstractTechproductsTestCase.php
+++ b/tests/Integration/AbstractTechproductsTestCase.php
@@ -5,6 +5,7 @@
 use PHPUnit\Framework\TestCase;
 use Solarium\Component\ComponentAwareQueryInterface;
 use Solarium\Component\Highlighting\Highlighting;
+use Solarium\Component\QueryInterface;
 use Solarium\Component\QueryTraits\GroupingTrait;
 use Solarium\Component\QueryTraits\TermsTrait;
 use Solarium\Component\Result\Grouping\FieldGroup;
@@ -57,6 +58,9 @@
 use Solarium\QueryType\Update\RequestBuilder\Xml as XmlUpdateRequestBuilder;
 use Solarium\Support\Utility;
 use Solarium\Tests\Integration\Plugin\EventTimer;
+use Solarium\Tests\Integration\Query\CustomQueryInterfaceQuery;
+use Solarium\Tests\Integration\Query\CustomSelfQuery;
+use Solarium\Tests\Integration\Query\CustomStaticQuery;
 use Symfony\Contracts\EventDispatcher\Event;
 
 abstract class AbstractTechproductsTestCase extends TestCase
@@ -5066,6 +5070,32 @@ public function testEventDispatching()
 
         self::$client->removePlugin('eventtimer');
     }
+
+    /**
+     * Test the various return types that are valid for custom query classes that
+     * override the {@see \Solarium\Component\QueryTrait::setQuery()} method.
+     *
+     * If this test throws a fatal error, the return type of the parent might no
+     * longer be backward compatible with existing code that overrides it.
+     *
+     * @see https://github.com/solariumphp/solarium/issues/1097
+     *
+     * @dataProvider customQueryClassProvider
+     */
+    public function testCustomQueryClassSetQueryReturnType(string $queryClass)
+    {
+        $query = new $queryClass();
+        $this->assertInstanceOf(QueryInterface::class, $query->setQuery('*:*'));
+    }
+
+    public function customQueryClassProvider(): array
+    {
+        return [
+            [CustomStaticQuery::class],
+            [CustomSelfQuery::class],
+            [CustomQueryInterfaceQuery::class],
+        ];
+    }
 }
 
 class GroupingTestQuery extends SelectQuery
diff --git a/tests/Integration/Query/CustomQueryInterfaceQuery.php b/tests/Integration/Query/CustomQueryInterfaceQuery.php
new file mode 100644
index 000000000..18f2595f3
--- /dev/null
+++ b/tests/Integration/Query/CustomQueryInterfaceQuery.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace Solarium\Tests\Integration\Query;
+
+use Solarium\Component\QueryInterface;
+use Solarium\QueryType\Select\Query\Query as SelectQuery;
+
+/**
+ * Custom query that overrides the setQuery() method with a QueryInterface return type.
+ */
+class CustomQueryInterfaceQuery extends SelectQuery
+{
+    /**
+     * @return self Provides fluent interface
+     */
+    public function setQuery(string $query, array $bind = null): QueryInterface
+    {
+        return parent::setQuery($query, $bind);
+    }
+}
diff --git a/tests/Integration/Query/CustomSelfQuery.php b/tests/Integration/Query/CustomSelfQuery.php
new file mode 100644
index 000000000..7cd82fa29
--- /dev/null
+++ b/tests/Integration/Query/CustomSelfQuery.php
@@ -0,0 +1,19 @@
+<?php
+
+namespace Solarium\Tests\Integration\Query;
+
+use Solarium\QueryType\Select\Query\Query as SelectQuery;
+
+/**
+ * Custom query that overrides the setQuery() method with a self return type.
+ */
+class CustomSelfQuery extends SelectQuery
+{
+    /**
+     * @return self Provides fluent interface
+     */
+    public function setQuery(string $query, array $bind = null): self
+    {
+        return parent::setQuery($query, $bind);
+    }
+}
diff --git a/tests/Integration/Query/CustomStaticQuery.php b/tests/Integration/Query/CustomStaticQuery.php
new file mode 100644
index 000000000..f85da327b
--- /dev/null
+++ b/tests/Integration/Query/CustomStaticQuery.php
@@ -0,0 +1,19 @@
+<?php
+
+namespace Solarium\Tests\Integration\Query;
+
+use Solarium\QueryType\Select\Query\Query as SelectQuery;
+
+/**
+ * Custom query that overrides the setQuery() method with a static return type.
+ */
+class CustomStaticQuery extends SelectQuery
+{
+    /**
+     * @return static Provides fluent interface
+     */
+    public function setQuery(string $query, array $bind = null): static
+    {
+        return parent::setQuery($query, $bind);
+    }
+}