Make easy extends optional

UPGRADE-3.x.md

@@ -1,12 +1,20 @@
 UPGRADE 3.x
 ===========
 
+UPGRADE FROM 3.x to 3.x
+=======================
+
+### SonataEasyExtends is deprecated
+
+Registering `SonataEasyExtendsBundle` bundle is deprecated, it SHOULD NOT be registered.
+Register `SonataDoctrineBundle` bundle instead.
+
 UPGRADE FROM 3.2 to 3.3
 =======================
 
 ### AMQP
 
-You might face some issues (though we tried to keep everything BC) if you are extending `AMQPBackend`, `AMQPBackendDispatcher` or `AMQPMessageIterator` classes 
+You might face some issues (though we tried to keep everything BC) if you are extending `AMQPBackend`, `AMQPBackendDispatcher` or `AMQPMessageIterator` classes
 or rely on their `__construct` method signature.
 
 If you want to migrate to another amqp interop compatible transport, say `enqueue/amqp-ext`, the BC layer want work and the exception is thrown.
@@ -16,6 +24,6 @@ UPGRADE FROM 3.0 to 3.1
 
 ### Tests
 
-All files under the ``Tests`` directory are now correctly handled as internal test classes. 
-You can't extend them anymore, because they are only loaded when running internal tests. 
+All files under the ``Tests`` directory are now correctly handled as internal test classes.
+You can't extend them anymore, because they are only loaded when running internal tests.
 More information can be found in the [composer docs](https://getcomposer.org/doc/04-schema.md#autoload-dev).

composer.json

@@ -24,8 +24,9 @@
         "php": "^7.2",
         "doctrine/doctrine-bundle": "^1.12 || ^2.0",
         "doctrine/persistence": "^1.3",
+        "laminas/laminas-diagnostics": "^1.6",
         "sonata-project/datagrid-bundle": "^2.5",
-        "sonata-project/doctrine-extensions": "^1.5",
+        "sonata-project/doctrine-extensions": "^1.8",
         "sonata-project/form-extensions": "^0.1 || ^1.4",
         "symfony/config": "^4.4",
         "symfony/console": "^4.4",
@@ -36,8 +37,7 @@
         "symfony/form": "^4.4",
         "symfony/http-foundation": "^4.4",
         "symfony/http-kernel": "^4.4",
-        "symfony/security-core": "^4.4",
-        "zendframework/zenddiagnostics": "^1.0"
+        "symfony/security-core": "^4.4"
     },
     "conflict": {
         "friendsofsymfony/rest-bundle": "<2.1",
@@ -51,6 +51,8 @@
         "guzzlehttp/guzzle": "^3.8",
         "jms/serializer-bundle": "^2.0 || ^3.0",
         "liip/monitor-bundle": "^2.6",
+        "matthiasnoback/symfony-config-test": "^4.0",
+        "matthiasnoback/symfony-dependency-injection-test": "^4.0",
         "nelmio/api-doc-bundle": "^2.13",
         "sensio/framework-extra-bundle": "^5.5",
         "sonata-project/doctrine-orm-admin-bundle": "^3.19",

docs/reference/advanced_configuration.rst

@@ -90,15 +90,15 @@ Full configuration options:
             # Iterate event is thrown on each command iteration
             #
             # Iteration listener class must implement Sonata\NotificationBundle\Event\IterationListener
-            iteration_listeners:  []
+            iteration_listeners: []
             class:
-                message:              App\Entity\Message
+                message: App\Entity\SonataNotificationMessage
             admin:
-                enabled:              true
+                enabled: true
                 message:
-                    class:                Sonata\NotificationBundle\Admin\MessageAdmin
-                    controller:           'SonataNotificationBundle:MessageAdmin'
-                    translation:          SonataNotificationBundle
+                    class: Sonata\NotificationBundle\Admin\MessageAdmin
+                    controller: 'SonataNotificationBundle:MessageAdmin'
+                    translation: SonataNotificationBundle
 
     .. code-block:: yaml
 

docs/reference/installation.rst

@@ -1,25 +1,60 @@
+.. index::
+    single: Installation
+    single: Configuration
+
 Installation
 ============
 
-.. code-block:: bash
+Prerequisites
+-------------
+
+PHP ^7.2 and Symfony ^4.4 are needed to make this bundle work, there are
+also some Sonata dependencies that need to be installed and configured beforehand.
+
+Optional dependencies:
+
+* `SonataAdminBundle <https://sonata-project.org/bundles/admin>`_
+
+And the persistence bundle (currently, not all the implementations of the Sonata persistence bundles are available):
+
+* `SonataDoctrineOrmAdminBundle <https://sonata-project.org/bundles/doctrine-orm-admin>`_
+
+Follow also their configuration step; you will find everything you need in
+their own installation chapter.
+
+.. note::
+
+    If a dependency is already installed somewhere in your project or in
+    another dependency, you won't need to install it again.
+
+Install Symfony Flex packs
+--------------------------
+
+With this method you can directly setup all the entities required to make this bundle work
+with the different persistence bundles supported.
+
+If you picked ``SonataDoctrineOrmAdminBundle``, install the Sonata Media ORM pack::
+
+    composer require sonata-project/notification-orm-pack
+
+Install without Symfony Flex packs
+----------------------------------
+
+Add ``SonataNotificationBundle`` via composer::
 
     composer require sonata-project/notification-bundle
 
-Or if you wish to use doctrine backend, execute ``composer require sonata-project/notification-orm-pack``.
-Symfony Flex will download recipes and install all necessary configuration
-files and an entity class for notification messages.
+If you want to use the REST API, you also need ``friendsofsymfony/rest-bundle`` and ``nelmio/api-doc-bundle``::
 
-Next, add the dependent bundles:
+    composer require friendsofsymfony/rest-bundle nelmio/api-doc-bundle
 
-.. code-block:: bash
+There are other optional dependencies::
 
-    composer require enqueue/amqp-lib --no-update # optional
-    composer require liip/monitor-bundle --no-update # optional
-    composer require friendsofsymfony/rest-bundle  --no-update # optional when using api with doctrine backend
-    composer require nelmio/api-doc-bundle  --no-update # optional when using api with doctrine backend
-    composer update
+    composer require enqueue/amqp-lib
+    composer require liip/monitor-bundle
 
-Now, add the new ``SonataNotificationBundle`` Bundle to ``bundles.php`` file::
+Next, be sure to enable the bundles in your ``config/bundles.php`` file if they
+are not already enabled::
 
     // config/bundles.php
 
@@ -29,10 +64,10 @@ Now, add the new ``SonataNotificationBundle`` Bundle to ``bundles.php`` file::
     ];
 
 Configuration
--------------
+=============
 
 SonataNotificationBundle Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
 
 To use the ``SonataNotificationBundle``, add the following lines to your application configuration
 file.
@@ -61,12 +96,10 @@ You can disable the admin if you don't need it :
         admin:
             enabled: false
 
-Doctrine Configuration
-~~~~~~~~~~~~~~~~~~~~~~
+Doctrine ORM Configuration
+--------------------------
 
-Add this bundle in the config mapping definition (or enable `auto_mapping`_):
-
-.. code-block:: yaml
+Add the bundle in the config mapping definition (or enable `auto_mapping`_)::
 
     # config/packages/doctrine.yaml
 
@@ -77,8 +110,42 @@ Add this bundle in the config mapping definition (or enable `auto_mapping`_):
                     mappings:
                         SonataNotificationBundle: ~
 
-        dbal:
-            types:
-                json: Sonata\Doctrine\Types\JsonType
+And then create the corresponding entity, ``src/Entity/SonataNotificationMessage``::
+
+    // src/Entity/SonataNotificationMessage.php
+
+    use Doctrine\ORM\Mapping as ORM;
+    use Sonata\NotificationBundle\Entity\BaseMessage;
+
+    /**
+     * @ORM\Entity
+     * @ORM\Table(name="notification__message")
+     */
+    class SonataNotificationMessage extends BaseMessage
+    {
+        /**
+         * @ORM\Id
+         * @ORM\GeneratedValue
+         * @ORM\Column(type="integer")
+         */
+        protected $id;
+    }
+
+The only thing left is to update your schema::
+
+    bin/console doctrine:schema:update --force
+
+Next Steps
+----------
+
+At this point, your Symfony installation should be fully functional, without errors
+showing up from SonataNotificationBundle. If, at this point or during the installation,
+you come across any errors, don't panic:
+
+    - Read the error message carefully. Try to find out exactly which bundle is causing the error.
+      Is it SonataNotificationBundle or one of the dependencies?
+    - Make sure you followed all the instructions correctly, for both SonataNotificationBundle and its dependencies.
+    - Still no luck? Try checking the project's `open issues on GitHub`_.
 
-.. _`auto_mapping`: http://symfony.com/doc/2.0/reference/configuration/doctrine.html#configuration-overview
+.. _`open issues on GitHub`: https://github.com/sonata-project/SonataNotificationBundle/issues
+.. _`auto_mapping`: http://symfony.com/doc/4.4/reference/configuration/doctrine.html#configuration-overviews

src/Backend/AMQPBackend.php

@@ -19,15 +19,15 @@
 use Interop\Amqp\AmqpQueue;
 use Interop\Amqp\AmqpTopic;
 use Interop\Amqp\Impl\AmqpBind;
+use Laminas\Diagnostics\Result\Failure;
+use Laminas\Diagnostics\Result\Success;
 use PhpAmqpLib\Channel\AMQPChannel;
 use Sonata\NotificationBundle\Consumer\ConsumerEvent;
 use Sonata\NotificationBundle\Exception\HandlingException;
 use Sonata\NotificationBundle\Iterator\AMQPMessageIterator;
 use Sonata\NotificationBundle\Model\Message;
 use Sonata\NotificationBundle\Model\MessageInterface;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
-use ZendDiagnostics\Result\Failure;
-use ZendDiagnostics\Result\Success;
 
 /**
  * Consumer side of the rabbitMQ backend.

src/Backend/AMQPBackendDispatcher.php

@@ -18,13 +18,13 @@
 use Guzzle\Http\Client as GuzzleClient;
 use Interop\Amqp\AmqpConnectionFactory;
 use Interop\Amqp\AmqpContext;
+use Laminas\Diagnostics\Result\Failure;
+use Laminas\Diagnostics\Result\Success;
 use PhpAmqpLib\Channel\AMQPChannel;
 use PhpAmqpLib\Connection\AMQPConnection;
 use Sonata\NotificationBundle\Exception\BackendNotFoundException;
 use Sonata\NotificationBundle\Model\MessageInterface;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
-use ZendDiagnostics\Result\Failure;
-use ZendDiagnostics\Result\Success;
 
 /**
  * Producer side of the rabbitmq backend.

src/Backend/BackendHealthCheck.php

@@ -13,7 +13,7 @@
 
 namespace Sonata\NotificationBundle\Backend;
 
-use ZendDiagnostics\Check\AbstractCheck;
+use Laminas\Diagnostics\Check\AbstractCheck;
 
 class BackendHealthCheck extends AbstractCheck
 {

src/Backend/BackendInterface.php

@@ -13,9 +13,9 @@
 
 namespace Sonata\NotificationBundle\Backend;
 
+use Laminas\Diagnostics\Result\ResultInterface;
 use Sonata\NotificationBundle\Model\MessageInterface;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
-use ZendDiagnostics\Result\ResultInterface;
 
 interface BackendInterface
 {

src/Backend/MessageManagerBackend.php

@@ -13,15 +13,15 @@
 
 namespace Sonata\NotificationBundle\Backend;
 
+use Laminas\Diagnostics\Result\Failure;
+use Laminas\Diagnostics\Result\Success;
+use Laminas\Diagnostics\Result\Warning;
 use Sonata\NotificationBundle\Consumer\ConsumerEvent;
 use Sonata\NotificationBundle\Exception\HandlingException;
 use Sonata\NotificationBundle\Iterator\MessageManagerMessageIterator;
 use Sonata\NotificationBundle\Model\MessageInterface;
 use Sonata\NotificationBundle\Model\MessageManagerInterface;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
-use ZendDiagnostics\Result\Failure;
-use ZendDiagnostics\Result\Success;
-use ZendDiagnostics\Result\Warning;
 
 class MessageManagerBackend implements BackendInterface
 {

src/Backend/MessageManagerBackendDispatcher.php

@@ -13,10 +13,10 @@
 
 namespace Sonata\NotificationBundle\Backend;
 
+use Laminas\Diagnostics\Result\Success;
 use Sonata\NotificationBundle\Model\MessageInterface;
 use Sonata\NotificationBundle\Model\MessageManagerInterface;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
-use ZendDiagnostics\Result\Success;
 
 /**
  * Producer side of the doctrine backend.

src/Backend/PostponeRuntimeBackend.php

@@ -13,11 +13,11 @@
 
 namespace Sonata\NotificationBundle\Backend;
 
+use Laminas\Diagnostics\Result\Success;
 use Sonata\NotificationBundle\Iterator\IteratorProxyMessageIterator;
 use Sonata\NotificationBundle\Model\MessageInterface;
 use Symfony\Component\EventDispatcher\Event;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
-use ZendDiagnostics\Result\Success;
 
 /**
  * This backend postpones the handling of messages to a registered event.

src/Backend/RuntimeBackend.php

@@ -13,12 +13,12 @@
 
 namespace Sonata\NotificationBundle\Backend;
 
+use Laminas\Diagnostics\Result\Success;
 use Sonata\NotificationBundle\Consumer\ConsumerEvent;
 use Sonata\NotificationBundle\Exception\HandlingException;
 use Sonata\NotificationBundle\Model\Message;
 use Sonata\NotificationBundle\Model\MessageInterface;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
-use ZendDiagnostics\Result\Success;
 
 class RuntimeBackend implements BackendInterface
 {