Add write protection with examples and tests (#115)

* Add write protection with examples and tests

* post review

* Linter

* PubNub SDK 7.4.0 release.

---------

Co-authored-by: PubNub Release Bot <120067856+pubnub-release-bot@users.noreply.github.com>

Author: seba-aln

.pubnub.yml

@@ -1,8 +1,13 @@
 name: php
-version: 7.3.0
+version: 7.4.0
 schema: 1
 scm: github.com/pubnub/php
 changelog:
+  - date: 2025-02-18
+    version: 7.4.0
+    changes:
+      - type: feature
+        text: "Write protection with If-Match eTag header for setting channel and uuid metadata."
   - date: 2025-02-05
     version: 7.3.0
     changes:
@@ -447,8 +452,8 @@ sdks:
                     - x86-64
           - distribution-type: library
             distribution-repository: GitHub release
-            package-name: php-7.3.0.zip
-            location: https://github.com/pubnub/php/releases/tag/7.3.0
+            package-name: php-7.4.0.zip
+            location: https://github.com/pubnub/php/releases/tag/7.4.0
             requires:
               - name: rmccue/requests
                 min-version: 1.0.0

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 7.4.0
+February 18 2025
+
+#### Added
+- Write protection with If-Match eTag header for setting channel and uuid metadata.
+
 ## 7.3.0
 February 05 2025
 

README.md

@@ -41,7 +41,7 @@ You will need the publish and subscribe keys to authenticate your app. Get your
          {
              "require": {
                  <!-- include the latest version from the badge at the top -->
-                 "pubnub/pubnub": "7.3.0"
+                 "pubnub/pubnub": "7.4.0"
              }
          }
          ```

composer.json

@@ -5,7 +5,7 @@
   "keywords": ["api", "real-time", "realtime", "real time", "ajax", "push"],
   "homepage": "http://www.pubnub.com/",
   "license": "proprietary",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "authors": [
     {
       "name": "PubNub",

examples/cli/partial_updates.php

@@ -0,0 +1,91 @@
+<?php
+
+set_time_limit(0);
+
+require('../../vendor/autoload.php');
+
+use PubNub\PNConfiguration;
+use PubNub\PubNub;
+
+$pnconf = new PNConfiguration();
+$pnconf->setPublishKey("demo");
+$pnconf->setSubscribeKey("demo");
+$pnconf->setUuid("example");
+
+$pubnub = new PubNub($pnconf);
+
+$channel = "demo_example";
+
+print("We're setting the channel's $channel additional info.\n");
+print("\tTo exit type '/exit'\n");
+print("\tTo show the current object type '/show'\n");
+print("\tTo show this help type '/help'\n");
+
+print("Enter the channel name: ");
+$name = trim(fgets(STDIN));
+
+print("Enter the channel description: ");
+$description = trim(fgets(STDIN));
+
+// Set channel metadata
+$pubnub->setChannelMetadata()
+    ->channel($channel)
+    ->meta([
+        "name" => $name,
+        "description" => $description,
+    ])
+    ->sync();
+
+print("The channel has been created with name and description.\n");
+
+while (true) {
+    // Fetch current channel metadata
+    $response = $pubnub->getChannelMetadata()
+        ->channel($channel)
+        ->sync();
+
+    print("Enter the field name: ");
+    $fieldName = trim(fgets(STDIN));
+
+    if ($fieldName === '/exit') {
+        exit();
+    } elseif ($fieldName === '/show') {
+        print_r($response);
+        continue;
+    } elseif ($fieldName === '/help') {
+        print("\tTo exit type '/exit'\n");
+        print("\tTo show the current object type '/show'\n");
+        print("\tTo show this help type '/help'\n");
+        continue;
+    }
+
+    print("Enter the field value: ");
+    $fieldValue = trim(fgets(STDIN));
+
+    // Prepare custom fields
+    $custom = (array)$response->getCustom();
+
+    if (isset($custom[$fieldName])) {
+        print("Field $fieldName already has a value. Overwrite? (y/n): ");
+        $confirmation = trim(fgets(STDIN));
+
+        if (strtolower($confirmation) !== 'y') {
+            print("Object will not be updated.\n");
+            continue;
+        }
+    }
+
+    // Update custom field
+    $custom[$fieldName] = $fieldValue;
+
+    // Writing the updated object back to the server
+    $pubnub->setChannelMetadata()
+        ->channel($channel)
+        ->meta([
+            "name" => $response->getName(),
+            "description" => $response->getDescription(),
+            "custom" => $custom,
+        ])
+        ->sync();
+    print("Object has been updated.\n");
+}

examples/cli/pn.jpg

@@ -0,0 +1,66 @@
+<?php
+
+require_once 'vendor/autoload.php';
+
+use PubNub\Exceptions\PubNubServerException;
+use PubNub\PubNub;
+use PubNub\PNConfiguration;
+
+$config = new PNConfiguration();
+$config->setPublishKey('demo');
+$config->setSubscribeKey('demo');
+$config->setUuid("example");
+
+$config_2 = clone $config;
+$config_2->setUuid("example_2");
+
+$pubnub = new PubNub($config);
+$pubnub_2 = new PubNub($config_2);
+
+$sample_user = [
+    "uuid" => "SampleUser",
+    "name" => "John Doe",
+    "email" => "jd@example.com",
+    "custom" => ["age" => 42, "address" => "123 Main St."]
+];
+
+// One client creates a metadata for the user "SampleUser" and successfully writes it to the server.
+$set_result = $pubnub->setUUIDMetadata()->uuid("SampleUser")->meta($sample_user)->sync();
+
+// We store the eTag for the user for further updates.
+$original_e_tag = $set_result->getETag();
+
+print("We receive the eTag for the user: $original_e_tag" . PHP_EOL);
+
+// Another client sets the user meta with the same UUID but different data.
+$overwrite_result = $pubnub_2->setUUIDMetadata()->uuid("SampleUser")->meta(["name" => "Jane Doe"])->sync();
+$new_e_tag = $overwrite_result->getETag();
+
+// We can verify that there is a new eTag for the user.
+print(
+    "After overwrite there's a new eTag: $original_e_tag === $new_e_tag? "
+    . ($original_e_tag === $new_e_tag ? "true" : "false") . PHP_EOL
+);
+
+// We modify the user and try to update it.
+$updated_user = array_merge($sample_user, ["custom" => ["age" => 43, "address" => "321 Other St."]]);
+
+try {
+    $update_result = $pubnub->setUUIDMetadata()
+        ->uuid("SampleUser")
+        ->meta($updated_user)
+        ->ifMatchesETag($original_e_tag)
+        ->sync();
+    print_r($update_result);
+} catch (PubNubServerException $e) {
+    if ($e->getStatusCode() === 412) {
+        print(
+            "Update failed because eTag mismatch: " . $e->getServerErrorMessage()
+            . "\nHTTP Status Code: " . $e->getStatusCode() . PHP_EOL
+        );
+    } else {
+        print( "Unexpected error: " . $e->getMessage() . PHP_EOL);
+    }
+} catch (Exception $e) {
+    echo "Unexpected error: " . $e->getMessage() . PHP_EOL;
+}

examples/cli/using_etag.php

@@ -3326,21 +3326,6 @@ parameters:
 			count: 1
 			path: src/PubNub/Models/Consumer/Objects/Channel/PNGetAllChannelMetadataResult.php
 
-		-
-			message: "#^Undefined variable\\: \\$data$#"
-			count: 1
-			path: src/PubNub/Models/Consumer/Objects/Channel/PNGetAllChannelMetadataResult.php
-
-		-
-			message: "#^Undefined variable\\: \\$data_string$#"
-			count: 1
-			path: src/PubNub/Models/Consumer/Objects/Channel/PNGetAllChannelMetadataResult.php
-
-		-
-			message: "#^Variable \\$data in empty\\(\\) is never defined\\.$#"
-			count: 1
-			path: src/PubNub/Models/Consumer/Objects/Channel/PNGetAllChannelMetadataResult.php
-
 		-
 			message: "#^Method PubNub\\\\Models\\\\Consumer\\\\Objects\\\\Channel\\\\PNGetChannelMetadataResult\\:\\:__construct\\(\\) has parameter \\$custom with no value type specified in iterable type array\\.$#"
 			count: 1

phpstan-baseline.neon

@@ -2,6 +2,7 @@
 
 namespace PubNub\Endpoints;
 
+use Exception;
 use PubNub\Enums\PNOperationType;
 use PubNub\Enums\PNHttpMethod;
 use PubNub\Enums\PNStatusCategory;
@@ -32,6 +33,9 @@ abstract class Endpoint
     protected int $endpointOperationType;
     protected string $endpointName;
 
+    /** @var string[] */
+    protected array $customHeaders = [];
+
     protected const RESPONSE_IS_JSON = true;
 
     /** @var  PubNub */
@@ -178,7 +182,7 @@ protected function defaultHeaders()
 
     protected function customHeaders()
     {
-        return [];
+        return $this->customHeaders;
     }
 
     /**

src/PubNub/Endpoints/Endpoint.php

@@ -3,6 +3,7 @@
 namespace PubNub\Endpoints\Objects\Channel;
 
 use PubNub\Endpoints\Endpoint;
+use PubNub\Endpoints\Objects\MatchesETagTrait;
 use PubNub\Enums\PNHttpMethod;
 use PubNub\Enums\PNOperationType;
 use PubNub\Exceptions\PubNubValidationException;
@@ -11,6 +12,8 @@
 
 class SetChannelMetadata extends Endpoint
 {
+    use MatchesETagTrait;
+
     protected const PATH = "/v2/objects/%s/channels/%s";
 
     /** @var string */

src/PubNub/Endpoints/Objects/Channel/SetChannelMetadata.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace PubNub\Endpoints\Objects;
+
+trait MatchesETagTrait
+{
+    protected ?string $eTag = null;
+    protected array $customHeaders = [];
+
+    /**
+     * @param string $eTag
+     * @return $this
+     */
+    public function ifMatchesETag(string $eTag): self
+    {
+        $this->eTag = $eTag;
+        $this->customHeaders['If-Match'] = $eTag;
+        return $this;
+    }
+}

src/PubNub/Endpoints/Objects/MatchesETagTrait.php

@@ -61,5 +61,4 @@ public function sort($sort)
 
         return $this;
     }
-
-}
+}

src/PubNub/Endpoints/Objects/ObjectsCollectionEndpoint.php

@@ -3,6 +3,7 @@
 namespace PubNub\Endpoints\Objects\UUID;
 
 use PubNub\Endpoints\Endpoint;
+use PubNub\Endpoints\Objects\MatchesETagTrait;
 use PubNub\Enums\PNHttpMethod;
 use PubNub\Enums\PNOperationType;
 use PubNub\Exceptions\PubNubValidationException;
@@ -11,6 +12,8 @@
 
 class SetUUIDMetadata extends Endpoint
 {
+    use MatchesETagTrait;
+
     protected const PATH = "/v2/objects/%s/uuids/%s";
 
     /** @var string */