vendor/shopware/core/Framework/Feature.php line 175

  1. <?php declare(strict_types=1);
  3. namespace Shopware\Core\Framework;
  5. use PHPUnit\Framework\TestCase;
  6. use Shopware\Core\DevOps\Environment\EnvironmentHelper;
  7. use Shopware\Core\Framework\Log\Package;
  8. use Shopware\Core\Framework\Script\Debugging\ScriptTraces;
  10. /**
  11.  * @phpstan-type FeatureFlagConfig array{name?: string, default?: boolean, major?: boolean, description?: string}
  12.  */
  13. #[Package('core')]
  14. class Feature
  15. {
  16.     final public const ALL_MAJOR = 'major';
  18.     /**
  19.      * @var array<bool>
  20.      */
  21.     private static array $silent = [];
  23.     /**
  24.      * @var array<string, FeatureFlagConfig>
  25.      */
  26.     private static array $registeredFeatures = [];
  28.     public static function normalizeName(string $name): string
  29.     {
  30.         /*
  31.          * Examples:
  32.          * - NEXT-1234
  33.          * - FEATURE_NEXT_1234
  34.          * - SAAS_321
  35.          * - v6.5.0.0 => v6_5_0_0
  36.          */
  37.         return \strtoupper(\str_replace(['.', ':', '-'], '_', $name));
  38.     }
  40.     /**
  41.      * @param array<string> $features
  42.      *
  43.      * @return mixed|null
  44.      */
  45.     public static function fake(array $features, \Closure $closure)
  46.     {
  47.         $before = self::$registeredFeatures;
  48.         $serverVarsBackup = $_SERVER;
  50.         $result = null;
  52.         try {
  53.             self::$registeredFeatures = [];
  54.             foreach ($_SERVER as $key => $value) {
  55.                 if (str_starts_with($key, 'v6.') || str_starts_with($key, 'FEATURE_') || str_starts_with($key, 'V6_')) {
  56.                     // set to false so that $_ENV is not checked
  57.                     $_SERVER[$key] = false;
  58.                 }
  59.             }
  61.             if ($features) {
  62.                 foreach ($features as $feature) {
  63.                     $_SERVER[Feature::normalizeName($feature)] = true;
  64.                 }
  65.             }
  67.             $result = $closure();
  68.         } finally {
  69.             self::$registeredFeatures = $before;
  70.             $_SERVER = $serverVarsBackup;
  71.         }
  73.         return $result;
  74.     }
  76.     public static function isActive(string $feature): bool
  77.     {
  78.         $env = EnvironmentHelper::getVariable('APP_ENV', 'prod');
  79.         $feature = self::normalizeName($feature);
  81.         if (self::$registeredFeatures !== []
  82.             && !isset(self::$registeredFeatures[$feature])
  83.             && $env !== 'prod'
  84.         ) {
  85.             trigger_error('Unknown feature "' . $feature . '"', \E_USER_WARNING);
  86.         }
  88.         $featureAll = EnvironmentHelper::getVariable('FEATURE_ALL', '');
  89.         if (self::isTrue((string) $featureAll) && (self::$registeredFeatures === [] || \array_key_exists($feature, self::$registeredFeatures))) {
  90.             if ($featureAll === Feature::ALL_MAJOR) {
  91.                 return true;
  92.             }
  94.             // return true if it's registered and not a major feature
  95.             if (isset(self::$registeredFeatures[$feature]) && (self::$registeredFeatures[$feature]['major'] ?? false) === false) {
  96.                 return true;
  97.             }
  98.         }
  100.         if (!EnvironmentHelper::hasVariable($feature) && !EnvironmentHelper::hasVariable(\strtolower($feature))) {
  101.             $fallback = self::$registeredFeatures[$feature]['default'] ?? false;
  103.             return (bool) $fallback;
  104.         }
  106.         return self::isTrue(trim((string) EnvironmentHelper::getVariable($feature)));
  107.     }
  109.     public static function ifActive(string $flagName, \Closure $closure): void
  110.     {
  111.         self::isActive($flagName) && $closure();
  112.     }
  114.     public static function callSilentIfInactive(string $flagName, \Closure $closure): void
  115.     {
  116.         $before = isset(self::$silent[$flagName]);
  117.         self::$silent[$flagName] = true;
  119.         try {
  120.             if (!self::isActive($flagName)) {
  121.                 $closure();
  122.             }
  123.         } finally {
  124.             if (!$before) {
  125.                 unset(self::$silent[$flagName]);
  126.             }
  127.         }
  128.     }
  130.     public static function silent(string $flagName, \Closure $closure): mixed
  131.     {
  132.         $before = isset(self::$silent[$flagName]);
  133.         self::$silent[$flagName] = true;
  135.         try {
  136.             $result = $closure();
  137.         } finally {
  138.             if (!$before) {
  139.                 unset(self::$silent[$flagName]);
  140.             }
  141.         }
  143.         return $result;
  144.     }
  146.     public static function skipTestIfInActive(string $flagName, TestCase $test): void
  147.     {
  148.         if (self::isActive($flagName)) {
  149.             return;
  150.         }
  152.         $test->markTestSkipped('Skipping feature test for flag  "' . $flagName . '"');
  153.     }
  155.     public static function skipTestIfActive(string $flagName, TestCase $test): void
  156.     {
  157.         if (!self::isActive($flagName)) {
  158.             return;
  159.         }
  161.         $test->markTestSkipped('Skipping feature test for flag  "' . $flagName . '"');
  162.     }
  164.     public static function throwException(string $flag, string $message, bool $state = true): void
  165.     {
  166.         if (self::isActive($flag) === $state || (self::$registeredFeatures !== [] && !self::has($flag))) {
  167.             throw new \RuntimeException($message);
  168.         }
  170.         if (\PHP_SAPI !== 'cli') {
  171.             ScriptTraces::addDeprecationNotice($message);
  172.         }
  173.     }
  175.     public static function triggerDeprecationOrThrow(string $majorFlag, string $message): void
  176.     {
  177.         if (self::isActive($majorFlag) || (self::$registeredFeatures !== [] && !self::has($majorFlag))) {
  178.             throw new \RuntimeException('Tried to access deprecated functionality: ' . $message);
  179.         }
  181.         if (!isset(self::$silent[$majorFlag]) || !self::$silent[$majorFlag]) {
  182.             if (\PHP_SAPI !== 'cli') {
  183.                 ScriptTraces::addDeprecationNotice($message);
  184.             }
  186.             trigger_deprecation('shopware/core', '', $message);
  187.         }
  188.     }
  190.     public static function deprecatedMethodMessage(string $class, string $method, string $majorVersion, ?string $replacement = null): string
  191.     {
  192.         $message = \sprintf(
  193.             'Method "%s::%s()" is deprecated and will be removed in %s.',
  194.             $class,
  195.             $method,
  196.             $majorVersion
  197.         );
  199.         if ($replacement) {
  200.             $message = \sprintf('%s Use "%s" instead.', $message, $replacement);
  201.         }
  203.         return $message;
  204.     }
  206.     public static function deprecatedClassMessage(string $class, string $majorVersion, ?string $replacement = null): string
  207.     {
  208.         $message = \sprintf(
  209.             'Class "%s" is deprecated and will be removed in %s.',
  210.             $class,
  211.             $majorVersion
  212.         );
  214.         if ($replacement) {
  215.             $message = \sprintf('%s Use "%s" instead.', $message, $replacement);
  216.         }
  218.         return $message;
  219.     }
  221.     public static function has(string $flag): bool
  222.     {
  223.         $flag = self::normalizeName($flag);
  225.         return isset(self::$registeredFeatures[$flag]);
  226.     }
  228.     /**
  229.      * @return array<string, bool>
  230.      */
  231.     public static function getAll(bool $denormalized = true): array
  232.     {
  233.         $resolvedFlags = [];
  235.         foreach (self::$registeredFeatures as $name => $_) {
  236.             $active = self::isActive($name);
  237.             $resolvedFlags[$name] = $active;
  239.             if (!$denormalized) {
  240.                 continue;
  241.             }
  242.             $resolvedFlags[self::denormalize($name)] = $active;
  243.         }
  245.         return $resolvedFlags;
  246.     }
  248.     /**
  249.      * @param FeatureFlagConfig $metaData
  250.      *
  251.      * @internal
  252.      */
  253.     public static function registerFeature(string $name, array $metaData = []): void
  254.     {
  255.         $name = self::normalizeName($name);
  257.         // merge with existing data
  259.         /** @var array{name?: string, default?: boolean, major?: boolean, description?: string} $metaData */
  260.         $metaData = array_merge(
  261.             self::$registeredFeatures[$name] ?? [],
  262.             $metaData
  263.         );
  265.         // set defaults
  266.         $metaData['major'] = (bool) ($metaData['major'] ?? false);
  267.         $metaData['default'] = (bool) ($metaData['default'] ?? false);
  268.         $metaData['description'] = (string) ($metaData['description'] ?? '');
  270.         self::$registeredFeatures[$name] = $metaData;
  271.     }
  273.     /**
  274.      * @param array<string, FeatureFlagConfig>|string[] $registeredFeatures
  275.      *
  276.      * @internal
  277.      */
  278.     public static function registerFeatures(iterable $registeredFeatures): void
  279.     {
  280.         foreach ($registeredFeatures as $flag => $data) {
  281.             // old format
  282.             if (\is_string($data)) {
  283.                 $flag = $data;
  284.                 $data = [];
  285.             }
  287.             self::registerFeature($flag, $data);
  288.         }
  289.     }
  291.     /**
  292.      * @internal
  293.      */
  294.     public static function resetRegisteredFeatures(): void
  295.     {
  296.         self::$registeredFeatures = [];
  297.     }
  299.     /**
  300.      * @internal
  301.      *
  302.      * @return array<string, FeatureFlagConfig>
  303.      */
  304.     public static function getRegisteredFeatures(): array
  305.     {
  306.         return self::$registeredFeatures;
  307.     }
  309.     private static function isTrue(string $value): bool
  310.     {
  311.         return $value
  312.             && $value !== 'false'
  313.             && $value !== '0'
  314.             && $value !== '';
  315.     }
  317.     private static function denormalize(string $name): string
  318.     {
  319.         return \strtolower(\str_replace(['_'], '.', $name));
  320.     }
  321. }