andre/fitme3070.pt
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Send mail locally again: message_queue + PHPMailer over SMTP

Browse Source 
Outbound email was relayed to the hub's /notify endpoint, so this install had
no SMTP configuration of its own and no way to see what had been sent. Bring
delivery back in-house, following the fotografia.andmore.pt stack rather than
inventing a second shape for it.

  - Submodule bumped 603ff84 -> ea3616a, the pin fotografia already uses. That
    is what provides functions_mail.php (shared transport), functions_settings.php
    (platform_smtp_config + encrypted settings) and compat_secrets.php. Verified
    no function-name collisions with this repo's own config/functions_settings.php:
    platform-tools namespaces everything platform_*.

  - PHPMailer 7.1.1 vendored at vendor/PHPMailer/src/. platform_mail_available()
    looks for exactly this hand-vendored layout before falling back to composer's
    autoloader, so the host needs no shell and no composer install. LGPL-2.1
    license text included.

  - config/functions_queue.php replaced: was a thin facade over the hub relay,
    now fotografia's real queue. Rows are claimed atomically, retried with
    exponential backoff up to max_attempts, and park in 'failed' with the real
    SMTP rejection in last_error.

  - SMTP resolution matches the fleet: .env wins for the SMTP_* constants, while
    the actual send goes through platform_smtp_config($pdo), which is DB-first.
    That ordering is deliberate -- the database is the half an operator can
    change from the backoffice without shell access. Empty SMTP_HOST falls back
    to PHP mail().

  - Sistema -> Comunicações (views/sysadmin/comms.php): credentials plus a live
    SMTP connection test and a verdict on what would happen to a message sent
    right now. Secret-valued settings are write-only in the form and encrypted
    at rest (AES-256-GCM, key from .env, never in the DB dump). Which keys count
    as secret is platform_settings_is_secret()'s decision, not a list kept here.

  - Sistema -> Mensagens (views/sysadmin/messages.php): the queue monitor.
    Filters, per-message detail with last_error, and retry/cancel/archive.
    Retry flushes inline so the operator sees the outcome immediately.

  - cron.php drains the queue every 5 minutes, serialised with a lock file, and
    runs retention once a day. Over HTTP it answers 404 until CRON_TOKEN is set
    to something other than replace_me. Deliberately not a copy of fotografia's
    cron: the session-reminder, download-digest and photo-archive steps have no
    modules here and would be dead code.

  - config/functions_notify_client.php deleted, and ANDMORE_ID_URL with it --
    the hub relay was its only caller.

Verified without a database: PHP lint across the tree; PHPMailer builds a full
MIME message with RFC 2047 UTF-8 subject encoding from the three vendored files;
platform_mail_available() finds them; platform_mail_make() returns a correctly
configured mailer; the diagnosis states report Operacional / Não configurado.
NOT verified: the settings encryption round-trip -- this machine's PHP has no
openssl extension, so platform_secret_key() returns null and values pass through
in clear. The code degrades safely (stores the value rather than losing it) and
the Comunicações page warns when the key is unavailable.

Deployment: apply database/migration_20260913_message_queue.sql, set SMTP in
Comunicações or .env, set APP_SECRET_KEY, and schedule cron.php.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
andreandClaude Opus 5 committed 2026-09-13 22:08:38 +01:00
1 parent 3626080599
commit d5cb50b432
16 files changed
+8982 -136
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

views/sysadmin/comms.php
+198
View File
@@ -0,0 +1,198 @@
<?php
// Comunicações — delivery credentials plus the diagnostics a sysadmin needs
// when mail stops working.
//
// Config and tests live on one page deliberately: the loop is "change a
// setting, test it, read the real error", and splitting that across two screens
// makes it slower to diagnose.
//
// Sysadmin-only: it handles SMTP and Twilio credentials.
require __DIR__ . '/../../config/db.php';
require __DIR__ . '/../../config/functions.php';
$user = require_sysadmin();
require_once __DIR__ . '/../../shared/platform-tools/functions_mail.php';
require_once __DIR__ . '/../../shared/platform-tools/functions_settings.php';
$repo_root = dirname(__DIR__, 2);
$saved = false;
$errors = [];
$test = null;
// Secret fields are write-only in the UI and encrypted at rest. Which keys count
// as secret is decided by platform_settings_is_secret() — anything ending in
// _password/_secret/_token/_api_key — rather than a list maintained here, so a
// field added later can't accidentally be stored in the clear.
$fields = [
'smtp_host' => ['label' => 'Servidor SMTP', 'type' => 'text', 'hint' => 'Vazio = usa a função mail() do PHP.'],
'smtp_port' => ['label' => 'Porta', 'type' => 'number', 'hint' => '587 para TLS, 465 para SSL.'],
'smtp_secure' => ['label' => 'Encriptação', 'type' => 'select', 'options' => ['tls' => 'TLS (StartTLS)', 'ssl' => 'SSL', '' => 'Nenhuma']],
'smtp_username' => ['label' => 'Utilizador', 'type' => 'text', 'hint' => 'Normalmente o endereço de email completo.'],
'smtp_password' => ['label' => 'Palavra-passe', 'type' => 'password'],
'email_from' => ['label' => 'Remetente', 'type' => 'text', 'hint' => 'Endereço que aparece no From.'],
'email_from_name' => ['label' => 'Nome do remetente', 'type' => 'text'],
'twilio_sid' => ['label' => 'Account SID', 'type' => 'text', 'hint' => 'Começa por AC…'],
'twilio_token' => ['label' => 'Auth Token', 'type' => 'password'],
'twilio_sms_from' => ['label' => 'Remetente SMS', 'type' => 'text', 'hint' => 'E.164 (+351…) ou alfanumérico.'],
'twilio_whatsapp_from' => ['label' => 'Remetente WhatsApp', 'type' => 'text', 'hint' => 'Número E.164, sem o prefixo whatsapp:.'],
'sms_default_country_code' => ['label' => 'Indicativo por defeito', 'type' => 'text', 'hint' => 'Aplicado a números guardados sem +.'],
];
$groups = [
'SMTP' => ['smtp_host', 'smtp_port', 'smtp_secure', 'smtp_username', 'smtp_password', 'email_from', 'email_from_name'],
'Twilio (SMS / WhatsApp)' => ['twilio_sid', 'twilio_token', 'twilio_sms_from', 'twilio_whatsapp_from', 'sms_default_country_code'],
];
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
csrf_check();
$action = $_POST['_action'] ?? 'save';
$uid = (int) $user['id'];
if ($action === 'save') {
foreach ($fields as $key => $meta) {
$raw = trim((string) ($_POST[$key] ?? ''));
if (platform_settings_is_secret($key)) {
// Blank means "leave the stored one alone" — the field is never
// pre-filled with the real value, so blank cannot mean "clear".
// Clearing is an explicit checkbox.
if (!empty($_POST[$key . '_clear'])) {
db_update_setting($pdo, $key, '', $uid);
} elseif ($raw !== '') {
db_update_setting($pdo, $key, secret_encrypt($raw), $uid);
}
continue;
}
db_update_setting($pdo, $key, $raw, $uid);
}
// db_update_setting() drops fitme3070's file cache; platform_settings_get()
// keeps its own per-request cache, which must go too or the diagnostics
// below would render the values from before this save.
platform_settings_cache_clear();
$saved = true;
} elseif ($action === 'test') {
$test = platform_mail_test($repo_root, platform_smtp_config($pdo));
}
}
$current = settings_all();
[$diagClass, $diagTitle, $diagText] = platform_mail_diagnosis($repo_root, null, $pdo);
$rows = platform_mail_config_rows(null, $pdo);
$page_title = 'Comunicações';
include __DIR__ . '/../../includes/header.php';
?>
<div class="container" style="max-width:860px;">
<h1 class="h3 mb-1">Comunicações</h1>
<p class="text-muted mb-4">Credenciais de envio e diagnóstico. As palavras-passe são guardadas cifradas.</p>
<?php if ($saved): ?><div class="alert alert-success">Definições guardadas.</div><?php endif; ?>
<?php foreach ($errors as $e): ?><div class="alert alert-danger"><?= htmlspecialchars($e) ?></div><?php endforeach; ?>
<?php if (!platform_settings_secret_available()): ?>
<div class="alert alert-warning">
<strong>Cifra indisponível.</strong> Defina <code>APP_SECRET_KEY</code> no <code>.env</code>
(ou um <code>BACKUP_TOKEN</code> que não seja <code>replace_me</code>) — sem chave, as palavras-passe
ficam guardadas em texto simples e acabam nos backups da base de dados.
</div>
<?php endif; ?>
<!-- ─── Estado ─────────────────────────────────────────────────────── -->
<div class="card shadow-sm mb-3"><div class="card-body">
<div class="d-flex justify-content-between align-items-start flex-wrap gap-2">
<div>
<h2 class="h6 mb-1">Estado</h2>
<span class="badge text-bg-<?= htmlspecialchars($diagClass) ?>"><?= htmlspecialchars($diagTitle) ?></span>
<p class="text-muted small mb-0 mt-2"><?= htmlspecialchars($diagText) ?></p>
</div>
<form method="POST" class="ms-auto">
<?= csrf_field() ?>
<input type="hidden" name="_action" value="test">
<button class="btn btn-outline-primary"><i class="bi bi-plug me-1"></i>Testar ligação SMTP</button>
</form>
</div>
<?php if ($test !== null): ?>
<hr>
<div class="alert alert-<?= !empty($test['ok']) ? 'success' : 'danger' ?> py-2 small mb-2">
<?= !empty($test['ok']) ? 'Ligação estabelecida.' : htmlspecialchars((string) ($test['error'] ?? 'Falhou.')) ?>
</div>
<?php if (!empty($test['log'])): ?>
<details>
<summary class="small text-muted">Registo da ligação</summary>
<pre class="small bg-light p-2 mt-2 mb-0" style="max-height:260px;overflow:auto;white-space:pre-wrap;"><?= htmlspecialchars((string) $test['log']) ?></pre>
</details>
<?php endif; ?>
<?php endif; ?>
<hr>
<div class="table-responsive">
<table class="table table-sm mb-0">
<tbody>
<?php foreach ($rows as [$label, $value, $ok]): ?>
<tr>
<th class="text-muted fw-normal" style="width:40%;"><?= htmlspecialchars($label) ?></th>
<td>
<?= htmlspecialchars((string) $value) ?>
<?php if (!$ok): ?><i class="bi bi-exclamation-triangle-fill text-warning ms-1"></i><?php endif; ?>
</td>
</tr>
<?php endforeach; ?>
</tbody>
</table>
</div>
<p class="text-muted small mb-0 mt-2">
Valores pinados no <code>.env</code> têm precedência sobre estes campos — se editar aqui e nada mudar,
é porque a chave está definida no <code>.env</code>.
</p>
</div></div>
<!-- ─── Definições ─────────────────────────────────────────────────── -->
<form method="POST">
<?= csrf_field() ?>
<input type="hidden" name="_action" value="save">
<?php foreach ($groups as $groupLabel => $keys): ?>
<div class="card shadow-sm mb-3"><div class="card-body">
<h2 class="h6 mb-3"><?= htmlspecialchars($groupLabel) ?></h2>
<?php foreach ($keys as $key):
$meta = $fields[$key];
$isSecret = platform_settings_is_secret($key);
$stored = (string) ($current[$key] ?? '');
?>
<div class="mb-3">
<label class="form-label" for="f-<?= htmlspecialchars($key) ?>"><?= htmlspecialchars($meta['label']) ?></label>
<?php if ($meta['type'] === 'select'): ?>
<select class="form-select" id="f-<?= htmlspecialchars($key) ?>" name="<?= htmlspecialchars($key) ?>">
<?php foreach ($meta['options'] as $val => $lbl): ?>
<option value="<?= htmlspecialchars((string) $val) ?>" <?= $stored === (string) $val ? 'selected' : '' ?>><?= htmlspecialchars($lbl) ?></option>
<?php endforeach; ?>
</select>
<?php elseif ($isSecret): ?>
<input type="password" class="form-control" id="f-<?= htmlspecialchars($key) ?>"
name="<?= htmlspecialchars($key) ?>" autocomplete="new-password"
placeholder="<?= $stored !== '' ? '•••••••• (guardada — deixe vazio para manter)' : 'não definida' ?>">
<?php if ($stored !== ''): ?>
<div class="form-check small mt-1">
<input class="form-check-input" type="checkbox" value="1"
id="c-<?= htmlspecialchars($key) ?>" name="<?= htmlspecialchars($key) ?>_clear">
<label class="form-check-label text-muted" for="c-<?= htmlspecialchars($key) ?>">Apagar a guardada</label>
</div>
<?php endif; ?>
<?php else: ?>
<input type="<?= htmlspecialchars($meta['type']) ?>" class="form-control"
id="f-<?= htmlspecialchars($key) ?>" name="<?= htmlspecialchars($key) ?>"
value="<?= htmlspecialchars($stored) ?>">
<?php endif; ?>
<?php if (!empty($meta['hint'])): ?>
<div class="form-text"><?= htmlspecialchars($meta['hint']) ?></div>
<?php endif; ?>
</div>
<?php endforeach; ?>
</div></div>
<?php endforeach; ?>
<button class="btn btn-primary">Guardar</button>
<a class="btn btn-link" href="<?= base_url('views/sysadmin/messages.php') ?>">Ver fila de mensagens →</a>
</form>
</div>
<?php include __DIR__ . '/../../includes/footer.php'; ?>