# Environment-specific mail and SMS configuration

## Configuration source

Mail identity and test delivery controls belong to each instance's ignored
`application/config/config.php`. They are not editable in **Ustawienia systemu**
and are never read from `application_setting`, so restoring a production database
on local or test-next cannot replace these controls.

Define the six required constants below in `application/config/config.php`;
`MAIL_TO2` is optional. The application loads this file before
`application/config/load_database_settings.php`. Replace any existing definition
of the same constant; do not append duplicates. Keep the existing
`MAIL_SETFROM_EMAIL`, SMTP credentials, `ENVIRONMENT`, and all unrelated server
configuration. Local and test-next must use `ENVIRONMENT = DEV`; production must
use `ENVIRONMENT = PROD`.

| Constant | Type and purpose |
| --- | --- |
| `MAIL_SETFROM_NAME` | String displayed as the sender's name. |
| `MAIL_REPLYTO_NAME` | String displayed as the Reply-To name. |
| `MAIL_REPLYTO_EMAIL` | Valid email address used for Reply-To. |
| `MAIL_TO` | Required valid test email on DEV; `false` on production. |
| `MAIL_TO2` | Optional additional SMTP test email. The constant may be omitted, `false`, or an empty string when no second recipient is wanted. Production ignores it. |
| `SKIP_SMS` | PHP boolean: `true` suppresses SMS gateway calls, `false` allows delivery subject to the DEV recipient guard. Do not use quoted `"true"` or `"false"`. |
| `SMS_PHONENUMBER` | Test phone string containing exactly nine digits without spaces or `+48`, required on DEV when `SKIP_SMS` is `false`; otherwise `false` is allowed. Use `false` on production. |

DEV template for test-next; local uses the same required keys. The optional secondary
email and phone below are placeholders. Leave SMS disabled until a controlled
test number has been entered, then set `SKIP_SMS` to `false` when delivery is
wanted:

```php
define('MAIL_SETFROM_NAME', 'Rollschool (test-next)');
define('MAIL_REPLYTO_NAME', 'Rollschool (test-next)');
define('MAIL_REPLYTO_EMAIL', 'kontakt@rollschool.pl');
define('MAIL_TO', 'kontakt@rollschool.pl');
define('MAIL_TO2', false); // Optional: 'tester@example.com'.
define('SKIP_SMS', true);
define('SMS_PHONENUMBER', false); // Replace with the controlled nine-digit number.
```

Production:

```php
define('MAIL_SETFROM_NAME', 'Rollschool');
define('MAIL_REPLYTO_NAME', 'Rollschool');
define('MAIL_REPLYTO_EMAIL', 'kontakt@rollschool.pl');
define('MAIL_TO', false);
define('MAIL_TO2', false);
define('SKIP_SMS', false);
define('SMS_PHONENUMBER', false);
```

## Email delivery

On local and test-next (`ENVIRONMENT = DEV`), all outbound email recipients use
the configured `MAIL_TO` address. `EmailRecipient::resolve()` is shared by direct
SMTP delivery, queued SMTP delivery, Przelewy24 registration and Fakturownia
receipt capture. An administrator session or impersonation does not affect it.
Production keeps the intended customer/payer recipient and ignores `MAIL_TO`.

Missing or invalid configuration never falls back to a customer address. P24
registration returns an actionable configuration error before HTTP. Direct mail
logs the failure and queued mail records a failed delivery. A single `MAIL_TO`
is sufficient. Optional `MAIL_TO2` retains its role as a second configured SMTP
test recipient; omitting it or setting it to `false` or an empty string sends no
additional copy. P24 and Fakturownia use the primary `MAIL_TO` only. Direct DEV mail does not BCC the
production sender mailbox.

Receipt recipients already captured are preserved. Changing `MAIL_TO` affects
new captures and later SMTP delivery, not existing provider documents.

## SMS delivery

The queue worker checks the environment-owned controls before contacting the
gateway. `SKIP_SMS = true` marks queued SMS as processed without sending them.
On DEV, a missing `SKIP_SMS` also prevents delivery. With `SKIP_SMS = false`,
DEV requires a valid nine-digit `SMS_PHONENUMBER`; missing or invalid test numbers
stop delivery instead of falling back to a customer's number. A valid test
number is sent with the `+48` prefix. Production uses the intended recipient and
ignores the DEV phone override; `SKIP_SMS = true` still suppresses sending.

## Deployment, database copies, and rollback

The exact configuration paths are:

- local: `/Users/radek/Sites/rollschool.localhost/application/config/config.php`;
- test-next: `/home/rollschomq-rg/test-next.rollschool.pl/application/config/config.php`;
- production: `/home/rollschomq-rg/zapisy/application/config/config.php`.

1. Back up the existing config privately on the same instance. Add or replace the
   six required definitions locally and on test-next, before database settings
   load. Add `MAIL_TO2` only when a second SMTP test recipient is wanted; during
   the transition from the older code, an explicit `false` also prevents that
   code from loading an old secondary address from the database.
   Lint the changed config without printing its contents. Verify the intended
   environment, constant types, valid test email, and SMS policy without sending
   messages or exposing SMTP credentials.
2. Apply and verify the test-next configuration before configuring production.
   The previous implementation already gives explicit constants precedence over
   database settings, so these definitions can be installed before the code
   deployment. They take effect immediately on the next request or worker run;
   they are not dormant until deployment. Use the production values above when
   preparing production in advance.
3. Deploy and verify the code on test-next, then promote the accepted exact SHA
   to production through the usual deployment workflow. Configuration validation
   requires the six mandatory constants, correct types, valid configured email
   values, and a valid DEV SMS number when SMS sending is enabled. The two former settings sections
   must no longer be visible or writable in the administration panel.
4. After a production database copy to DEV, retain that DEV instance's config.
   Confirm its mail recipients and SMS policy still come from the file; do not
   copy production `config.php` with the database.

No SQL migration is required. Existing `application_setting` rows for all seven
keys remain in place but are ignored. Do not clean them up while any environment
still runs the earlier implementation; this change includes no database cleanup.
The change does not rewrite historical records,
move `Files` assets, or require installing any additional server files. The
configuration update above must precede deployment; it is not performed by the
database migration runner.

For a code rollback, retain the six required environment definitions and define
`MAIL_TO2` explicitly as the intended secondary test email or `false`. The earlier
implementation respects explicitly defined constants but loads an undefined
`MAIL_TO2` from the database; its DEV P24 path requires a valid `MAIL_TO`.
Do not remove the overrides and resume using rows
that may have been copied from production. If a config edit needs correction,
restore only the relevant values from the private backup and check the DEV
recipient guards before resuming delivery.

## Verification

Use isolated tests or fake gateways for missing and invalid configuration: DEV
must never fall back to customer email addresses or phone numbers. Verify SMS
suppression, a controlled DEV phone with `+48`, and normal production recipients.
Start a sandbox payment, compare the checkout notice, P24 registration email and
newly captured receipt recipient, and confirm registration alone does not mark
the payment as paid. Check normal, guest and impersonated sessions with the same
test address. `tests/przelewy24_registration_test.php` covers valid, false, empty
and invalid email configuration with temporary tables and a fake provider.
It requires an isolated `RP_TEST_DATABASE=codex_rollpoints_<name>` prepared with
`scripts/prepare-rollpoints-tests.php`; see [RollPoints test suites](rollpoints.md#automated-suites).
`tests/communication_configuration_test.php` covers file configuration, an omitted
`MAIL_TO2`, and isolation from copied database values without database access.
`tests/sms_routing_test.php` verifies all three SMS consumers using fake storage
and transports. `tests/email_optional_copy_test.php` verifies direct and queued
email delivery with `MAIL_TO2` entirely undefined and without opening connections.
`tests/fakturownia_settings_test.php` checks that old or crafted
forms cannot change the retired settings, using connection-local temporary tables.