feat: send Network calls synchornously if set in init

Author: sakshamg1304

CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.13.0] - 2025-10-10
+
+### Added
+
+- Introduced option to send network calls synchronously with the introduction of a new parameter in init, `shouldWaitForTrackingCalls`.
+- Added `retryConfig` init parameter to configure retries: `shouldRetry`, `maxRetries`, `initialDelay`, `backoffMultiplier`.
+
+Example:
+
+```php
+$vwoClient = VWO::init([
+    'accountId' => '123456',
+    'sdkKey' => '32-alpha-numeric-sdk-key',
+    'shouldWaitForTrackingCalls' => true, // switch to synchronous (cURL) tracking
+    'retryConfig' => [
+        'shouldRetry' => true,        // default: true
+        'maxRetries' => 3,            // default: 3
+        'initialDelay' => 2,          // seconds; default: 2
+        'backoffMultiplier' => 2,     // delays: 2s, 4s, 8s; default: 2
+    ],
+]);
+
+// If you want synchronous calls without retries
+$vwoClient = VWO::init([
+    'accountId' => '123456',
+    'sdkKey' => '32-alpha-numeric-sdk-key',
+    'shouldWaitForTrackingCalls' => true,
+    'retryConfig' => [
+        'shouldRetry' => false,
+    ],
+]);
+```
+
 ## [1.12.0] - 2025-09-25
 
 ### Added

README.md

@@ -209,6 +209,62 @@ $vwoClient = VWO::init([
 
 Refer to the [Gateway Documentation](https://developers.vwo.com/v2/docs/gateway-service) for further details.
 
+### Synchronous network calls
+
+Synchronous network calls differ from the default (asynchronous or fire-and-forget) tracking behavior by waiting for the tracking request to return a response from the VWO server before proceeding with the rest of your application code. By default, the SDK sends tracking network calls in a way that does not block your application, providing maximum throughput and lowest latency for user actions.
+
+**Why is it so?**
+- The default asynchronous approach ensures minimal impact on user experience or application response times. Tracking calls are dispatched without waiting for a server response.
+- With synchronous calls enabled (`shouldWaitForTrackingCalls => true`), your code will block and wait for the network call to complete, allowing you to detect network errors, retry, and ensure delivery before execution continues.
+
+**When should you use synchronous calls?**
+- Use synchronous tracking when tracking data integrity or acknowledgment is critical before user flow continues (e.g., checkout flows, conversion confirmations, or compliance events).
+- It is recommended when you need to guarantee that server-side events are delivered, and are willing to trade a slight increase in user-facing latency for this assurance.
+
+
+
+You can opt-in to perform network calls synchronously by passing an init parameter.
+
+```php
+$vwoClient = VWO::init([
+  'sdkKey' => '32-alpha-numeric-sdk-key',
+  'accountId' => '123456',
+  'shouldWaitForTrackingCalls' => true,
+]);
+```
+
+Notes:
+- In PHP, the default transport for tracking is a non-blocking socket-based call (fire-and-forget).
+- When you enable `shouldWaitForTrackingCalls`, the SDK switches to a blocking cURL-based call so your code waits for the response.
+- For synchronous (cURL) calls, retry is enabled by default. You can override via `retryConfig` in init:
+
+```php
+$vwoClient = VWO::init([
+  'sdkKey' => '32-alpha-numeric-sdk-key',
+  'accountId' => '123456',
+  'shouldWaitForTrackingCalls' => true,
+  'retryConfig' => [
+    'shouldRetry' => true,        // default: true
+    'maxRetries' => 3,            // default: 3
+    'initialDelay' => 2,          // seconds; default: 2
+    'backoffMultiplier' => 2,     // delays: 2s, 4s, 8s; default: 2
+  ],
+]);
+```
+
+If you want synchronous calls but without retries, set `shouldRetry` to `false`:
+
+```php
+$vwoClient = VWO::init([
+  'sdkKey' => '32-alpha-numeric-sdk-key',
+  'accountId' => '123456',
+  'shouldWaitForTrackingCalls' => true,
+  'retryConfig' => [
+    'shouldRetry' => false,
+  ],
+]);
+```
+
 ### Storage
 
 The SDK operates in a stateless mode by default, meaning each `getFlag` call triggers a fresh evaluation of the flag against the current user context.

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "vwo/vwo-fme-php-sdk",
 
-    "version": "1.12.0",
+    "version": "1.13.0",
     "keywords": ["vwo", "fme", "sdk"],
     "license": "Apache-2.0",
     "authors": [{

src/Constants/Constants.php

@@ -40,7 +40,7 @@ class Constants {
     const DEFAULT_EVENTS_PER_REQUEST = 100;
     const SDK_NAME = 'vwo-fme-php-sdk';
 
-    const SDK_VERSION = '1.12.0';
+    const SDK_VERSION = '1.13.0';
     const AP = 'server';
 
     const SETTINGS = 'settings';
@@ -57,6 +57,20 @@ class Constants {
 
     const PRODUCT = 'product';
     const FME = 'fme';
+
+    // Retry configuration keys
+    const RETRY_SHOULD_RETRY = 'shouldRetry';
+    const RETRY_MAX_RETRIES = 'maxRetries';
+    const RETRY_INITIAL_DELAY = 'initialDelay';
+    const RETRY_BACKOFF_MULTIPLIER = 'backoffMultiplier';
+
+    // Retry configuration defaults
+    const DEFAULT_RETRY_CONFIG = [
+        self::RETRY_SHOULD_RETRY => true,
+        self::RETRY_MAX_RETRIES => 3,
+        self::RETRY_INITIAL_DELAY => 2,
+        self::RETRY_BACKOFF_MULTIPLIER => 2,
+    ];
 }
 
 ?>

src/Packages/NetworkLayer/Client/NetworkClient.php

@@ -20,69 +20,129 @@
 
 use vwo\Packages\NetworkLayer\Models\ResponseModel;
 use vwo\Packages\NetworkLayer\Models\RequestModel;
+use vwo\Services\LoggerService;
+use vwo\Enums\LogLevelEnum;
+use vwo\Constants\Constants;
 
 class NetworkClient implements NetworkClientInterface
 {
     const HTTPS = 'HTTPS';
     const DEFAULT_TIMEOUT = 5; // seconds
     private $isGatewayUrlNotSecure = false; // Flag to store the value
+    private $shouldWaitForTrackingCalls = false;
+    private $retryConfig = Constants::DEFAULT_RETRY_CONFIG;
 
     // Constructor to accept options and store the flag
     public function __construct($options = []) {
         if (isset($options['isGatewayUrlNotSecure'])) {
             $this->isGatewayUrlNotSecure = $options['isGatewayUrlNotSecure'];
         }
+        if (isset($options['shouldWaitForTrackingCalls'])) {
+            $this->shouldWaitForTrackingCalls = $options['shouldWaitForTrackingCalls'];
+        }
+        if(isset($options['retryConfig'])) {
+            $this->retryConfig = $options['retryConfig'];
+        }
     }
 
     private function shouldUseCurl($networkOptions)
     {
-        return $this->isGatewayUrlNotSecure;
+        if ($this->isGatewayUrlNotSecure || $this->shouldWaitForTrackingCalls) {
+            return true;
+        }
+        return false;
     }
 
-    private function makeCurlRequest($url, $method, $headers, $body = null, $timeout = 5)
+    private function makeCurlRequest($url, $method, $headers, $body = null, $timeout = 5, $retryConfig = [])
     {
-        $ch = curl_init();
+        // Merge with defaults to ensure all keys are present
+        $retryConfig = array_merge(Constants::DEFAULT_RETRY_CONFIG, $retryConfig);
 
-        curl_setopt_array($ch, [
-            CURLOPT_URL => $url,
-            CURLOPT_RETURNTRANSFER => true,
-            CURLOPT_TIMEOUT => $timeout,
-            CURLOPT_CUSTOMREQUEST => $method,
-            CURLOPT_SSL_VERIFYPEER => false,
-            CURLOPT_SSL_VERIFYHOST => false,
-        ]);
-
-        if (!isset($headers['Content-Type'])) {
-            $headers['Content-Type'] = 'application/json';
+        $maxRetries = $retryConfig[Constants::RETRY_MAX_RETRIES];
+        $baseDelay = $retryConfig[Constants::RETRY_INITIAL_DELAY];
+        $multiplier = $retryConfig[Constants::RETRY_BACKOFF_MULTIPLIER];
+        $shouldRetry = $retryConfig[Constants::RETRY_SHOULD_RETRY];
+
+        $retryDelays = [];
+        for ($i = 0; $i < $maxRetries; $i++) {
+            $retryDelays[$i] = $baseDelay * ($i === 0 ? 1 : pow($multiplier, $i));
         }
+        $lastError = null;
 
-        // Set headers
-        if (!empty($headers)) {
-            $curlHeaders = [];
-
-            foreach ($headers as $key => $value) {
-               $curlHeaders[] = "$key: $value"; 
+        for ($attempt = 0; $attempt < $maxRetries && $shouldRetry === true; $attempt++) {
+            $ch = curl_init();
+            
+            curl_setopt_array($ch, [
+                CURLOPT_URL => $url,
+                CURLOPT_RETURNTRANSFER => true,
+                CURLOPT_TIMEOUT => $timeout,
+                CURLOPT_CUSTOMREQUEST => $method,
+                CURLOPT_SSL_VERIFYPEER => false,
+                CURLOPT_SSL_VERIFYHOST => false,
+                CURLOPT_FOLLOWLOCATION => true,
+                CURLOPT_MAXREDIRS => 5,
+            ]);
+
+            if (!isset($headers['Content-Type'])) {
+                $headers['Content-Type'] = 'application/json';
             }
-        }
-        curl_setopt($ch, CURLOPT_HTTPHEADER, $curlHeaders);
 
-        // Set body for POST requests
-        if ($method === 'POST' && $body) {
-            curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
-        }
+            // Set headers
+            $curlHeaders = [];
+            if (!empty($headers)) {
+                foreach ($headers as $key => $value) {
+                   $curlHeaders[] = "$key: $value"; 
+                }
+            }
+            curl_setopt($ch, CURLOPT_HTTPHEADER, $curlHeaders);
 
-        $response = curl_exec($ch);
+            // Set body for POST requests
+            if ($method === 'POST' && $body) {
+                curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
+                if (defined('CURLOPT_POSTREDIR')) {
+                    curl_setopt($ch, CURLOPT_POSTREDIR, 3); // keep POST on 301/302 redirects
+                }
+            }
 
-        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
-        $error = curl_error($ch);
-        
-        curl_close($ch);
+            $response = curl_exec($ch);
+            $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+            $error = curl_error($ch);
+            
+            curl_close($ch);
+
+            // Check if request was successful
+            if (!$error && $httpCode >= 200 && $httpCode < 300) {
+                return [
+                    'body' => $response,
+                    'status_code' => $httpCode
+                ];
+            }
 
-        if ($error) {
-            throw new \Exception("cURL error: $error");
+            // Store the error for potential re-throwing
+            $lastError = $error ? "cURL error: $error" : "HTTP error: $httpCode";
+            
+            // If this is not the last attempt, wait before retrying
+            if ($attempt < $maxRetries ) {
+                $delay = $retryDelays[$attempt] ?? $baseDelay;
+                
+                LoggerService::error('NETWORK_CALL_RETRY_ATTEMPT', [
+                    'endPoint' => $url,
+                    'err' => $lastError,
+                    'delay' => $delay,
+                    'attempt' => $attempt + 1,
+                    'maxRetries' => $maxRetries
+                ]);
+                sleep($delay);
+            } else {
+                LoggerService::error('NETWORK_CALL_RETRY_FAILED', [
+                    'endPoint' => $url,
+                    'err' => $lastError
+                ]);
+            }
         }
 
-        return $response;
+        // If we get here, all retries failed
+        throw new \Exception($lastError);
     }
 
     private function createSocketConnection($url, $timeout)
@@ -205,13 +265,15 @@ public function GET($request)
         try {
             // Check if we should use cURL instead of socket
             if ($this->shouldUseCurl($networkOptions)) {
-                $rawResponse = $this->makeCurlRequest(
+                $curlResponse = $this->makeCurlRequest(
                     $networkOptions['url'],
                     'GET',
                     $networkOptions['headers'],
                     null,
                     $networkOptions['timeout'] / 1000
                 );
+                $rawResponse = $curlResponse['body'];
+                $responseModel->setStatusCode($curlResponse['status_code']);
             } else {
                 // Use socket connection (existing logic)
                 $socket = $this->createSocketConnection(
@@ -246,23 +308,37 @@ public function POST($request)
         $networkOptions = $request->getOptions();
         $responseModel = new ResponseModel();
 
+        // NetworkManager ensures retryConfig is set and validated in options
+        $retryConfig = $request->getRetryConfig();
+
         try {
-            // Check if we should use cURL instead of socket
+            // Check if we should use cURL (either for synchronous or gateway fallback)
             if ($this->shouldUseCurl($networkOptions)) {
-                $rawResponse = $this->makeCurlRequest(
+                $curlResponse = $this->makeCurlRequest(
                     $networkOptions['url'],
                     'POST',
                     $networkOptions['headers'],
                     $networkOptions['body'],
-                    $networkOptions['timeout'] / 1000
+                    $networkOptions['timeout'] / 1000,
+                    $retryConfig
                 );
 
-                $parsedData = json_decode($rawResponse, false);
-                if ($parsedData === null && json_last_error() !== JSON_ERROR_NONE) {
-                    throw new \Exception("Failed to parse JSON response: " . json_last_error_msg());
-                }
+                $rawResponse = $curlResponse['body'];
+                $responseModel->setStatusCode($curlResponse['status_code']);
 
-                $responseModel->setData($parsedData);
+                // If body is empty or whitespace, don't attempt JSON parse
+                if (is_string($rawResponse) && trim($rawResponse) === '') {
+                    $responseModel->setData(null);
+                } else {
+                    $parsedData = json_decode($rawResponse, false);
+                    if ($parsedData === null && json_last_error() !== JSON_ERROR_NONE) {
+                        // Non-JSON response; keep status code and set error, but do not throw
+                        $responseModel->setError('Non-JSON response body');
+                        $responseModel->setData(null);
+                    } else {
+                        $responseModel->setData($parsedData);
+                    }
+                }
             } else {
                 // Use socket connection (existing logic)
                 $socket = $this->createSocketConnection(
@@ -277,12 +353,18 @@ public function POST($request)
                 $rawResponse = $this->readResponse($socket);
                 fclose($socket);
 
-                $parsedData = json_decode($rawResponse['body'], false);
-                if ($parsedData === null && json_last_error() !== JSON_ERROR_NONE) {
-                    throw new \Exception("Failed to parse JSON response: " . json_last_error_msg());
+                $parsedBody = $rawResponse['body'];
+                if (is_string($parsedBody) && trim($parsedBody) === '') {
+                    $responseModel->setData(null);
+                } else {
+                    $parsedData = json_decode($parsedBody, false);
+                    if ($parsedData === null && json_last_error() !== JSON_ERROR_NONE) {
+                        $responseModel->setError('Non-JSON response body');
+                        $responseModel->setData(null);
+                    } else {
+                        $responseModel->setData($parsedData);
+                    }
                 }
-                
-                $responseModel->setData($parsedData);
             }
 
         } catch (\Exception $e) {