feat: add deprecation notice (#2951)

Author: stobrien89

.changes/nextrelease/deprecation-warning.json

@@ -0,0 +1,7 @@
+[
+  {
+    "type": "feature",
+    "category": "",
+    "description": "Adds notice for the upcoming deprecation of PHP versions 8.0.x and below."
+  }
+]

Makefile

@@ -24,7 +24,7 @@ clear-cache:
 	php build/aws-clear-cache.php
 
 test:
-	@AWS_ACCESS_KEY_ID=foo AWS_SECRET_ACCESS_KEY=bar AWS_CSM_ENABLED=false AWS_REGION= AWS_ENDPOINT_URL= \
+	@AWS_ACCESS_KEY_ID=foo AWS_SECRET_ACCESS_KEY=bar AWS_CSM_ENABLED=false AWS_REGION= AWS_ENDPOINT_URL= AWS_SUPPRESS_PHP_DEPRECATION_WARNING=true \
 	vendor/bin/phpunit --testsuite=unit $(TEST)
 
 test-phar: package

src/AwsClient.php

@@ -684,6 +684,11 @@ protected function isUseEndpointV2()
     }
 
     public static function emitDeprecationWarning() {
+        trigger_error(
+            "This method is deprecated. It will be removed in an upcoming release."
+            , E_USER_DEPRECATED
+        );
+
         $phpVersion = PHP_VERSION_ID;
         if ($phpVersion <  70205) {
             $phpVersionString = phpversion();

src/ClientResolver.php

@@ -308,6 +308,13 @@ class ClientResolver
             'doc'       => 'Set to false to disable checking for shared aws config files usually located in \'~/.aws/config\' and \'~/.aws/credentials\'.  This will be ignored if you set the \'profile\' setting.',
             'default'   => true,
         ],
+        'suppress_php_deprecation_warning' => [
+            'type'      => 'value',
+            'valid'     => ['bool'],
+            'doc' => 'Set to true to suppress PHP runtime deprecation warnings. The current deprecation campaign is PHP versions 8.0.x and below, taking effect on 1/13/2025.',
+            'default' => false,
+            'fn' => [__CLASS__, '_apply_suppress_php_deprecation_warning']
+        ],
         'account_id_endpoint_mode' => [
             'type'      => 'value',
             'valid'     => ['string'],
@@ -1230,6 +1237,28 @@ public static function _apply_ignore_configured_endpoint_urls($value, array &$ar
         $args['config']['ignore_configured_endpoint_urls'] = $value;
     }
 
+    public static function _apply_suppress_php_deprecation_warning($value, &$args)
+    {
+        if ($value)  {
+            $args['suppress_php_deprecation_warning'] = true;
+        } elseif (!empty(getenv("AWS_SUPPRESS_PHP_DEPRECATION_WARNING"))) {
+            $args['suppress_php_deprecation_warning']
+                = \Aws\boolean_value(getenv("AWS_SUPPRESS_PHP_DEPRECATION_WARNING"));
+        } elseif (!empty($_SERVER["AWS_SUPPRESS_PHP_DEPRECATION_WARNING"])) {
+            $args['suppress_php_deprecation_warning'] =
+                \Aws\boolean_value($_SERVER["AWS_SUPPRESS_PHP_DEPRECATION_WARNING"]);
+        } elseif (!empty($_ENV["AWS_SUPPRESS_PHP_DEPRECATION_WARNING"])) {
+            $args['suppress_php_deprecation_warning'] =
+                \Aws\boolean_value($_SERVER["AWS_SUPPRESS_PHP_DEPRECATION_WARNING"]);
+        }
+
+        if ($args['suppress_php_deprecation_warning'] === false
+            && PHP_VERSION_ID < 80100
+        ) {
+            self::emitDeprecationWarning();
+        }
+    }
+
     public static function _default_ignore_configured_endpoint_urls(array &$args)
     {
         return ConfigurationResolver::resolve(
@@ -1392,20 +1421,39 @@ private function _apply_client_context_params(array $args)
         }
     }
 
-    private static function isValidService($service) {
+    private static function isValidService($service)
+    {
         if (is_null($service)) {
             return false;
         }
         $services = \Aws\manifest();
         return isset($services[$service]);
     }
 
-    private static function isValidApiVersion($service, $apiVersion) {
+    private static function isValidApiVersion($service, $apiVersion)
+    {
         if (is_null($apiVersion)) {
             return false;
         }
         return is_dir(
             __DIR__ . "/data/{$service}/$apiVersion"
         );
     }
+
+    private static function emitDeprecationWarning()
+    {
+        $phpVersionString = phpversion();
+        trigger_error(
+            "This installation of the SDK is using PHP version"
+            .  " {$phpVersionString}, which will be deprecated on January"
+            .  " 13th, 2025.\nPlease upgrade your PHP version to a minimum of"
+            .  " 8.1.x to continue receiving updates for the AWS"
+            .  " SDK for PHP.\nTo disable this warning, set"
+            .  " suppress_php_deprecation_warning to true on the client constructor"
+            .  " or set the environment variable AWS_SUPPRESS_PHP_DEPRECATION_WARNING"
+            .  " to true.\nMore information can be found at: "
+            .   "https://aws.amazon.com/blogs/developer/announcing-the-end-of-support-for-php-runtimes-8-0-x-and-below-in-the-aws-sdk-for-php/\n",
+            E_USER_WARNING
+        );
+    }
 }

tests/AwsClientTest.php

@@ -767,6 +767,17 @@ public function testAppliesConfiguredSignatureVersionViaClientConfig() {
         $client->foo();
     }
 
+
+    public function testCallingEmitDeprecationWarningEmitsDeprecationWarning()
+    {
+        $this->expectDeprecation();
+        $this->expectDeprecationMessage(
+            "This method is deprecated. It will be removed in an upcoming release."
+        );
+        $client = $this->createClient();
+        $client::emitDeprecationWarning();
+    }
+
     /**
      * @dataProvider signingRegionSetProvider
      * @runInSeparateProcess
@@ -833,7 +844,6 @@ public function testSigningRegionSetResolution(
         }
 
         putenv('AWS_SIGV4A_SIGNING_REGION_SET=');
-
     }
 
     public function signingRegionSetProvider()

tests/ClientResolverTest.php

@@ -1677,4 +1677,23 @@ public function testAppliesAuthSchemeResolver()
             $conf['auth_scheme_resolver']
         );
     }
+
+    public function testEmitsDeprecationWarning()
+    {
+        if (PHP_VERSION_ID >= 80100) {
+            $this->markTestSkipped();
+        }
+
+        putenv('AWS_SUPPRESS_PHP_DEPRECATION_WARNING=false');
+        $this->expectWarning();
+        $this->expectWarningMessage('This installation of the SDK is using PHP version');
+
+        $r = new ClientResolver(ClientResolver::getDefaultArguments());
+
+        try {
+            $r->resolve(['service' => 'sqs', 'region' => 'x'], new HandlerList());
+        } finally {
+            putenv('AWS_SUPPRESS_PHP_DEPRECATION_WARNING=true');
+        }
+    }
 }