Merge pull request #4 from nucleos/dev

Port FOSUserBundle components

.github/workflows/continuous-integration.yml

@@ -220,4 +220,4 @@ jobs:
         run: composer install --no-interaction --no-progress --no-suggest
 
       - name: "Run mutation tests with pcov and infection/infection"
-        run: vendor/bin/infection --ignore-msi-with-no-mutations --min-covered-msi=67 --min-msi=37
+        run: vendor/bin/infection --ignore-msi-with-no-mutations --min-covered-msi=57 --min-msi=17

composer.json

@@ -18,17 +18,9 @@
     ],
     "require": {
         "php": "^7.3",
-        "ext-json": "*",
-        "ext-mbstring": "*",
-        "doctrine/collections": "^1.6",
-        "doctrine/common": "^2.11",
-        "doctrine/event-manager": "^1.1",
-        "doctrine/persistence": "^1.3",
         "egulias/email-validator": "^2.1.10",
         "nucleos/user-bundle": "dev-master",
-        "paragonie/random_compat": "^1 || ^2 || ^9",
         "symfony/config": "^4.4 || ^5.0",
-        "symfony/console": "^4.4 || ^5.0",
         "symfony/dependency-injection": "^4.4 || ^5.0",
         "symfony/event-dispatcher": "^4.4 || ^5.0",
         "symfony/event-dispatcher-contracts": "^1.0 || ^2.0",
@@ -39,12 +31,8 @@
         "symfony/mailer": "^4.4 || ^5.0",
         "symfony/mime": "^4.4 || ^5.0",
         "symfony/options-resolver": "^4.4 || ^5.0",
-        "symfony/polyfill-mbstring": "^1.13",
         "symfony/routing": "^4.4 || ^5.0",
-        "symfony/security-bundle": "^4.4 || ^5.0",
         "symfony/security-core": "^4.4 || ^5.0",
-        "symfony/security-csrf": "^4.4 || ^5.0",
-        "symfony/security-http": "^4.4 || ^5.0",
         "symfony/translation": "^4.4 || ^5.0",
         "symfony/translation-contracts": "^1.0 || ^2.0",
         "symfony/twig-bridge": "^4.4 || ^5.0",
@@ -53,30 +41,18 @@
         "twig/twig": "^2.4 || ^3.0"
     },
     "conflict": {
-        "doctrine/doctrine-bundle": "<1.12",
-        "doctrine/mongodb": "<1.6",
-        "doctrine/mongodb-odm": "<1.1",
-        "doctrine/mongodb-odm-bundle": "<4.1",
-        "doctrine/orm": "<2.7",
         "symfony/doctrine-bridge": "<4.4"
     },
     "require-dev": {
         "alcaeus/mongo-php-adapter": "^1.1",
         "bamarni/composer-bin-plugin": "^1.3",
         "doctrine/doctrine-bundle": "^1.12 || ^2.0",
-        "doctrine/mongodb": "^1.6",
-        "doctrine/mongodb-odm": "^1.1 || ^2.0",
-        "doctrine/mongodb-odm-bundle": "^4.1",
-        "doctrine/orm": "^2.7",
         "ergebnis/composer-normalize": "^2.0.1",
         "symfony/browser-kit": "^4.4 || ^5.0",
         "symfony/doctrine-bridge": "^4.4 || ^5.0",
         "symfony/yaml": "^4.4 || ^5.0"
     },
     "config": {
-        "platform": {
-            "ext-mongo": "1.6.16"
-        },
         "sort-packages": true
     },
     "extra": {

docs/configuration.rst

@@ -0,0 +1,22 @@
+Configuration reference
+=======================
+
+All available configuration options are listed below with their default values.
+
+.. code-block:: yaml
+
+    nucleos_profile:
+        use_listener:               true
+        use_flash_notifications:    true
+        use_authentication_listener: true
+        profile:
+            form:
+                model:               Nucleos\ProfileBundle\Form\Model\Profile
+        registration:
+            confirmation:
+                from_email:         ~ # Required
+                enabled:            false # change to true for required email confirmation
+            form:
+                model:               Nucleos\ProfileBundle\Form\Model\Registration
+        service:
+            mailer:                 nucleos_profile.mailer.default

docs/events.rst

@@ -0,0 +1,73 @@
+Hooking into the Controllers
+============================
+
+The controllers packaged with the NucleosProfileBundle provide a lot of
+functionality that is sufficient for general use cases. But, you might find
+that you need to extend that functionality and add some logic that suits the
+specific needs of your application.
+
+For this purpose, the controllers are dispatching events in many places in
+their logic. All events can be found in the constants of the
+``Nucleos\ProfileBundle\NucleosProfileEvents`` class.
+
+All controllers follow the same convention: they dispatch a ``SUCCESS`` event
+when the form is valid before saving the user, and a ``COMPLETED`` event when
+it is done. Thus, all ``SUCCESS`` events allow you to set a response if you
+don't want the default redirection. And all ``COMPLETED`` events give you access
+to the response before it is returned.
+
+Controllers with a form also dispatch an ``INITIALIZE`` event after the entity is
+fetched, but before the form is created.
+
+For instance, this listener will change the redirection after the password
+resetting to go to the homepage.
+
+.. code-block:: php-annotations
+
+    // src/App/EventListener/ProfileEditingListener.php
+    namespace App\EventListener;
+
+    use Nucleos\ProfileBundle\Event\FormEvent;
+    use Nucleos\ProfileBundle\NucleosProfileEvents;
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpFoundation\RedirectResponse;
+    use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+
+    /**
+     * Listener responsible to change the redirection at the end of the profile editing
+     */
+    class ProfileEditingListener implements EventSubscriberInterface
+    {
+        private $router;
+
+        public function __construct(UrlGeneratorInterface $router)
+        {
+            $this->router = $router;
+        }
+
+        public static function getSubscribedEvents(): array
+        {
+            return [
+                NucleosProfileEvents::PROFILE_EDIT_SUCCESS => 'onProfileEditingSuccess',
+            ];
+        }
+
+        public function onProfileEditingSuccess(FormEvent $event): void
+        {
+            $url = $this->router->generate('homepage');
+
+            $event->setResponse(new RedirectResponse($url));
+        }
+    }
+
+You can then register this listener:
+
+.. code-block:: yaml
+
+    # config/services.yaml
+    services:
+        app.password_resetting:
+            class: App\EventListener\ProfileEditingListener
+            arguments: ['@router']
+            tags:
+                - { name: kernel.event_subscriber }

docs/index.rst

@@ -1,2 +1,22 @@
-NucleosProfileundle
-===================
+NucleosProfileBundle
+====================
+
+This is an extension for the basic user profile brought with the `NucleosUserBundle`_.
+
+The NucleosProfileBundle builds on top of this to make it quick
+and easy to open up a registration form and let the user to change the profile.
+
+The following documents are available:
+
+.. toctree::
+    :maxdepth: 1
+
+    installation
+    events
+    mailing
+    routing
+    configuration
+    migrate_from_fos
+
+
+.. _NucleosUserBundle: https://github.com/nucleos/NucleosUserBundle/

docs/installation.rst

@@ -0,0 +1,89 @@
+Install the bundle
+==================
+
+Prerequisites
+-------------
+
+You need to configure the NucleosUserBundle first, check `NucleosUserBundle documentation`_.
+
+Translations
+~~~~~~~~~~~~
+
+If you wish to use default texts provided in this bundle, you have to make
+sure you have translator enabled in your config.
+
+.. code-block:: yaml
+
+    # config/packages/framework.yaml
+    framework:
+        translator: ~
+
+For more information about translations, check `Symfony documentation`_.
+
+Installation
+------------
+
+1. Download NucleosProfileBundle using composer
+2. Enable the Bundle
+3. Configure the NucleosProfileBundle
+4. Import NucleosProfileBundle routing
+
+Step 1: Download NucleosProfileBundle using composer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Require the bundle with composer:
+
+.. code-block:: bash
+
+    $ composer require nucleos/profile-bundle
+
+Step 2: Enable the bundle
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enable the bundle in the kernel:
+
+.. code-block:: php-annotations
+
+    // config/bundles.php
+    return [
+        // ...
+        Nucleos\UserBundle\NucleosProfileBundle::class => ['all' => true],
+        // ...
+    ]
+
+Step 3: Configure the NucleosProfileBundle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add the following configuration to your ``config/packages/nucleos_profile.yaml``.
+
+.. code-block:: yaml
+
+    # config/packages/nucleos_profile.yaml
+    nucleos_profile:
+        registration:
+            confirmation:
+                from_email:  "%mailer_user%"
+
+
+Step 4: Import NucleosProfileBundle routing files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that you have activated and configured the bundle, all that is left to do is
+import the NucleosProfileBundle routing files.
+
+By importing the routing files you will have ready made pages for things such as
+logging in, creating users, etc.
+
+.. code-block:: yaml
+
+    # config/routes/nucleos_profile.yaml
+    nucleos_profile:
+        resource: "@NucleosProfileBundle/src/Resources/config/routing/all.xml"
+
+.. note::
+
+    In order to use the built-in email functionality (confirmation of the account,
+    resetting of the password), you must activate and configure the SwiftmailerBundle.
+
+.. _Symfony documentation: https://symfony.com/doc/current/book/translation.html
+.. _NucleosUserBundle documentation: https://nucleosuserbundle.readthedocs.io

docs/mailing.rst

@@ -0,0 +1,93 @@
+Sending E-Mails
+===============
+
+The NucleosProfileBundle has built-in support for sending emails in two different
+instances.
+
+Registration Confirmation
+-------------------------
+
+The first is when a new user registers and the bundle is configured
+to require email confirmation before the user registration is complete.
+The email that is sent to the new user contains a link that, when visited,
+will verify the registration and enable the user account.
+
+Requiring email confirmation for a new account is turned off by default.
+To enable it, update your configuration as follows:
+
+.. code-block:: yaml
+
+    # config/packages/nucleos_profile.yaml
+    nucleos_profile:
+        registration:
+            confirmation:
+                enabled: true
+
+Default Mailer Implementations
+------------------------------
+
+The bundle comes with three mailer implementations. They are listed below
+by service id:
+
+- ``nucleos_profile.mailer.default`` is the default implementation, and uses symfony mailer to send emails.
+- ``nucleos_profile.mailer.noop`` is a mailer implementation which performs no operation, so no emails are sent.
+
+Configuring the Sender Email Address
+------------------------------------
+
+The NucleosProfileBundle default mailer allows you to configure the sender email address
+of the emails sent out by the bundle.
+
+To configure the sender email address for registration emails sent out by the bundle,
+update your ``nucleos_profile`` config as follows:
+
+.. code-block:: yaml
+
+    # config/packages/nucleos_profile.yaml
+    nucleos_profile:
+        # ...
+        registration:
+            confirmation:
+                from_email:   resetting@example.com
+
+Using A Custom Mailer
+---------------------
+
+The default mailer service used by NucleosProfileBundle relies on the symfony mailer
+library to send mail. If you would like to use a different library to send
+emails or change the content of the email you
+may do so by defining your own service.
+
+First you must create a new class which implements ``Nucleos\UserBundle\Mailer\MailerInterface``
+which is listed below:
+
+.. code-block:: php-annotations
+
+    namespace Nucleos\UserBundle\Mailer;
+
+    use Nucleos\UserBundle\Model\UserInterface;
+
+    interface MailerInterface
+    {
+
+        /**
+         * Send an email to a user to confirm the password reset
+         *
+         * @param UserInterface $user
+         */
+        function sendConfirmationEmailMessage(UserInterface $user): void;
+    }
+
+After you have implemented your custom mailer class and defined it as a service,
+you must update your bundle configuration so that NucleosProfileBundle will use it.
+Set the ``mailer`` configuration parameter under the ``service`` section.
+An example is listed below.
+
+.. code-block:: yaml
+
+    # config/packages/nucleos_profile.yaml
+    nucleos_profile:
+        # ...
+        service:
+            mailer: app.custom_nucleos_profile_mailer
+

docs/migrate_from_fos.rst

@@ -0,0 +1,4 @@
+Migrate from FOSUserBundle
+==========================
+
+Tbd.

docs/routing.rst

@@ -0,0 +1,19 @@
+Advanced routing configuration
+==============================
+
+By default, the routing file ``@NucleosProfileBundle/Resources/config/routing/all.xml`` imports
+all the routing files and enables all the routes.
+In the case you want to enable or disable the different available routes, use the
+single routing configuration files.
+
+.. code-block:: yaml
+
+    # config/routes/nucleos_profile.yaml
+    nucleos_profile_profile:
+        resource: "@NucleosProfileBundle/Resources/config/routing/profile.xml"
+        prefix: /profile
+
+    nucleos_profile_change_registration:
+        resource: "@NucleosProfileBundle/Resources/config/routing/registration.xml"
+        prefix: /registration
+