memberpoint/wos-users-bundle

There is no license information available for the latest version (v2.57) of this package.

Installs: 17

Dependents: 8

Suggesters: 0

Type:symfony-bundle

v2.57 2021-12-02 02:29 UTC

README

The MemberPoint Whole-Of-Sports (WOS) UsersBundle provides functionality for the management of user accounts.

For instructions on how to use the bundle, refer to the bundle's documentation.

Installation

These instructions assume the consuming application uses Symfony Flex.

Add the following repository to the application's composer.json file:

"repositories": [
    {
        "type": "composer",
        "url": "https://code.int.savagebull.com.au"
    }
]

Open a command console, enter the project directory, and execute:

$ composer require memberpoint/wos-users-bundle

Post-Installation

This section describes post-installation steps required for the bundle to work correctly. Steps are divided into the following sections:

Mail

For this bundle to be fully operational, the Swift Mailer service needs to be configured. To aid in development, Mailtrap is recommended as an SMTP mail server.

A sample .env file using Mailtrap is as follows:

MAILER_URL=smtp://smtp.mailtrap.io:2525?auth_mode=cram-md5&username=<foo>&password=<bar>

Ensure an application-wide sender address is also configured:

# config/packages/wos_common.yaml
wos_common:
  mail:
    sender_address: <an-email-address>

For more information on WOS common configuration options, refer to the MemberPoint Whole-Of-Sports (WOS) CommonBundle documentation.

National Identification Numbers (NINs)

National Identification Numbers (or NINs for short) are unique numbers sequentially assigned to user accounts on confirmation.

For this bundle to be fully operational, the NIN sequence must first be initialised using the supplied wos:users:ninseq-init command:

$ php bin/console wos:users:ninseq-init
$ php bin/console wos:users:ninseq-init -s 3000

The first command above initialises the NIN sequence starting at 1; the second initialises the NIN sequence starting at 3000.

Failure to initialise the NIN sequence may cause the bundle to error unexpectedly.

Parameters

To ensure commands provided by this bundle operate correctly, configure a global request context, like so:

# config/services.yaml
parameters:
  router.request_context.host: example.org
  router.request_context.scheme: https
  router.request_context.base_url: /my/path

Persistence

This bundle relies on Doctrine for persistence. After installing this bundle, ensure a connection to a database is correctly configured before executing:

$ php bin/console doctrine:schema:update --force

Routes

This bundle defines several routes used in conjunction with authentication and commands. For this bundle to work correctly, import these routes into the main application's routing configuration:

# config/routes.yaml
wos_users_security:
  resource: '@WOSUsersBundle/Resources/config/routing-security.yaml'
  prefix: /
wos_users_general:
  resource: '@WOSUsersBundle/Resources/config/routing-general.yaml'
  prefix: /accounts

This bundle defines a collection of routes that serve as JSON API-endpoints. If the consuming application wishes to expose these endpoints, be sure to import them into the application's routing configuration:

# config/routes.yaml
wos_users_api:
  resource: '@WOSUsersBundle/Resources/config/routing-api.yaml'
  prefix: /api

Security

This bundle provides JSON Web Token (JWT) authentication functionality. To use this functionality, SSH keys first need to be generated.

To generate the necessary SSH keys, open a command console, enter the project directory, and execute:

$ mkdir config/jwt
$ openssl genrsa -out config/jwt/private.pem -aes256 4096
$ openssl rsa -pubout -in config/jwt/private.pem -out config/jwt/public.pem

If the first openssl command forces you to input a pass-phrase, use following to get the private key decrypted:

$ openssl rsa -in config/jwt/private.pem -out config/jwt/private2.pem
$ mv config/jwt/private.pem config/jwt/private.pem-back
$ mv config/jwt/private2.pem config/jwt/private.pem

Generating the necessary SSH keys is enough for the bundle to start enforcing security and issuing JWT authentication tokens (see instructions on how to use the bundle).

However, a large part of the JWT authentication functionality provided by this bundle relies on LexikJWTAuthenticationBundle. So if finer-grained configuration is required, refer to LexikJWTAuthenticationBundle's configuration reference.

Unit Testing

Ensure the bundle has all development dependencies available, then open a command console, enter the project directory, and execute:

$ vendor/bin/phpunit --testdox --coverage-text

Integration Testing

The UsersBundle provides fixtures for loading "fake" sets of data into a database to help perform integration testing.

Ensure the Fixtures bundle and the Faker library are available to the testing application:

$ composer require --dev doctrine/doctrine-fixtures-bundle
$ composer require --dev fzaninotto/faker

Then execute the following to load the fixtures:

$ php bin/console doctrine:fixtures:load

Development controller

In addition to fixtures, the UsersBundle provides a development controller with methods to help with integration testing. The development controller is only available in the 'dev' and 'test' environments, and to make the controller accessible, its routes must be imported:

# config/routes/dev/wos_users.yaml
memberpoint_wos_users:
  resource: '@WOSUsersBundle/Resources/config/dev/routing.yaml'
  prefix: /_wos_users

Among the methods provided by the development controller is the ability to set a user account as the current session user. For more information about the devlopment controller methods, refer to the controller directly.