Merge pull request #7909 from lcobucci/add-deprecation-messages

Add deprecation messages

UPGRADE.md

@@ -10,6 +10,14 @@ Method `Doctrine\ORM\AbstractQuery#useResultCache()` which could be used for bot
 To optimize DB interaction, `Doctrine\ORM\Tools\Pagination\Paginator` no longer fetches identifiers to be able to
 perform the pagination with join collections when max results isn't set in the query.
 
+## Deprecated number unaware `Doctrine\ORM\Mapping\UnderscoreNamingStrategy`
+
+In the last patch of the `v2.6.x` series, we fixed a bug that was not converting names properly when they had numbers
+(e.g.: `base64Encoded` was wrongly converted to `base64encoded` instead of `base64_encoded`).
+
+In order to not break BC we've introduced a way to enable the fixed behavior using a boolean constructor argument. This
+argument will be removed in 3.0 and the default behavior will be the fixed one.
+
 ## Deprecated: `Doctrine\ORM\AbstractQuery#useResultCache()`	
 
 Method `Doctrine\ORM\AbstractQuery#useResultCache()` is deprecated because it is split into `enableResultCache()`
@@ -82,6 +90,14 @@ restful operations, you should look at alternatives such as [JMSSerializer](http
 Final keyword will be added to the `EntityManager::class` in Doctrine 3.0 in order to ensure that EntityManager
  is not used as valid extension point. Valid extension point should be EntityManagerInterface.
 
+## Deprecated `EntityManager#clear($entityName)`
+
+If your code relies on clearing a single entity type via `EntityManager#clear($entityName)`,
+the signature has been changed to `EntityManager#clear()`.
+
+The main reason is that partial clears caused multiple issues with data integrity
+in the managed entity graph, which was constantly spawning more edge-case bugs/scenarios.
+
 ## Deprecated `EntityManager#flush($entity)` and `EntityManager#flush($entities)`
 
 If your code relies on single entity flushing optimisations via

lib/Doctrine/ORM/EntityManager.php

@@ -29,6 +29,7 @@
 use Doctrine\ORM\Query\FilterCollection;
 use Doctrine\Common\Util\ClassUtils;
 use Throwable;
+use const E_USER_DEPRECATED;
 use function trigger_error;
 
 /**
@@ -555,6 +556,13 @@ public function clear($entityName = null)
             throw ORMInvalidArgumentException::invalidEntityName($entityName);
         }
 
+        if ($entityName !== null) {
+            @trigger_error(
+                'Calling ' . __METHOD__ . '() with any arguments to clear specific entities is deprecated and will not be supported in Doctrine 3.0.',
+                E_USER_DEPRECATED
+            );
+        }
+
         $this->unitOfWork->clear(
             null === $entityName
                 ? null

lib/Doctrine/ORM/Mapping/UnderscoreNamingStrategy.php

@@ -22,12 +22,14 @@
 
 use const CASE_LOWER;
 use const CASE_UPPER;
+use const E_USER_DEPRECATED;
 use function preg_replace;
 use function strpos;
 use function strrpos;
 use function strtolower;
 use function strtoupper;
 use function substr;
+use function trigger_error;
 
 /**
  * Naming strategy implementing the underscore naming convention.
@@ -58,6 +60,13 @@ class UnderscoreNamingStrategy implements NamingStrategy
      */
     public function __construct($case = CASE_LOWER, bool $numberAware = false)
     {
+        if (! $numberAware) {
+            @trigger_error(
+                'Creating ' . self::class . ' without making it number aware is deprecated and will be removed in Doctrine 3.0.',
+                E_USER_DEPRECATED
+            );
+        }
+
         $this->case    = $case;
         $this->pattern = $numberAware ? self::NUMBER_AWARE_PATTERN : self::DEFAULT_PATTERN;
     }

tests/Doctrine/Tests/Mapping/UnderscoreNamingStrategyTest.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\Mapping;
+
+use Doctrine\ORM\Mapping\UnderscoreNamingStrategy;
+use Doctrine\Tests\VerifyDeprecations;
+use PHPUnit\Framework\TestCase;
+use const CASE_LOWER;
+
+final class UnderscoreNamingStrategyTest extends TestCase
+{
+    use VerifyDeprecations;
+
+    /** @test */
+    public function checkDeprecationMessage() : void
+    {
+        $this->expectDeprecationMessage('Creating Doctrine\ORM\Mapping\UnderscoreNamingStrategy without making it number aware is deprecated and will be removed in Doctrine 3.0.');
+        new UnderscoreNamingStrategy(CASE_LOWER, false);
+    }
+}

tests/Doctrine/Tests/ORM/EntityManagerTest.php

@@ -309,6 +309,15 @@ public function testClearManagerWithNullValue()
         $this->assertFalse($this->_em->contains($entity));
     }
 
+    public function testDeprecatedClearWithArguments() : void
+    {
+        $entity = new Country(456, 'United Kingdom');
+        $this->_em->persist($entity);
+
+        $this->expectDeprecationMessage('Calling Doctrine\ORM\EntityManager::clear() with any arguments to clear specific entities is deprecated and will not be supported in Doctrine 3.0.');
+        $this->_em->clear(Country::class);
+    }
+
     public function testDeprecatedFlushWithArguments() : void
     {
         $entity = new Country(456, 'United Kingdom');