dev: Reorganize and document the env files

.env

@@ -1,32 +1,54 @@
 # This file defines a list of environment variables used to configure Bileto.
-# PLEASE DON'T CHANGE THE VALUES OF THIS FILE! They are used by the development environment.
+#
+# PLEASE DON'T CHANGE THE VALUES OF THIS FILE! They are used as default values.
+# Any change in this file would be deleted at the next update.
+#
 # To configure Bileto in production, copy the file env.sample as .env.local instead.
 
-APP_ENV=dev
-APP_SECRET=97cb420d0d43c4c786c51225db0b6018
-APP_BASE_URL=http://localhost:8000
+####################################
+# Configuration of the application #
+####################################
+APP_ENV="dev"
+APP_SECRET="change-me"
+APP_BASE_URL=""
+APP_DEFAULT_LOCALE="en_GB"
 
-DATABASE_URL="postgresql://postgres:postgres@pgsql:5432/bileto?serverVersion=13&charset=utf8"
-# DATABASE_URL="mysql://root:mariadb@mariadb:3306/bileto?serverVersion=10.5.27-MariaDB"
+#################################
+# Configuration of the database #
+#################################
+DATABASE_URL=""
 
-MAILER_DSN=smtp://support%40example.com:secret@mailserver:3025
-MAILER_FROM=[email protected]
+########################################
+# Configuration of the SMTP mailserver #
+########################################
+MAILER_DSN="null://null"
+MAILER_FROM="[email protected]"
 
-MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0
+#####################################
+# Configuration of the async system #
+#####################################
+MESSENGER_TRANSPORT_DSN="doctrine://default?auto_setup=0"
 
+###########################
+# Configuration of Sentry #
+###########################
+SENTRY_DSN=""
 SENTRY_SEND_DEFAULT_PII=false
 
+#########################
+# Configuration of LDAP #
+#########################
 LDAP_ENABLED=false
-LDAP_HOST="ldap"
-LDAP_PORT=1389
+LDAP_HOST="localhost"
+LDAP_PORT=636
 LDAP_VERSION=3
-LDAP_ENCRYPTION="none"
+LDAP_ENCRYPTION="ssl"
 LDAP_BASE_DN="ou=users,dc=example,dc=com"
 LDAP_ADMIN_DN="cn=admin,dc=example,dc=com"
 LDAP_ADMIN_PASSWORD="secret"
 LDAP_USERS_DN="cn={user_identifier},ou=users,dc=example,dc=com"
 LDAP_QUERY_LIST_USERS="(cn=*)"
 LDAP_QUERY_SEARCH_USER="(cn={user_identifier})"
-LDAP_FIELD_IDENTIFIER=cn
-LDAP_FIELD_EMAIL=mail
-LDAP_FIELD_FULLNAME=displayName
+LDAP_FIELD_IDENTIFIER="cn"
+LDAP_FIELD_EMAIL="mail"
+LDAP_FIELD_FULLNAME="displayName"

.env.dev

@@ -0,0 +1,30 @@
+# This file defines a list of environment variables used to configure Bileto.
+#
+# These values are used in the development environment.
+#
+# To configure Bileto in development, create a .env.dev.local file instead.
+
+####################################
+# Configuration of the application #
+####################################
+APP_SECRET="97cb420d0d43c4c786c51225db0b6018"
+APP_BASE_URL="http://localhost:8000"
+
+#################################
+# Configuration of the database #
+#################################
+DATABASE_URL="postgresql://postgres:postgres@pgsql:5432/bileto?serverVersion=12&charset=utf8"
+#DATABASE_URL="mysql://root:mariadb@mariadb:3306/bileto?serverVersion=10.4.29-MariaDB"
+
+########################################
+# Configuration of the SMTP mailserver #
+########################################
+MAILER_DSN="smtp://support%40example.com:secret@mailserver:3025"
+
+#########################
+# Configuration of LDAP #
+#########################
+LDAP_ENABLED=true
+LDAP_HOST="ldap"
+LDAP_PORT=1389
+LDAP_ENCRYPTION="none"

.env.test

@@ -1,10 +1,40 @@
-LDAP_ENABLED=true
-APP_UPLOADS_DIRECTORY=/tmp/bileto/uploads
+# This file defines a list of environment variables used to configure Bileto.
+#
+# These values are used in the test environment.
+#
+# To configure Bileto in production, copy the file env.sample as .env.local instead.
 
-KERNEL_CLASS='App\Kernel'
+####################################
+# Configuration of the application #
+####################################
 APP_SECRET='$ecretf0rt3st'
-MAILER_DSN=null://null
-MESSENGER_TRANSPORT_DSN=sync://
+APP_BASE_URL="http://localhost:8000"
+APP_UPLOADS_DIRECTORY="/tmp/bileto/uploads"
+
+#################################
+# Configuration of the database #
+#################################
+DATABASE_URL="postgresql://postgres:postgres@pgsql:5432/bileto?serverVersion=12&charset=utf8"
+
+#####################################
+# Configuration of the async system #
+#####################################
+MESSENGER_TRANSPORT_DSN="sync://"
+
+#########################
+# Configuration of LDAP #
+#########################
+LDAP_ENABLED=true
+LDAP_HOST="ldap"
+LDAP_PORT=1389
+LDAP_ENCRYPTION="none"
+
+###########################################
+# Configuration specific to Symfony tests #
+###########################################
+KERNEL_CLASS="App\Kernel"
+
 SYMFONY_DEPRECATIONS_HELPER=999999
-PANTHER_APP_ENV=panther
-PANTHER_ERROR_SCREENSHOT_DIR=./var/error-screenshots
+
+PANTHER_APP_ENV="panther"
+PANTHER_ERROR_SCREENSHOT_DIR="./var/error-screenshots"

config/packages/sentry.yaml

@@ -4,7 +4,7 @@
 
 when@prod:
     sentry:
-        dsn: '%env(string:default::SENTRY_DSN)%'
+        dsn: '%env(string:SENTRY_DSN)%'
         register_error_listener: false
         register_error_handler: false
         options:

docs/developers/README.md

@@ -8,6 +8,7 @@
 Dedicated to the backend:
 
 - [Declaring a new Entity](/docs/developers/entity.md)
+- [Managing environment files](/docs/developers/environment-files.md)
 - [Creating a User](/docs/developers/create-user.md)
 - [Encrypting data](/docs/developers/encryptor.md)
 - [Sorting the entities](/docs/developers/sorters.md)

docs/developers/environment-files.md

@@ -0,0 +1,54 @@
+# Managing environment files
+
+Bileto is configured through environment files (e.g. `.env`).
+An environment file declares a bunch of environment variables which are then used in the application.
+
+Learn more about environment files in [the Symfony documentation.](https://symfony.com/doc/current/configuration.html#configuration-based-on-environment-variables)
+
+## Environment files
+
+Bileto provides several environment files:
+
+- [`.env`](/.env): this is the file where the default values are declared. These values are used in all the environments.
+- [`.env.dev`](/.env.dev): this file overrides the variables for the development environment.
+- [`.env.test`](/.env.test): this file overrides the variables for the test environment.
+- [`env.sample`](/env.sample): this file is not directly used by Bileto, but it must be copied as `.env.local`. It is then adapted to the need of the administrator or developer.
+
+## How to add an environment variable
+
+When you need to add a new configuration option, you'll have to declare a new environment variable.
+
+First, add the variable with an understandable value to the `env.sample` file.
+The variable must be documented with a comment.
+It must be placed in the correct section (e.g. "Configuraton of the application").
+If the value is a string, please always put it in double quotes as a good practice.
+
+Always comment the variable itself in this file, unless it is absolutely required that the administrator set it.
+In this case, you must also add a note to the "Breaking changes" section of [the changelog](/CHANGELOG.md).
+
+Then, add a default value to the `.env` file (unless it can be null).
+We should consider that administrators will forget to set this variable in production, so it's important that this value is suitable for production.
+
+If necessary (and only if necessary), declare the variable in the `.env.dev` and `.env.test` files.
+
+You don't need to duplicate the comment in the `.env*` files as it would be harder to maintain if it should be changed in the `env.sample` file.
+However, please always include the environment sections in order to ease the read of these files.
+
+## How to use an environment variable
+
+Once declared, you can use the variable either in the Symfony configuration (ie. under the [`config/` folder](/config), or directly in a service:
+
+```php
+use Symfony\Component\DependencyInjection\Attribute\Autowire;
+
+class MyService
+{
+    public function __construct(
+        #[Autowire(env: 'APP_MY_VARIABLE')]
+        private string $myVariable,
+    ) {
+    }
+}
+```
+
+You can use the [Symfony environment variable processors](https://symfony.com/doc/current/configuration/env_var_processors.html) to cast the value of the variable from a string to another type.

docs/developers/setup.md

@@ -44,7 +44,8 @@ Open [localhost:8000](http://localhost:8000) and login with one of the following
 
 - `[email protected]` / `secret` (super-admin and technician for all the organizations)
 - `[email protected]` / `secret` (salesman for all the organizations)
-- `[email protected]` / `secret` (user in the “Friendly Coop” organization)
+- `charlie` / `secret` (LDAP user, in the “Friendly Coop” organization)
+- `dominique` / `secret` (LDAP user, in the “Probesys” organization)
 
 A note about the `make` commands: they might feel magic, but they are not!
 They are just shortcuts for common commands.
@@ -53,32 +54,26 @@ They are hopefully easily readable by newcomers.
 
 ## Use MariaDB
 
-By default, `make docker-start` starts a PostgreSQL database.
-If you want to use MariaDB, just pass the `DATABASE` variable to the command:
-
-```console
-$ make docker-start DATABASE=mariadb
-```
-
-You’ll also need to change the `DATABASE_URL` value in the [`.env` file](/.env) (just uncomment the second line).
-If you want to make this change permanent, create a `.env.local` file and copy the line into it.
-
-## Work with LDAP
-
-You’ll have to create an `.env.local` file to enable LDAP support in Bileto:
+By default, the development environment starts with a PostgreSQL database.
+To use MariaDB, you must set the `DATABASE_URL` value in the `.env.dev.local` file:
 
 ```dotenv
-LDAP_ENABLED=true
+DATABASE_URL="mysql://root:mariadb@mariadb:3306/bileto?serverVersion=10.4.29-MariaDB"
 ```
 
-Everything else is already configured in the [`.env`](/.env) file.
+Then, restart the `docker-start` command with the `DATABASE` variable set to `mariadb`:
 
-You can login with two users with LDAP:
+```console
+$ make docker-start DATABASE=mariadb
+```
 
-- `charlie` / `secret` (same as the previous `[email protected]` user, instead that you can't login with its email anymore)
-- `dominique` / `secret` (this user is created at login, so they have no organization nor permissions)
+You may have to setup or migrate the database:
 
-You can still log in using the `[email protected]` and `[email protected]` emails.
+```console
+$ make db-setup
+$ # or
+$ make db-migrate
+```
 
 ## Working in the Docker containers
 

env.sample

@@ -1,30 +1,31 @@
 # This file defines a list of environment variables used to configure Bileto.
-# Please copy this file as .env.local to configure Bileto in production.
+# Please copy this file as .env.local and adapt to your needs to configure
+# Bileto in production.
 
 ####################################
 # Configuration of the application #
 ####################################
 # Define the environment of the application. It can be: prod, dev, test
 # Don't change this value unless you know what you do.
-APP_ENV=prod
+APP_ENV="prod"
 
 # A secret used to generate security tokens, **it must be changed!**
 # Generate a token with the command: php bin/console app:secret
-APP_SECRET=change-me
+APP_SECRET="change-me"
 
 # The base URL that serves your application. It is used to generate URLs in
 # non-HTTP contexts (i.e. from the command line).
-APP_BASE_URL=https://example.org
+APP_BASE_URL="https://support.example.org"
 
 # The default locale to use when creating a user and that no locale is
 # specified. This is useful especially when synchronizing with a LDAP server
 # or when no locale can be specified.
 # Must be either "en_GB" (default) or "fr_FR".
-# APP_DEFAULT_LOCALE=fr_FR
+# APP_DEFAULT_LOCALE="fr_FR"
 
 # The path to the upload directory.
 # Default is var/uploads/ in the root directory.
-# APP_UPLOADS_DIRECTORY=/path/to/uploads
+# APP_UPLOADS_DIRECTORY="/path/to/uploads"
 
 #################################
 # Configuration of the database #
@@ -41,16 +42,16 @@ APP_BASE_URL=https://example.org
 # Configure your mail server. It is used to send email notifications to the users.
 # Uncomment both MAILER_* lines and set them to your needs.
 # More documentation at https://symfony.com/doc/7.0/mailer.html (“Transport Setup”).
-# MAILER_DSN=smtp://user:[email protected]:465
-# [email protected]
+# MAILER_DSN="smtp://user:[email protected]:465"
+# MAILER_FROM="[email protected]"
 
 #####################################
 # Configuration of the async system #
 #####################################
 # Configure the Symfony Messenger transport.
 # You should not change this value unless you know what you're doing.
 # More documentation at https://symfony.com/doc/current/messenger.html#transport-configuration
-MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0
+# MESSENGER_TRANSPORT_DSN="doctrine://default?auto_setup=0"
 
 ###########################
 # Configuration of Sentry #
@@ -67,8 +68,8 @@ MESSENGER_TRANSPORT_DSN=doctrine://default?auto_setup=0
 #########################
 # Configuration of LDAP #
 #########################
-# Set to true to use LDAP.
-LDAP_ENABLED=false
+# Uncomment to enable LDAP.
+# LDAP_ENABLED=true
 
 # The hostname of the LDAP server.
 # LDAP_HOST="localhost"
@@ -106,6 +107,6 @@ LDAP_ENABLED=false
 
 # The name of the LDAP attributes to search for the identifier, the email and
 # the fullname of the users.
-# LDAP_FIELD_IDENTIFIER=cn
-# LDAP_FIELD_EMAIL=mail
-# LDAP_FIELD_FULLNAME=displayName
+# LDAP_FIELD_IDENTIFIER="cn"
+# LDAP_FIELD_EMAIL="mail"
+# LDAP_FIELD_FULLNAME="displayName"

src/Service/Ldap.php

@@ -36,16 +36,13 @@ public function __construct(
         private string $querySearchUser,
         #[Autowire(env: 'LDAP_QUERY_LIST_USERS')]
         private string $queryListUsers,
-        #[Autowire(env: 'default::LDAP_FIELD_IDENTIFIER')]
-        private ?string $fieldIdentifier,
-        #[Autowire(env: 'default::LDAP_FIELD_EMAIL')]
-        private ?string $fieldEmail,
-        #[Autowire(env: 'default::LDAP_FIELD_FULLNAME')]
-        private ?string $fieldFullName,
+        #[Autowire(env: 'LDAP_FIELD_IDENTIFIER')]
+        private string $fieldIdentifier,
+        #[Autowire(env: 'LDAP_FIELD_EMAIL')]
+        private string $fieldEmail,
+        #[Autowire(env: 'LDAP_FIELD_FULLNAME')]
+        private string $fieldFullName,
     ) {
-        $this->fieldIdentifier ??= 'cn';
-        $this->fieldEmail ??= 'mail';
-        $this->fieldFullName ??= 'displayName';
     }
 
     /**

src/Service/Locales.php

@@ -27,10 +27,10 @@ public static function getSupportedLocalesCodes(): array
     }
 
     public function __construct(
-        #[Autowire(env: 'default::APP_DEFAULT_LOCALE')]
-        ?string $defaultLocale,
+        #[Autowire(env: 'APP_DEFAULT_LOCALE')]
+        string $defaultLocale,
     ) {
-        if ($defaultLocale && $this->isAvailable($defaultLocale)) {
+        if ($this->isAvailable($defaultLocale)) {
             /** @var key-of<self::SUPPORTED_LOCALES> */
             $defaultLocale = $defaultLocale;
             $this->defaultLocale = $defaultLocale;