Merge branch 'master' into solr_8.5.0

docs/queries/update-query/best-practices-for-updates.md

@@ -27,3 +27,7 @@ If you need to use rollbacks (outside of testing) that usually indicates there i
 ### Optimizing
 
 While 'optimizing' sounds like it's always a good thing to do, you should use it with care, as it can have a negative performance impact *during the optimize process*. If possible use try to use it outside peak hours / at intervals.
+
+### Raw XML update commands
+
+Solarium makes it easy to build update commands without having to know the underlying XML structure. If you already have XML formatted update commands, you can add them directly to an update query. Make sure they are valid as Solarium will not check this.

docs/queries/update-query/building-an-update-query/rawxml-command.md

@@ -0,0 +1,58 @@
+You can use this command to add XML formatted update commands to an update query.
+
+Make sure the XML is valid as Solarium will not check this. If you are constructing these strings in your own code, you should probably be using the other commands Solarium provides to build your update query.
+
+Options
+-------
+
+This command has no options.
+
+Example
+-------
+
+```php
+<?php
+
+require(__DIR__.'/init.php');
+htmlHeader();
+
+// create a client instance
+$client = new Solarium\Client($config);
+
+// get an update query instance
+$update = $client->createUpdate();
+
+// create an XML string with a valid update command
+$xml = '
+<add>
+    <doc>
+        <field name="id">125</field>
+        <field name="name">testdoc-3</field>
+        <field name="price">325</field>
+    </doc>
+    <doc>
+        <field name="id">126</field>
+        <field name="name">testdoc-4</field>
+        <field name="price">375</field>
+    </doc>
+</add>
+';
+
+// or use an XML file containing a valid update command
+$xmlfile = 'example.xml';
+
+// add the XML string, the XML file and a commit command to the update query
+$update->addRawXmlCommand($xml);
+$update->addRawXmlFile($xmlfile);
+$update->addCommit();
+
+// this executes the query and returns the result
+$result = $client->update($update);
+
+echo '<b>Update query executed</b><br/>';
+echo 'Query status: ' . $result->getStatus(). '<br/>';
+echo 'Query time: ' . $result->getQueryTime();
+
+htmlFooter();
+
+```

examples/2.2.6-rawxml.php

@@ -0,0 +1,43 @@
+<?php
+
+require(__DIR__.'/init.php');
+htmlHeader();
+
+// create a client instance
+$client = new Solarium\Client($config);
+
+// get an update query instance
+$update = $client->createUpdate();
+
+// create an XML string with a valid update command
+$xml = '
+<add>
+    <doc>
+        <field name="id">125</field>
+        <field name="name">testdoc-3</field>
+        <field name="price">325</field>
+    </doc>
+    <doc>
+        <field name="id">126</field>
+        <field name="name">testdoc-4</field>
+        <field name="price">375</field>
+    </doc>
+</add>
+';
+
+// or use an XML file containing a valid update command
+$xmlfile = 'example.xml';
+
+// add the XML string, the XML file and a commit command to the update query
+$update->addRawXmlCommand($xml);
+$update->addRawXmlFile($xmlfile);
+$update->addCommit();
+
+// this executes the query and returns the result
+$result = $client->update($update);
+
+echo '<b>Update query executed</b><br/>';
+echo 'Query status: ' . $result->getStatus(). '<br/>';
+echo 'Query time: ' . $result->getQueryTime();
+
+htmlFooter();

examples/index.html

@@ -82,7 +82,8 @@ <h2>Examples</h2>
                     <li><a href="2.2.2-delete-by-query.php">2.2.2 Delete by query</a></li>
                     <li><a href="2.2.3-delete-by-id.php">2.2.3 Delete by ID</a></li>
                     <li><a href="2.2.4-optimize.php">2.2.4 Optimize index</a></li>
-                    <li><a href="2.2.5-rollback.php">2.2.5 Rollback</a></li>
+                    <li><a href="2.2.5-rollback.php">2.2.5 Rollback uncommitted changes</a></li>
+                    <li><a href="2.2.6-rawxml.php">2.2.6 Issue raw XML update commands</a></li>
                 </ul>
 
                 <li>2.3. MoreLikeThis query</li>

src/Plugin/BufferedAdd/BufferedAdd.php

@@ -265,7 +265,7 @@ public function commit(?bool $overwrite = null, ?bool $softCommit = null, ?bool
         $event = new PreCommitEvent($this->buffer, $overwrite, $softCommit, $waitSearcher, $expungeDeletes);
         $this->client->getEventDispatcher()->dispatch($event, Events::PRE_COMMIT);
 
-        $this->updateQuery->addDocuments($this->buffer, $event->getOverwrite());
+        $this->updateQuery->addDocuments($event->getBuffer(), $event->getOverwrite());
         $this->updateQuery->addCommit($event->getSoftCommit(), $event->getWaitSearcher(), $event->getExpungeDeletes());
         $result = $this->client->update($this->updateQuery, $this->getEndpoint());
         $this->clear();

src/Plugin/BufferedAdd/Event/AddDocument.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Solarium\Plugin\BufferedAdd\Event;
 
 use Solarium\Core\Query\DocumentInterface;

src/Plugin/BufferedAdd/Event/Events.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Solarium\Plugin\BufferedAdd\Event;
 
 /**
@@ -14,7 +16,7 @@ interface Events
      *
      * @var string
      */
-    const PRE_FLUSH = 'solarium.bufferedAdd.preFlush';
+    public const PRE_FLUSH = 'solarium.bufferedAdd.preFlush';
 
     /**
      * This event is called after a buffer flush.
@@ -23,7 +25,7 @@ interface Events
      *
      * @var string
      */
-    const POST_FLUSH = 'solarium.bufferedAdd.postFlush';
+    public const POST_FLUSH = 'solarium.bufferedAdd.postFlush';
 
     /**
      * This event is called before a buffer commit.
@@ -32,7 +34,7 @@ interface Events
      *
      * @var string
      */
-    const PRE_COMMIT = 'solarium.bufferedAdd.preCommit';
+    public const PRE_COMMIT = 'solarium.bufferedAdd.preCommit';
 
     /**
      * This event is called after a buffer commit.
@@ -41,7 +43,7 @@ interface Events
      *
      * @var string
      */
-    const POST_COMMIT = 'solarium.bufferedAdd.postCommit';
+    public const POST_COMMIT = 'solarium.bufferedAdd.postCommit';
 
     /**
      * This event is called when a new document is added.
@@ -50,5 +52,5 @@ interface Events
      *
      * @var string
      */
-    const ADD_DOCUMENT = 'solarium.bufferedAdd.addDocument';
+    public const ADD_DOCUMENT = 'solarium.bufferedAdd.addDocument';
 }

src/Plugin/BufferedAdd/Event/PostCommit.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Solarium\Plugin\BufferedAdd\Event;
 
 use Solarium\QueryType\Update\Result;

src/Plugin/BufferedAdd/Event/PostFlush.php

@@ -1,8 +1,9 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Solarium\Plugin\BufferedAdd\Event;
 
-use Solarium\Core\Query\DocumentInterface;
 use Solarium\QueryType\Update\Result;
 use Symfony\Contracts\EventDispatcher\Event;
 
@@ -29,7 +30,7 @@ public function __construct(Result $result)
     /**
      * Get the result for this event.
      *
-     * @return DocumentInterface[]
+     * @return \Solarium\QueryType\Update\Result
      */
     public function getResult(): Result
     {

src/Plugin/BufferedAdd/Event/PreCommit.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Solarium\Plugin\BufferedAdd\Event;
 
 use Solarium\Core\Query\DocumentInterface;
@@ -16,7 +18,7 @@ class PreCommit extends Event
     protected $buffer;
 
     /**
-     * @var bool
+     * @var bool|null
      */
     protected $overwrite;
 
@@ -38,13 +40,13 @@ class PreCommit extends Event
     /**
      * Event constructor.
      *
-     * @param array     $buffer
-     * @param bool      $overwrite
-     * @param bool|null $softCommit
-     * @param bool|null $waitSearcher
-     * @param bool|null $expungeDeletes
+     * @param DocumentInterface[] $buffer
+     * @param bool|null           $overwrite
+     * @param bool|null           $softCommit
+     * @param bool|null           $waitSearcher
+     * @param bool|null           $expungeDeletes
      */
-    public function __construct(array $buffer, bool $overwrite, ?bool $softCommit, ?bool $waitSearcher, ?bool $expungeDeletes)
+    public function __construct(array $buffer, ?bool $overwrite, ?bool $softCommit, ?bool $waitSearcher, ?bool $expungeDeletes)
     {
         $this->buffer = $buffer;
         $this->overwrite = $overwrite;
@@ -73,19 +75,21 @@ public function getBuffer(): array
     public function setBuffer(array $buffer): self
     {
         $this->buffer = $buffer;
+
         return $this;
     }
 
     /**
      * Optionally override the value.
      *
-     * @param bool $expungeDeletes
+     * @param bool|null $expungeDeletes
      *
      * @return self Provides fluent interface
      */
-    public function setExpungeDeletes(bool $expungeDeletes): self
+    public function setExpungeDeletes(?bool $expungeDeletes): self
     {
         $this->expungeDeletes = $expungeDeletes;
+
         return $this;
     }
 
@@ -100,34 +104,36 @@ public function getExpungeDeletes(): ?bool
     /**
      * Optionally override the value.
      *
-     * @param bool $overwrite
+     * @param bool|null $overwrite
      *
      * @return self Provides fluent interface
      */
-    public function setOverwrite(bool $overwrite): self
+    public function setOverwrite(?bool $overwrite): self
     {
         $this->overwrite = $overwrite;
+
         return $this;
     }
 
     /**
-     * @return bool
+     * @return bool|null
      */
-    public function getOverwrite(): bool
+    public function getOverwrite(): ?bool
     {
         return $this->overwrite;
     }
 
     /**
      * Optionally override the value.
      *
-     * @param bool $softCommit
+     * @param bool|null $softCommit
      *
      * @return self Provides fluent interface
      */
-    public function setSoftCommit(bool $softCommit): self
+    public function setSoftCommit(?bool $softCommit): self
     {
         $this->softCommit = $softCommit;
+
         return $this;
     }
 
@@ -142,13 +148,14 @@ public function getSoftCommit(): ?bool
     /**
      * Optionally override the value.
      *
-     * @param bool $waitSearcher
+     * @param bool|null $waitSearcher
      *
      * @return self Provides fluent interface
      */
-    public function setWaitSearcher(bool $waitSearcher): self
+    public function setWaitSearcher(?bool $waitSearcher): self
     {
         $this->waitSearcher = $waitSearcher;
+
         return $this;
     }