Version option deprecation fix and replacements

CHANGELOG.md

@@ -8,11 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Backward Compatibility Breaks
 ### Added
 * Ability to specify the type of authentication manually by the `auth_type` parameter (in the client class config) was added (allowed values are `basic, digest, gssnegotiate, ntlm`)
+* Added `if_seq_no` / `if_primary_term` to replace `version` for [optimistic concurrency control](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/optimistic-concurrency-control.html)
 ### Changed
 * Allow `string` such as `wait_for` to be passed to `AbstractUpdateAction::setRefresh` [#1791](https://github.com/ruflin/Elastica/pull/1791)
 * Changed the return type of `AbstractUpdateAction::getRefresh` to `boolean|string` [#1791](https://github.com/ruflin/Elastica/pull/1791)
 ### Deprecated
 * Deprecated Match query class and introduced MatchQuery instead for PHP 8.0 compatibility reason [#1799](https://github.com/ruflin/Elastica/pull/1799)
+* Deprecated `version`/`version_type` options [(deprecated in `6.7.0`)](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/docs-update.html) and added `if_seq_no` / `if_primary_term` that replaced it
 ### Removed
 ### Fixed
 * fixed issue [1789](https://github.com/ruflin/Elastica/issues/1789)

src/AbstractUpdateAction.php

@@ -65,6 +65,71 @@ public function getIndex()
     }
 
     /**
+     * Sets the sequence number of a document for use with optimistic concurrency control.
+     *
+     * @param int $number Sequence Number
+     *
+     * @return $this
+     *
+     * @see https://www.elastic.co/guide/en/elasticsearch/reference/6.8/optimistic-concurrency-control.html
+     */
+    public function setSequenceNumber($number)
+    {
+        return $this->setParam('if_seq_no', $number);
+    }
+
+    /**
+     * Returns document version.
+     *
+     * @return int|string Document version
+     */
+    public function getSequenceNumber()
+    {
+        return $this->getParam('if_seq_no');
+    }
+
+    /**
+     * @return bool
+     */
+    public function hasSequenceNumber()
+    {
+        return $this->hasParam('if_seq_no');
+    }
+
+    /**
+     * Sets the prmary term of a document for use with optimistic concurrency control.
+     *
+     * @param int $term Primary Term
+     *
+     * @return $this
+     *
+     * @see https://www.elastic.co/guide/en/elasticsearch/reference/6.8/optimistic-concurrency-control.html
+     */
+    public function setPrimaryTerm($term)
+    {
+        return $this->setParam('if_primary_term', $term);
+    }
+
+    /**
+     * Returns document version.
+     *
+     * @return int|string Document version
+     */
+    public function getPrimaryTerm()
+    {
+        return $this->getParam('if_primary_term');
+    }
+
+    /**
+     * @return bool
+     */
+    public function hasPrimaryTerm()
+    {
+        return $this->hasParam('if_primary_term');
+    }
+
+    /**
+     * @deprecated
      * Sets the version of a document for use with optimistic concurrency control.
      *
      * @param int $version Document version
@@ -75,10 +140,13 @@ public function getIndex()
      */
     public function setVersion($version)
     {
-        return $this->setParam('version', (int) $version);
+        \trigger_error('Elastica\AbstractUpdateAction::setVersion is deprecated. Use Elastica\AbstractUpdateAction::setSequenceNumber and Elastica\AbstractUpdateAction::setPrimaryTerm instead.', E_USER_DEPRECATED);
+
+        return $this;
     }
 
     /**
+     * @deprecated
      * Returns document version.
      *
      * @return int|string Document version
@@ -89,6 +157,7 @@ public function getVersion()
     }
 
     /**
+     * @deprecated
      * @return bool
      */
     public function hasVersion()
@@ -97,6 +166,7 @@ public function hasVersion()
     }
 
     /**
+     * @deprecated
      * Sets the version_type of a document
      * Default in ES is internal, but you can set to external to use custom versioning.
      *
@@ -106,10 +176,13 @@ public function hasVersion()
      */
     public function setVersionType($versionType)
     {
-        return $this->setParam('version_type', $versionType);
+        \trigger_error('Elastica\AbstractUpdateAction::setVersionType is deprecated. Use Elastica\AbstractUpdateAction::setSequenceNumber and Elastica\AbstractUpdateAction::setPrimaryTerm instead.', E_USER_DEPRECATED);
+
+        return $this;
     }
 
     /**
+     * @deprecated
      * Returns document version type.
      *
      * @return int|string Document version type
@@ -120,6 +193,7 @@ public function getVersionType()
     }
 
     /**
+     * @deprecated
      * @return bool
      */
     public function hasVersionType()

src/Bulk.php

@@ -323,8 +323,11 @@ protected function _processResponse(Response $response): ResponseSet
                         if (!$data->hasId() && isset($bulkResponseData['_id'])) {
                             $data->setId($bulkResponseData['_id']);
                         }
-                        if (isset($bulkResponseData['_version'])) {
-                            $data->setVersion($bulkResponseData['_version']);
+                        if (isset($responseData['_seq_no'])) {
+                            $data->setSequenceNumber($responseData['_seq_no']);
+                        }
+                        if (isset($responseData['_primary_term'])) {
+                            $data->setPrimaryTerm($responseData['_primary_term']);
                         }
                     }
                 }

src/Client.php

@@ -277,8 +277,8 @@ public function updateDocument($id, $data, $index, array $options = []): Respons
 
             $docOptions = $data->getOptions(
                 [
-                    'version',
-                    'version_type',
+                    'if_seq_no',
+                    'if_primary_term',
                     'routing',
                     'percolate',
                     'parent',
@@ -311,8 +311,11 @@ public function updateDocument($id, $data, $index, array $options = []): Respons
             && ($data->isAutoPopulate() || $this->getConfigValue(['document', 'autoPopulate'], false))
         ) {
             $responseData = $response->getData();
-            if (isset($responseData['_version'])) {
-                $data->setVersion($responseData['_version']);
+            if (isset($responseData['_seq_no'])) {
+                $data->setSequenceNumber($responseData['_seq_no']);
+            }
+            if (isset($responseData['_primary_term'])) {
+                $data->setPrimaryTerm($responseData['_primary_term']);
             }
         }
 

src/Index.php

@@ -215,8 +215,11 @@ public function addDocument(Document $doc): Response
             if (isset($data['_id']) && !$doc->hasId()) {
                 $doc->setId($data['_id']);
             }
-            if (isset($data['_version'])) {
-                $doc->setVersion($data['_version']);
+            if (isset($responseData['_seq_no'])) {
+                $doc->setSequenceNumber($responseData['_seq_no']);
+            }
+            if (isset($responseData['_primary_term'])) {
+                $doc->setPrimaryTerm($responseData['_primary_term']);
             }
         }
 
@@ -272,10 +275,7 @@ public function getDocument($id, array $options = []): Document
             $data = [];
         }
 
-        $document = new Document($id, $data, $this->getName());
-        $document->setVersion($result['_version']);
-
-        return $document;
+        return new Document($id, $data, $this->getName());
     }
 
     /**