PS_Launcher/server/admin/lib/Mailer.php

<?php
declare(strict_types=1);

namespace PSLauncher\Admin;

/**
 * Petit helper d'envoi d'emails de notification (release announce).
 *
 * Stratégie : on utilise <code>mail()</code> natif PHP, qui sur OVH mutualisé
 * passe par le relais SMTP local et marche out-of-the-box sans config
 * additionnelle. Pas de dépendance composer (PHPMailer, etc.) volontairement
 * — on a besoin de notifications opportunistes, pas de delivery garantie.
 *
 * Pour passer à PHPMailer / SMTP externe plus tard, la surface API reste la
 * même : on remplace juste <see cref="sendInternal"/> par un appel
 * <code>$mailer->send()</code>.
 */
final class Mailer
{
    /**
     * Parse un blob texte saisi par l'admin (CSV, ligne par ligne, mélange…)
     * en liste d'emails normalisés et validés. Tout token qui ne matche pas
     * la regex email est rejeté SILENCIEUSEMENT (l'admin n'a pas besoin d'un
     * popup pour un copy/paste avec une virgule en trop).
     *
     * @return list<string> emails uniques lowercase
     */
    public static function parseEmails(?string $raw): array
    {
        if ($raw === null || trim($raw) === '') return [];
        // Split sur tout séparateur courant : virgule, point-virgule, espace,
        // newline. Permet à l'admin de coller un copy/paste depuis Outlook,
        // Excel, ou ligne par ligne — peu importe.
        $tokens = preg_split('/[\s,;]+/', $raw, -1, PREG_SPLIT_NO_EMPTY) ?: [];
        $out = [];
        foreach ($tokens as $t) {
            $t = strtolower(trim($t));
            if ($t === '') continue;
            if (!filter_var($t, FILTER_VALIDATE_EMAIL)) continue;
            if (!in_array($t, $out, true)) $out[] = $t;
        }
        return $out;
    }

    /**
     * Inverse : prend un tableau d'emails et le formate pour stockage DB
     * (séparé par virgules). NULL si la liste est vide pour économiser
     * une ligne en DB sur les licenses sans contacts.
     */
    public static function joinForStorage(array $emails): ?string
    {
        $emails = array_values(array_filter(
            array_map('trim', $emails),
            fn($e) => $e !== '' && filter_var($e, FILTER_VALIDATE_EMAIL)
        ));
        return empty($emails) ? null : implode(', ', $emails);
    }

    /**
     * Envoie un email HTML (avec partie texte alternative pour les MUA legacy)
     * à un destinataire. Best-effort : retourne true en cas de succès apparent
     * du sink mail(), false si rejet immédiat. Erreurs de delivery côté SMTP
     * relais (bounce, deferred) ne sont PAS détectées ici — on log juste le
     * résultat brut.
     *
     * Si <paramref name="$inlineImages"/> est non vide, on construit une structure
     * MIME <c>multipart/related</c> (CID embed) au lieu de <c>multipart/alternative</c>.
     * Les images sont attachées comme pièces jointes inline, référencées dans
     * le HTML via <c>&lt;img src="cid:..."&gt;</c>. Avantage vs hotlink HTTP :
     * Outlook (et MUA généralement) affiche l'image SANS demander de permission
     * (vs hotlink bloqué par défaut pour anti-tracking pixel).
     *
     * @param array  $notifConfig   bloc $config['notifications'] (from_address, from_name, reply_to)
     * @param string $to            destinataire UNIQUE (pour multi-destinataires, appeler en boucle)
     * @param string $subject       sujet en clair (sera Q-encoded UTF-8 automatiquement)
     * @param string $bodyHtml      contenu HTML (multipart alt avec text auto-généré)
     * @param array  $inlineImages  liste d'images à embed inline. Chaque entrée :
     *                              ['cid' => 'logo', 'path' => '/abs/path/file.png', 'type' => 'image/png']
     */
    public static function send(array $notifConfig, string $to, string $subject, string $bodyHtml, array $inlineImages = []): bool
    {
        $from      = $notifConfig['from_address'] ?? 'no-reply@localhost';
        $fromName  = $notifConfig['from_name']    ?? 'PROSERVE Launcher';
        $replyTo   = $notifConfig['reply_to']     ?? '';

        // Filtre les inline images : ne garde que celles dont le fichier existe
        // ET est lisible. Si une image manque, on log silencieusement et on
        // continue avec les autres — l'email part de toute façon.
        $validImages = [];
        foreach ($inlineImages as $img) {
            $p = $img['path'] ?? '';
            if ($p === '' || !is_file($p) || !is_readable($p)) continue;
            $validImages[] = $img;
        }

        // Boundaries uniques. Si on a des images, on a 2 niveaux d'imbrication :
        // multipart/related contenant multipart/alternative + image(s).
        $boundaryAlt = '=_PSLauncherAlt_'  . bin2hex(random_bytes(8));
        $boundaryRel = '=_PSLauncherRel_'  . bin2hex(random_bytes(8));

        // Headers RFC 5322 + MIME. Pas de "Bcc:" — on appelle send() par destinataire
        // pour avoir des "Per-user emails" et faciliter le debugging.
        $contentType = empty($validImages)
            ? "multipart/alternative; boundary=\"{$boundaryAlt}\""
            : "multipart/related; type=\"multipart/alternative\"; boundary=\"{$boundaryRel}\"";
        $headers = [
            'MIME-Version: 1.0',
            "Content-Type: {$contentType}",
            'From: ' . self::formatAddress($fromName, $from),
            'X-Mailer: PSLauncher-Admin',
            'X-Auto-Response-Suppress: All', // mute autoresponders OOO
        ];
        if ($replyTo !== '' && filter_var($replyTo, FILTER_VALIDATE_EMAIL)) {
            $headers[] = 'Reply-To: ' . $replyTo;
        }

        // === Construction du body ===
        $bodyText = self::htmlToPlainText($bodyHtml);

        // Bloc multipart/alternative (text + html)
        $altPart  = "--{$boundaryAlt}\r\n";
        $altPart .= "Content-Type: text/plain; charset=UTF-8\r\n";
        $altPart .= "Content-Transfer-Encoding: 8bit\r\n\r\n";
        $altPart .= $bodyText . "\r\n\r\n";
        $altPart .= "--{$boundaryAlt}\r\n";
        $altPart .= "Content-Type: text/html; charset=UTF-8\r\n";
        $altPart .= "Content-Transfer-Encoding: 8bit\r\n\r\n";
        $altPart .= $bodyHtml . "\r\n\r\n";
        $altPart .= "--{$boundaryAlt}--\r\n";

        if (empty($validImages)) {
            // Pas d'images → email simple, juste l'alternative
            $body = $altPart;
        } else {
            // Avec images → multipart/related wrappant l'alt + chaque image
            $body  = "--{$boundaryRel}\r\n";
            $body .= "Content-Type: multipart/alternative; boundary=\"{$boundaryAlt}\"\r\n\r\n";
            $body .= $altPart;
            foreach ($validImages as $img) {
                $cid  = $img['cid'] ?? bin2hex(random_bytes(6));
                $type = $img['type'] ?? 'application/octet-stream';
                $path = $img['path'];
                $name = basename($path);
                $data = @file_get_contents($path);
                if ($data === false) continue;
                $b64  = chunk_split(base64_encode($data), 76, "\r\n");
                $body .= "\r\n--{$boundaryRel}\r\n";
                $body .= "Content-Type: {$type}; name=\"{$name}\"\r\n";
                $body .= "Content-Transfer-Encoding: base64\r\n";
                $body .= "Content-ID: <{$cid}>\r\n";
                $body .= "Content-Disposition: inline; filename=\"{$name}\"\r\n\r\n";
                $body .= $b64;
            }
            $body .= "\r\n--{$boundaryRel}--\r\n";
        }

        $subjectEncoded = '=?UTF-8?B?' . base64_encode($subject) . '?=';

        try {
            return @mail($to, $subjectEncoded, $body, implode("\r\n", $headers));
        } catch (\Throwable $e) {
            return false;
        }
    }

    /**
     * Convertit un HTML simple en plain text pour la partie text/plain du
     * multipart. Pas une vraie conversion (ce n'est pas html2text), mais
     * suffisant pour nos templates qui sont quasi-text avec quelques tags.
     */
    private static function htmlToPlainText(string $html): string
    {
        // Convert <br> et <p> en sauts de ligne avant strip_tags
        $s = preg_replace('#<br\s*/?>#i', "\n", $html) ?? $html;
        $s = preg_replace('#</p>\s*<p[^>]*>#i', "\n\n", $s) ?? $s;
        $s = preg_replace('#<a\s[^>]*href="([^"]+)"[^>]*>([^<]+)</a>#i', '$2 ($1)', $s) ?? $s;
        $s = strip_tags($s);
        $s = html_entity_decode($s, ENT_QUOTES | ENT_HTML5, 'UTF-8');
        return trim($s);
    }

    /**
     * "Pretty Name <email@x>" si name non vide, sinon "email@x" brut.
     * Échappe les chars spéciaux conformément à RFC 5322.
     */
    private static function formatAddress(string $name, string $email): string
    {
        $name = trim($name);
        if ($name === '') return $email;
        // Encode le name en MIME si pas pur ASCII
        if (preg_match('/[\x80-\xFF]/', $name)) {
            $name = '=?UTF-8?B?' . base64_encode($name) . '?=';
        } else {
            // Quote si chars spéciaux RFC : "()<>@,;:\\\"/.\\[\\]"
            if (preg_match('/[()<>@,;:\\\"\/\[\]]/', $name)) {
                $name = '"' . str_replace('"', '\\"', $name) . '"';
            }
        }
        return "{$name} <{$email}>";
    }
}