Make SonataEasyExtends optional

UPGRADE-3.x.md

@@ -1,6 +1,14 @@
 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.3 to 3.4
 =======================
 
@@ -13,8 +21,8 @@ UPGRADE FROM 3.1 to 3.2
 
 ### 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).
 
 ### Deprecations

composer.json

@@ -30,9 +30,8 @@
         "sonata-project/cache": "^1.0.3 || ^2.0",
         "sonata-project/cache-bundle": "^2.4.1",
         "sonata-project/datagrid-bundle": "^2.5",
-        "sonata-project/doctrine-extensions": "^1.5",
+        "sonata-project/doctrine-extensions": "^1.8",
         "sonata-project/doctrine-orm-admin-bundle": "^3.19",
-        "sonata-project/easy-extends-bundle": "^2.5",
         "sonata-project/form-extensions": "^0.1.1 || ^1.4",
         "sonata-project/notification-bundle": "^3.8",
         "sonata-project/seo-bundle": "^2.11",

docs/reference/advanced_configuration.rst

@@ -114,11 +114,11 @@ Full configuration options:
                 # Prototype
                 id:                   ~
             class:
-                page:                 Application\Sonata\PageBundle\Entity\Page
-                snapshot:             Application\Sonata\PageBundle\Entity\Snapshot
-                block:                Application\Sonata\PageBundle\Entity\Block
-                site:                 Application\Sonata\PageBundle\Entity\Site
-            direct_publication:   false
+                page: App\Entity\SonataPagePage
+                snapshot: App\Entity\SonataPageSnapshot
+                block: App\Entity\SonataPageBlock
+                site: App\Entity\SonataPageSite
+            direct_publication: false
 
     .. code-block:: yaml
 
@@ -130,7 +130,6 @@ Full configuration options:
                 entity_managers:
                     default:
                         mappings:
-                            ApplicationSonataPageBundle: ~
                             SonataPageBundle: ~
 
 .. _`here`: https://sonata-project.org/bundles/page

docs/reference/installation.rst

@@ -1,19 +1,30 @@
+.. index::
+    single: Installation
+    single: Configuration
+
 Installation
 ============
 
 Prerequisites
 -------------
 
-PHP 7.2 and Symfony >=4.3 are needed to make this bundle work, there are
-also some Sonata dependencies that need to be installed and configured beforehand:
+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.
+
+Required dependencies:
+
+* `SonataAdminBundle <https://sonata-project.org/bundles/admin>`_
+* `SonataBlockBundle_ <https://sonata-project.org/bundles/block>`_
+* `SonataCacheBundle_ <https://sonata-project.org/bundles/cache>`_
+* `SonataSeoBundle_ <https://sonata-project.org/bundles/seo>`_
+* `SonataNotificationBundle_ <https://sonata-project.org/bundles/notification>`_
+
+And the persistence bundle:
 
-    - SonataAdminBundle_
-    - SonataDoctrineORMAdminBundle_
-    - SonataBlockBundle_
-    - SonataCacheBundle_
-    - SonataSeoBundle_
-    - SonataEasyExtendsBundle_
-    - SonataNotificationBundle_
+* `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::
 
@@ -23,52 +34,33 @@ also some Sonata dependencies that need to be installed and configured beforehan
 Enable the Bundle
 -----------------
 
-Add the dependant bundles to the vendor/bundles directory:
+Add ``SonataPageBundle`` via composer::
+
+    composer require sonata-project/page-bundle
 
-.. code-block:: bash
+.. note::
 
-    composer require sonata-project/page-bundle --no-update
-    composer require sonata-project/doctrine-orm-admin-bundle --no-update
+    This will install the SymfonyCmfRoutingBundle_, too.
 
-    # optional when using API
-    composer require friendsofsymfony/rest-bundle  --no-update
-    composer require nelmio/api-doc-bundle  --no-update
+If you want to use the REST API, you also need ``friendsofsymfony/rest-bundle`` and ``nelmio/api-doc-bundle``::
 
-    composer update
+    composer require friendsofsymfony/rest-bundle nelmio/api-doc-bundle
 
-Next, be sure to enable the bundles in your ``bundles.php`` file if they
+Next, be sure to enable the bundles in your ``config/bundles.php`` file if they
 are not already enabled::
 
     // config/bundles.php
 
     return [
         // ...
         Sonata\PageBundle\SonataPageBundle::class => ['all' => true],
-        Sonata\EasyExtendsBundle\SonataEasyExtendsBundle::class => ['all' => true],
     ];
 
 Configuration
--------------
-
-Doctrine Configuration
-~~~~~~~~~~~~~~~~~~~~~~
-
-Add these bundles in the config mapping definition (or enable `auto_mapping`_):
-
-.. code-block:: yaml
-
-    # config/packages/doctrine.yaml
-
-    doctrine:
-        orm:
-            entity_managers:
-                default:
-                    mappings:
-                        ApplicationSonataPageBundle: ~ # only once the ApplicationSonataPageBundle is generated
-                        SonataPageBundle: ~
+=============
 
 CMF Routing Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 ``sonata.page.router`` service must be added to the index of ``cmf_routing.router`` chain router.
 
@@ -99,20 +91,26 @@ Or register ``sonata.page.router`` automatically:
             priority: 150
 
 SonataPageBundle Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 .. code-block:: yaml
 
     # config/packages/sonata_page.yaml
 
     sonata_page:
-        slugify_service:   sonata.core.slugify.cocur # old BC value is sonata.core.slugify.native
+        slugify_service: sonata.core.slugify.cocur # old BC value is sonata.core.slugify.native
         multisite: host
         use_streamed_response: true # set the value to false in debug mode or if the reverse proxy does not handle streamed response
         ignore_route_patterns:
             - ^(.*)admin(.*)   # ignore admin route, ie route containing 'admin'
             - ^_(.*)          # ignore symfony routes
 
+        class:
+            page: App\Entity\SonataPagePage
+            snapshot: App\Entity\SonataPageSnapshot
+            block: App\Entity\SonataPageBlock
+            site: App\Entity\SonataPageSite
+
         ignore_routes:
             - sonata_page_cache_esi
             - sonata_page_cache_ssi
@@ -143,7 +141,7 @@ SonataPageBundle Configuration
             fatal:     [500]    # so you can use the same page for different http errors or specify specific page for each error
 
 SonataAdminBundle Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 .. code-block:: yaml
 
@@ -157,7 +155,7 @@ SonataAdminBundle Configuration
                 - bundles/sonatapage/sonata-page.back.min.css
 
 SonataBlockBundle Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 .. code-block:: yaml
 
@@ -171,7 +169,7 @@ SonataBlockBundle Configuration
     Please you need to use the context ``sonata_page_bundle`` in the SonataBlockBundle to add block into a Page.
 
 Security Configuration
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 .. code-block:: yaml
 
@@ -201,7 +199,7 @@ this logout handler:
                     handlers: ['sonata.page.cms_manager_selector']
 
 Routing Configuration
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 .. code-block:: yaml
 
@@ -215,62 +213,120 @@ Routing Configuration
         resource: '@SonataPageBundle/Resources/config/routing/cache.xml'
         prefix: /
 
-Extend the Bundle
------------------
-
-At this point, the bundle is usable, but not quite ready yet. You need to
-generate the correct entities for the page:
+Doctrine ORM Configuration
+--------------------------
 
-.. code-block:: bash
+And these in the config mapping definition (or enable `auto_mapping`_)::
 
-    bin/console sonata:easy-extends:generate SonataPageBundle --dest=src --namespace_prefix=App
-
-With provided parameters, the files are generated in ``src/Application/Sonata/PageBundle``.
-
-.. note::
-
-    The command will generate domain objects in an ``App\Application`` namespace.
-    So you can point entities' associations to a global and common namespace.
-    This will make Entities sharing easier as your models will allow to
-    point to a global namespace. For instance the page will be
-    ``App\Application\Sonata\PageBundle\Entity\Page``.
-
-Now, add the new ``Application`` Bundle into the ``bundles.php``::
-
-    // config/bundles.php
-
-    return [
-        // ...
-        App\Application\Sonata\PageBundle\ApplicationSonataPageBundle::class => ['all' => true],
-    ];
-
-Configure SonataPageBundle to use the newly generated classes:
+    # config/packages/doctrine.yaml
 
-.. code-block:: yaml
+    doctrine:
+        orm:
+            entity_managers:
+                default:
+                    mappings:
+                        SonataPageBundle: ~
 
-    # config/packages/sonata_page.yaml
+And then create the corresponding entities, ``src/Entity/SonataPageBlock``::
+
+    // src/Entity/SonataPageBlock.php
+
+    use Doctrine\ORM\Mapping as ORM;
+    use Sonata\PageBundle\Entity\BaseBlock;
+
+    /**
+     * @ORM\Entity
+     * @ORM\Table(name="page__block")
+     */
+    class SonataPageBlock extends BaseBlock
+    {
+        /**
+         * @ORM\Id
+         * @ORM\GeneratedValue
+         * @ORM\Column(type="integer")
+         */
+        protected $id;
+    }
+
+``src/Entity/SonataPagePage``::
+
+    // src/Entity/SonataPagePage.php
+
+    use Doctrine\ORM\Mapping as ORM;
+    use Sonata\PageBundle\Entity\BasePage;
+
+    /**
+     * @ORM\Entity
+     * @ORM\Table(name="page__page")
+     */
+    class SonataPagePage extends BasePage
+    {
+        /**
+         * @ORM\Id
+         * @ORM\GeneratedValue
+         * @ORM\Column(type="integer")
+         */
+        protected $id;
+    }
+
+``src/Entity/SonataPageSite``::
+
+    // src/Entity/SonataPageSite.php
+
+    use Doctrine\ORM\Mapping as ORM;
+    use Sonata\PageBundle\Entity\BaseSite;
+
+    /**
+     * @ORM\Entity
+     * @ORM\Table(name="page__site")
+     */
+    class SonataPageSite extends BaseSite
+    {
+        /**
+         * @ORM\Id
+         * @ORM\GeneratedValue
+         * @ORM\Column(type="integer")
+         */
+        protected $id;
+    }
+
+and ``src/Entity/SonataPageSnapshot``::
+
+    // src/Entity/SonataPageSnapshot.php
+
+    use Doctrine\ORM\Mapping as ORM;
+    use Sonata\PageBundle\Entity\BaseSnapshot;
+
+    /**
+     * @ORM\Entity
+     * @ORM\Table(name="page__snapshot")
+     */
+    class SonataPageSnapshot extends BaseSnapshot
+    {
+        /**
+         * @ORM\Id
+         * @ORM\GeneratedValue
+         * @ORM\Column(type="integer")
+         */
+        protected $id;
+    }
+
+The only thing left is to update your schema::
 
-    sonata_page:
-        class:
-            page: App\Application\Sonata\PageBundle\Entity\Page # This is an optional value
-            snapshot: App\Application\Sonata\PageBundle\Entity\Snapshot
-            block: App\Application\Sonata\PageBundle\Entity\Block
-            site: App\Application\Sonata\PageBundle\Entity\Site
+    bin/console doctrine:schema:update --force
 
-The only thing left is to update your schema:
+Next Steps
+----------
 
-.. code-block:: bash
+At this point, your Symfony installation should be fully functional, without errors
+showing up from SonataPageBundle. If, at this point or during the installation,
+you come across any errors, don't panic:
 
-    bin/console doctrine:schema:update --force
+    - Read the error message carefully. Try to find out exactly which bundle is causing the error.
+      Is it SonataPageBundle or one of the dependencies?
+    - Make sure you followed all the instructions correctly, for both SonataPageBundle and its dependencies.
+    - Still no luck? Try checking the project's `open issues on GitHub`_.
 
-.. _SonataAdminBundle: https://sonata-project.org/bundles/admin
-.. _SonataDoctrineORMAdminBundle: https://sonata-project.org/bundles/doctrine-orm-admin
-.. _SonataBlockBundle: https://sonata-project.org/bundles/block
-.. _SonataCacheBundle: https://sonata-project.org/bundles/cache
-.. _SonataSeoBundle: https://sonata-project.org/bundles/seo
-.. _SonataEasyExtendsBundle: https://sonata-project.org/bundles/easy-extends
-.. _SonataNotificationBundle: https://sonata-project.org/bundles/notification
-.. _EasyExtendsBundle: https://sonata-project.org/bundles/easy-extends/master/doc/index.html
+.. _`open issues on GitHub`: https://github.com/sonata-project/SonataPageBundle/issues
 .. _SymfonyCmfRoutingBundle: https://github.com/symfony-cmf/RoutingBundle
-.. _SymfonyCmfRoutingExtraBundle: https://github.com/symfony-cmf/RoutingExtraBundle
 .. _auto_mapping: http://symfony.com/doc/2.0/reference/configuration/doctrine.html#configuration-overview