Merge pull request #7183 from beberlei/Upgrade-Improvements

Improve DBAL migration docs for object, array and json_array type removals.

Author: beberlei

UPGRADE.md

@@ -573,6 +573,22 @@ The following classes and constants have been deprecated:
 
 Use JSON for storing unstructured data.
 
+You can keep the old type behavior by copying (and adapting) the old type
+classes
+([Array](https://github.com/doctrine/dbal/blob/2.13.9/lib/Doctrine/DBAL/Types/ArrayType.php)
+and
+[Object](https://github.com/doctrine/dbal/blob/2.13.9/lib/Doctrine/DBAL/Types/ObjectType.php))
+into your own code- base and re-register them in the TypeRegistry:
+
+```php
+use Doctrine\DBAL\Types\TypeFactory;
+use MyApp\Doctrine\Types\ArrayType;
+use MyApp\Doctrine\Types\ObjectType;
+
+TypeRegistry::register('array', new ArrayType());
+TypeRegistry::register('object', new ObjectType());
+```
+
 ## Deprecated `Driver::getSchemaManager()`.
 
 The `Driver::getSchemaManager()` method has been deprecated. Use `AbstractPlatform::createSchemaManager()` instead.
@@ -1329,9 +1345,49 @@ Please generate UUIDs on the application side (e.g. using [ramsey/uuid](https://
 
 The `Doctrine\DBAL\Driver::getName()` has been removed.
 
+## BC Break: `json_array` type removed
+
+Removed `json_array` type and all associated hacks.
+
+It is recommened to migrate to the `json` type while still being on the ORM 2
+branch. You then need to migrate the database (using migrations or SchemaTool)
+to update both the type and especially remove the `(Dc2Type:json_array)` column
+comment, before you ugprade to DBAL 3.
+
+If you cannot migrate the database or  rely on this type, especially its
+behavior with regard to NULL and empty values, you can copy (adapt) the
+[JsonArrayType
+class](https://github.com/doctrine/dbal/blob/2.13.9/lib/Doctrine/DBAL/Types/JsonArrayType.php)
+into your own codebase and re-regsiter under the name:
+
+```php
+use Doctrine\DBAL\Types\TypeFactory;
+use MyApp\Doctrine\Types\JsonArrayType;
+
+TypeRegistry::register('json_array', new JsonArrayType());
+```
+
+Or if you want to opt into the newer type instead, with its slightly changed null behavior, you can
+register that with:
+
+```php
+use Doctrine\DBAL\Types\TypeFactory;
+use Doctrine\DBAL\Types\JsonType;
+
+TypeRegistry::register('json_array', new JsonType());
+```
+
+In Symfony you can register this type with:
+
+```yml
+doctrine:
+   dbal:
+      types:
+         json_array: "Doctrine\\DBAL\\Types\\JsonType"
+```
+
 ## BC BREAK Removed previously deprecated features
 
- * Removed `json_array` type and all associated hacks.
  * Removed `Connection::TRANSACTION_*` constants.
  * Removed `AbstractPlatform::DATE_INTERVAL_UNIT_*` and `AbstractPlatform::TRIM_*` constants.
  * Removed `AbstractPlatform::getSQLResultCasing()`, `::prefersSequences()` and `::supportsForeignKeyOnUpdate()` methods.