Release v3.28.0

Author: imjoehaines

CHANGELOG.md

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+## 3.28.0 (2022-05-18)
+
+### Enhancements
+
+* New APIs to support feature flag and experiment functionality. For more information, please see https://docs.bugsnag.com/product/features-experiments.
+  [#646](https://github.com/bugsnag/bugsnag-php/pull/646)
+
 ## 3.27.0 (2022-02-07)
 
 ### Enhancements

src/Client.php

@@ -22,7 +22,7 @@
 use Composer\CaBundle\CaBundle;
 use GuzzleHttp;
 
-class Client
+class Client implements FeatureDataStore
 {
     /**
      * The default event notification endpoint.
@@ -806,6 +806,54 @@ public function getMetaData()
         return $this->config->getMetaData();
     }
 
+    /**
+     * Add a single feature flag to all future reports.
+     *
+     * @param string $name
+     * @param string|null $variant
+     *
+     * @return void
+     */
+    public function addFeatureFlag($name, $variant = null)
+    {
+        $this->config->addFeatureFlag($name, $variant);
+    }
+
+    /**
+     * Add multiple feature flags to all future reports.
+     *
+     * @param FeatureFlag[] $featureFlags
+     * @phpstan-param list<FeatureFlag> $featureFlags
+     *
+     * @return void
+     */
+    public function addFeatureFlags(array $featureFlags)
+    {
+        $this->config->addFeatureFlags($featureFlags);
+    }
+
+    /**
+     * Remove the feature flag with the given name from all future reports.
+     *
+     * @param string $name
+     *
+     * @return void
+     */
+    public function clearFeatureFlag($name)
+    {
+        $this->config->clearFeatureFlag($name);
+    }
+
+    /**
+     * Remove all feature flags from all future reports.
+     *
+     * @return void
+     */
+    public function clearFeatureFlags()
+    {
+        $this->config->clearFeatureFlags();
+    }
+
     /**
      * Set Bugsnag's error reporting level.
      *

src/Configuration.php

@@ -2,9 +2,10 @@
 
 namespace Bugsnag;
 
+use Bugsnag\Internal\FeatureFlagDelegate;
 use InvalidArgumentException;
 
-class Configuration
+class Configuration implements FeatureDataStore
 {
     /**
      * The default endpoint for event notifications.
@@ -84,7 +85,7 @@ class Configuration
      */
     protected $notifier = [
         'name' => 'Bugsnag PHP (Official)',
-        'version' => '3.27.0',
+        'version' => '3.28.0',
         'url' => 'https://bugsnag.com',
     ];
 
@@ -116,6 +117,13 @@ class Configuration
      */
     protected $metaData = [];
 
+    /**
+     * The associated feature flags.
+     *
+     * @var FeatureFlagDelegate
+     */
+    private $featureFlags;
+
     /**
      * The error reporting level.
      *
@@ -196,6 +204,7 @@ public function __construct($apiKey)
 
         $this->apiKey = $apiKey;
         $this->fallbackType = php_sapi_name();
+        $this->featureFlags = new FeatureFlagDelegate();
 
         // Add PHP runtime version to device data
         $this->mergeDeviceData(['runtimeVersions' => ['php' => phpversion()]]);
@@ -588,6 +597,64 @@ public function getMetaData()
         return $this->metaData;
     }
 
+    /**
+     * Add a single feature flag to all future reports.
+     *
+     * @param string $name
+     * @param string|null $variant
+     *
+     * @return void
+     */
+    public function addFeatureFlag($name, $variant = null)
+    {
+        $this->featureFlags->add($name, $variant);
+    }
+
+    /**
+     * Add multiple feature flags to all future reports.
+     *
+     * @param FeatureFlag[] $featureFlags
+     * @phpstan-param list<FeatureFlag> $featureFlags
+     *
+     * @return void
+     */
+    public function addFeatureFlags(array $featureFlags)
+    {
+        $this->featureFlags->merge($featureFlags);
+    }
+
+    /**
+     * Remove the feature flag with the given name from all future reports.
+     *
+     * @param string $name
+     *
+     * @return void
+     */
+    public function clearFeatureFlag($name)
+    {
+        $this->featureFlags->remove($name);
+    }
+
+    /**
+     * Remove all feature flags from all future reports.
+     *
+     * @return void
+     */
+    public function clearFeatureFlags()
+    {
+        $this->featureFlags->clear();
+    }
+
+    /**
+     * @internal
+     *
+     * @return FeatureFlagDelegate
+     */
+    public function getFeatureFlagsCopy()
+    {
+        return clone $this->featureFlags;
+    }
+
     /**
      * Set Bugsnag's error reporting level.
      *

src/FeatureDataStore.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Bugsnag;
+
+interface FeatureDataStore
+{
+    /**
+     * Add a single feature flag.
+     *
+     * @param string $name
+     * @param string|null $variant
+     *
+     * @return void
+     */
+    public function addFeatureFlag($name, $variant = null);
+
+    /**
+     * Add multiple feature flags.
+     *
+     * The new flags will be merged with any existing feature flags, with the
+     * newer variant values taking precedence
+     *
+     * @param array $featureFlags
+     * @phpstan-param list<FeatureFlag> $featureFlags
+     *
+     * @return void
+     */
+    public function addFeatureFlags(array $featureFlags);
+
+    /**
+     * Remove a single feature flag by name.
+     *
+     * @param string $name
+     *
+     * @return void
+     */
+    public function clearFeatureFlag($name);
+
+    /**
+     * Remove all feature flags.
+     *
+     * @return void
+     */
+    public function clearFeatureFlags();
+}

src/FeatureFlag.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Bugsnag;
+
+final class FeatureFlag
+{
+    /**
+     * A name that identifies this feature flag.
+     *
+     * @var string
+     */
+    private $name;
+
+    /**
+     * An optional variant for this feature flag.
+     *
+     * @var string|null
+     */
+    private $variant;
+
+    /**
+     * @param string $name a name that identifies this feature flag
+     * @param string|null $variant an optional variant for this feature flag.
+     */
+    public function __construct($name, $variant = null)
+    {
+        $this->name = $name;
+
+        // ensure the variant can only be null or a string as the API only
+        // accepts strings (null values will be omitted from the payload)
+        if ($variant !== null && !is_string($variant)) {
+            $json = json_encode($variant);
+
+            // if JSON encoding fails, omit the variant
+            $variant = $json === false ? null : $json;
+        }
+
+        $this->variant = $variant;
+    }
+
+    /**
+     * Get the feature flag's name.
+     *
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->name;
+    }
+
+    /**
+     * Get the feature flag's variant.
+     *
+     * @return string|null
+     */
+    public function getVariant()
+    {
+        return $this->variant;
+    }
+
+    /**
+     * Convert this feature flag into the format used by the Bugsnag Event API.
+     *
+     * This has two forms, either with a variant:
+     *   { "featureFlag": "name", "variant": "variant" }
+     *
+     * or if the feature flag has no variant:
+     *   { "featureFlag": "no variant" }
+     *
+     * @return array[]
+     * @phpstan-return array{featureFlag: string, variant?: string}
+     */
+    public function toArray()
+    {
+        if (is_string($this->variant)) {
+            return ['featureFlag' => $this->name, 'variant' => $this->variant];
+        }
+
+        return ['featureFlag' => $this->name];
+    }
+}