presseportale/app/Services/Newsletter/CampaignRecipients.php

<?php

namespace App\Services\Newsletter;

use App\Enums\EmailNotificationType;
use App\Enums\UserPaymentOptionStatus;
use App\Models\User;
use Illuminate\Database\Eloquent\Builder;

/**
 * Empfänger-Auswahl für interne Newsletter-Kampagnen (Admin ▸ Newsletter).
 *
 * Grundmenge sind alle aktiven User mit E-Mail-Adresse, die den Newsletter
 * nicht abbestellt haben. Darauf setzen die Kampagnen-Filter auf:
 * Portal, Legacy-Vertrag (Bestandsschutz-Zahlungsoption) und der
 * Login-Zeitraum (eingeloggt innerhalb X Monaten bzw. dessen Komplement:
 * länger nicht oder noch nie eingeloggt).
 */
class CampaignRecipients
{
    public const LOGIN_ANY = 'any';

    public const LOGIN_WITHIN = 'within';

    public const LOGIN_NOT_WITHIN = 'not_within';

    public const SORT_FIELDS = ['created_at', 'last_login_at'];

    /**
     * Filter-Defaults; unbekannte Werte fallen auf diese zurück.
     *
     * @return array{portal: string, legacy_contract: bool, login: string, login_months: int, sort: string, direction: string}
     */
    public static function defaultFilters(): array
    {
        return [
            'portal' => '',
            'legacy_contract' => false,
            'login' => self::LOGIN_ANY,
            'login_months' => 6,
            'sort' => 'created_at',
            'direction' => 'desc',
        ];
    }

    /**
     * Bringt einen (z. B. aus der UI oder dem JSON-Snapshot kommenden)
     * Filter-Satz in eine validierte, vollständige Form.
     *
     * @param  array<string, mixed>  $filters
     * @return array{portal: string, legacy_contract: bool, login: string, login_months: int, sort: string, direction: string}
     */
    public function normalize(array $filters): array
    {
        $defaults = self::defaultFilters();

        $portal = (string) ($filters['portal'] ?? '');
        $login = (string) ($filters['login'] ?? $defaults['login']);
        $months = (int) ($filters['login_months'] ?? $defaults['login_months']);
        $sort = (string) ($filters['sort'] ?? $defaults['sort']);
        $direction = (string) ($filters['direction'] ?? $defaults['direction']);

        return [
            'portal' => in_array($portal, ['presseecho', 'businessportal24', 'both'], true) ? $portal : '',
            'legacy_contract' => (bool) ($filters['legacy_contract'] ?? false),
            'login' => in_array($login, [self::LOGIN_ANY, self::LOGIN_WITHIN, self::LOGIN_NOT_WITHIN], true) ? $login : self::LOGIN_ANY,
            'login_months' => max(1, min(120, $months)),
            'sort' => in_array($sort, self::SORT_FIELDS, true) ? $sort : $defaults['sort'],
            'direction' => $direction === 'asc' ? 'asc' : 'desc',
        ];
    }

    /**
     * Menschenlesbare Zusammenfassung eines Filter-Satzes für die Admin-UI.
     *
     * @param  array<string, mixed>  $filters
     * @return list<string>
     */
    public function describe(array $filters): array
    {
        $filters = $this->normalize($filters);

        $parts = ['Aktive User mit E-Mail, Newsletter nicht abbestellt'];

        if ($filters['portal'] !== '') {
            $parts[] = 'Portal: '.$filters['portal'];
        }

        if ($filters['legacy_contract']) {
            $parts[] = 'Nur User mit Legacy-Vertrag (Bestandsschutz)';
        }

        if ($filters['login'] === self::LOGIN_WITHIN) {
            $parts[] = sprintf('In den letzten %d Monaten eingeloggt', $filters['login_months']);
        } elseif ($filters['login'] === self::LOGIN_NOT_WITHIN) {
            $parts[] = sprintf('Seit %d Monaten nicht eingeloggt (oder noch nie)', $filters['login_months']);
        }

        $parts[] = sprintf(
            'Sortiert nach %s (%s)',
            $filters['sort'] === 'last_login_at' ? 'letztem Login' : 'Erstellungsdatum',
            $filters['direction'] === 'asc' ? 'älteste zuerst' : 'neueste zuerst',
        );

        return $parts;
    }

    /**
     * @param  array<string, mixed>  $filters
     * @return Builder<User>
     */
    public function query(array $filters): Builder
    {
        $filters = $this->normalize($filters);
        $loginCutoff = now()->subMonths($filters['login_months']);

        return User::query()
            ->where('is_active', true)
            ->whereNotNull('email')
            ->whereDoesntHave('emailNotificationOptOuts', fn (Builder $query) => $query
                ->where('type', EmailNotificationType::Newsletter->value))
            ->when($filters['portal'] !== '', fn (Builder $query) => $query
                ->where('portal', $filters['portal']))
            ->when($filters['legacy_contract'], fn (Builder $query) => $query
                ->whereHas('userPaymentOptions', fn (Builder $inner) => $inner
                    ->where('status', UserPaymentOptionStatus::Grandfathered->value)
                    ->where(fn (Builder $until) => $until
                        ->whereNull('grandfathered_until')
                        ->orWhere('grandfathered_until', '>=', now()))))
            ->when($filters['login'] === self::LOGIN_WITHIN, fn (Builder $query) => $query
                ->where('last_login_at', '>=', $loginCutoff))
            ->when($filters['login'] === self::LOGIN_NOT_WITHIN, fn (Builder $query) => $query
                ->where(fn (Builder $inner) => $inner
                    ->whereNull('last_login_at')
                    ->orWhere('last_login_at', '<', $loginCutoff)))
            ->orderBy($filters['sort'], $filters['direction'])
            ->orderBy('id');
    }
}