Lesstime/src/Mail/MimeHeaderDecoder.php

<?php

declare(strict_types=1);

namespace App\Mail;

use const ICONV_MIME_DECODE_CONTINUE_ON_ERROR;

/**
 * Décode les en-têtes mail encodés en « encoded-words » MIME (RFC 2047),
 * ex: "=?UTF-8?Q?Fwd=3A_Votre_inscription?=" → "Fwd: Votre inscription".
 *
 * Certains serveurs IMAP (OVH) renvoient les sujets / noms d'expéditeur
 * encodés bruts ; webklex ne les décode pas systématiquement. Cet utilitaire
 * normalise la sortie en UTF-8 lisible. Idempotent : un texte déjà décodé
 * (sans séquence "=?") est retourné inchangé.
 */
final class MimeHeaderDecoder
{
    public static function decode(?string $value): ?string
    {
        if (null === $value || '' === $value) {
            return $value;
        }

        // Pas d'encoded-word → rien à faire (chemin rapide + idempotence).
        if (!str_contains($value, '=?')) {
            return $value;
        }

        $decoded = @iconv_mime_decode($value, ICONV_MIME_DECODE_CONTINUE_ON_ERROR, 'UTF-8');

        if (false === $decoded || '' === trim($decoded)) {
            // Fallback : mb_decode_mimeheader gère certains cas refusés par iconv.
            $previous = mb_internal_encoding();
            mb_internal_encoding('UTF-8');

            try {
                $decoded = mb_decode_mimeheader($value);
            } finally {
                mb_internal_encoding($previous);
            }
        }

        return false === $decoded || '' === $decoded ? $value : $decoded;
    }
}