feature #37175 [Mime] Deprecate Address::fromString() (fabpot)

This PR was merged into the 5.2-dev branch.

Discussion
----------

[Mime] Deprecate Address::fromString()

| Q             | A
| ------------- | ---
| Branch?       | master <!-- see below -->
| Bug fix?      | no
| New feature?  | no <!-- please update src/**/CHANGELOG.md files -->
| Deprecations? | yes <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tickets       | n/a <!-- prefix each issue number with "Fix #", if any -->
| License       | MIT
| Doc PR        | n/a

Follow-up of #37167

Commits
-------

6e28fda [Mime] Deprecate Address::fromString()

UPGRADE-5.2.md

@@ -1,6 +1,11 @@
 UPGRADE FROM 5.1 to 5.2
 =======================
 
+Mime
+----
+
+ * Deprecated `Address::fromString()`, use `Address::create()` instead
+
 Validator
 ---------
 

UPGRADE-6.0.md

@@ -89,6 +89,11 @@ Messenger
  * The signature of method `RetryStrategyInterface::isRetryable()` has been updated to `RetryStrategyInterface::isRetryable(Envelope $message, \Throwable $throwable = null)`.
  * The signature of method `RetryStrategyInterface::getWaitingTime()` has been updated to `RetryStrategyInterface::getWaitingTime(Envelope $message, \Throwable $throwable = null)`.
 
+Mime
+----
+
+ * Removed `Address::fromString()`, use `Address::create()` instead
+
 OptionsResolver
 ---------------
 

src/Symfony/Component/Mime/Address.php

@@ -89,7 +89,15 @@ public static function create($address): self
             return $address;
         }
         if (\is_string($address)) {
-            return self::fromString($address);
+            if (false === strpos($address, '<')) {
+                return new self($address);
+            }
+
+            if (!preg_match(self::FROM_STRING_PATTERN, $address, $matches)) {
+                throw new InvalidArgumentException(sprintf('Could not parse "%s" to a "%s" instance.', $address, self::class));
+            }
+
+            return new self($matches['addrSpec'], trim($matches['displayName'], ' \'"'));
         }
 
         throw new InvalidArgumentException(sprintf('An address can be an instance of Address or a string ("%s" given).', get_debug_type($address)));
@@ -110,14 +118,19 @@ public static function createArray(array $addresses): array
         return $addrs;
     }
 
+    /**
+     * @deprecated since Symfony 5.2, use "create()" instead.
+     */
     public static function fromString(string $string): self
     {
+        trigger_deprecation('symfony/mime', '5.2', '"%s()" is deprecated, use "%s::create()" instead.', __METHOD__, __CLASS__);
+
         if (false === strpos($string, '<')) {
             return new self($string, '');
         }
 
         if (!preg_match(self::FROM_STRING_PATTERN, $string, $matches)) {
-            throw new InvalidArgumentException(sprintf('Could not parse "%s" to a "%s" instance.', $string, static::class));
+            throw new InvalidArgumentException(sprintf('Could not parse "%s" to a "%s" instance.', $string, self::class));
         }
 
         return new self($matches['addrSpec'], trim($matches['displayName'], ' \'"'));

src/Symfony/Component/Mime/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+5.2.0
+-----
+
+ * Deprecated `Address::fromString()`, use `Address::create()` instead
+
 4.4.0
 -----
 

src/Symfony/Component/Mime/Tests/AddressTest.php

@@ -44,6 +44,19 @@ public function testCreate()
         $this->assertEquals($a, Address::create('fabien@symfony.com'));
     }
 
+    /**
+     * @dataProvider fromStringProvider
+     */
+    public function testCreateWithString($string, $displayName, $addrSpec)
+    {
+        $address = Address::create($string);
+        $this->assertEquals($displayName, $address->getName());
+        $this->assertEquals($addrSpec, $address->getAddress());
+        $fromToStringAddress = Address::create($address->toString());
+        $this->assertEquals($displayName, $fromToStringAddress->getName());
+        $this->assertEquals($addrSpec, $fromToStringAddress->getAddress());
+    }
+
     public function testCreateWrongArg()
     {
         $this->expectException(\InvalidArgumentException::class);
@@ -81,6 +94,7 @@ public function nameEmptyDataProvider(): array
 
     /**
      * @dataProvider fromStringProvider
+     * @group legacy
      */
     public function testFromString($string, $displayName, $addrSpec)
     {
@@ -92,6 +106,9 @@ public function testFromString($string, $displayName, $addrSpec)
         $this->assertEquals($addrSpec, $fromToStringAddress->getAddress());
     }
 
+    /**
+     * @group legacy
+     */
     public function testFromStringFailure()
     {
         $this->expectException(InvalidArgumentException::class);

src/Symfony/Component/Mime/composer.json

@@ -17,6 +17,7 @@
     ],
     "require": {
         "php": ">=7.2.5",
+        "symfony/deprecation-contracts": "^2.1",
         "symfony/polyfill-intl-idn": "^1.10",
         "symfony/polyfill-mbstring": "^1.0",
         "symfony/polyfill-php80": "^1.15"