Release v3.28.0

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];
+ }
+}