Search by

steinhaug / email_routes_hq

steinhaug

Transactional email dispatch with MySQL-backed volume limits and delivery history.

Package info

github.com/steinhaug/email_dispatchers

Language:HTML

pkg:composer/steinhaug/email_routes_hq

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.9.9 2026-11-20 04:46 UTC

This package is auto-updated.

Last update: 2026-11-20 04:49:50 UTC


README

Felles PHP-modul for én mottaker per kall. Hver installasjon har sin egen database, sitt eget volumvern og sin egen transportkonfigurasjon. En vellykket produksjonssending betyr at transportøren har akseptert meldingen.

Se versjonshistorikken.

Ta modulen i bruk

Installer fra en annen PHP-applikasjon

Legg til følgende oppføring under repositories i webshopens eller CMS-ets composer.json. Tilpass stien til biblioteket.

{
    "repositories": {
        "email-routes": {
            "type": "path",
            "url": "I:/htdocs/email_routes_hq",
            "options": {"symlink": true}
        }
    }
}

Installer pakken fra prosjektroten på utviklingsmaskinen.

composer require "steinhaug/email_routes_hq:@dev"

Når bibliotekskoden ligger på main i GitHub-repoet, kan andre prosjekter installere direkte derfra. Legg til VCS-repoet i prosjektet som skal bruke biblioteket, og installer utviklingsversjonen.

composer config repositories.email-routes vcs https://github.com/steinhaug/email_dispatchers.git
composer require "steinhaug/email_routes_hq:dev-main"

Vertens vendor/autoload.php laster email_dispatch(), email_transactional() og email_broadcast() automatisk. Importer vendor/steinhaug/email_routes_hq/schema.sql én gang per installasjon og kall email_routes_configure($mysqli, $mail_conf) i applikasjonens oppstart før du sender. Sendekall uten initialisering, og initialisering med tom eller utelatt konfigurasjon, kaster RuntimeException('error missing credentials') før noe databasekall.

Konfigurer installasjonen

  1. Ved utvikling i bibliotekets egen prosjektrot installerer du avhengighetene med composer install. Kopier _credentials.php til credentials.php i prosjektroten og fyll inn konfigurasjonen. Opprett databasen og kjør php bin/mail-install.php for å opprette tabellene fra schema.sql. Biblioteket bruker PHP 8.1 eller nyere med mysqlnd, mysqli og curl.
  2. Fjern den gamle definisjonen av email_dispatch når løsningen tar i bruk Composer-autoload for dette biblioteket. PHP kan bare registrere den globale funksjonen én gang.
  3. Last konfigurasjonen fra vertsapplikasjonen. Behold hemmeligheter utenfor webroten. Gi modulen en ledig MySQLi- eller Mysqli2-forbindelse med autocommit. La kallet skje etter at forretningstransaksjonen er committet.
require __DIR__.'/vendor/autoload.php';
$mail_conf = [
    'env' => 'production',
    'from_email' => 'ordre@example.org',
    'from_name' => 'Eksempelbutikken',
    'postmark' => [
        'server_token' => getenv('POSTMARK_SERVER_TOKEN'),
        'stream_transactional' => 'outbound',
        'timeout' => 10,
    ],
    'smtp' => [
        'host' => getenv('SMTP_HOST'),
        'port' => 587,
        'encryption' => 'tls',
        'username' => getenv('SMTP_USERNAME'),
        'password' => getenv('SMTP_PASSWORD'),
        'timeout' => 10,
    ],
];
email_routes_configure($mysqli, $mail_conf);
$result = email_transactional(null, $customerEmail, $subject, $html, opt: [
    'template' => 'order_confirmation', 'ref_type' => 'order', 'ref_id' => $orderId,
]);
$customerNotice = \Steinhaug\EmailRoutesHq\MailAdmin::userMessage('checkout', $result->code);

Bruk en verifisert avsender i Postmark. I produksjon bruker email_dispatch SMTP. I et oppsett med Postmark-token bruker email_transactional Postmark og category => 'internal' krever en konfigurert postmark.stream_internal. I et rent SMTP-oppsett går transaksjonsmeldinger via SMTP. Etter initialisering loggføres manglende transport eller strøm som CONFIG_MISSING. Etter et sendeforsøk avsluttes kallet med transportens resultat.

Nyhetsbrev fra EasyWebshop

Kjør migrations/001-broadcast-category.sql ved oppgradering fra skjemaet med sperret broadcast. Nye installasjoner bruker schema.sql. Sett postmark.stream_broadcast til ID-en for kundens Postmark Broadcast-strøm med avmeldingshåndtering. Kall funksjonen fra nyhetsbrevjobben én gang per mottaker. Les gjeldende abonnementsstatus i webshopens database før hvert kall.

$result = email_broadcast(null, $email, $subject, $html, opt: [
    'template' => 'newsletter', 'ref_type' => 'campaign', 'ref_id' => $campaignId,
    'subscribed' => $hasActiveSubscription,
]);

subscribed må være boolsk true. Samme kampanje og mottaker dedupliseres ved ny kjøring. Utviklingsmodus lagrer EML. I et rent SMTP-oppsett går også nyhetsbrev via SMTP. Med Postmark-token krever broadcast både konfigurert SMTP og en egen Postmark Broadcast-strøm. Egen kvote settes med limits.broadcast_hour og limits.broadcast_day (standard 300 og 2000). EasyWebshop må selv planlegge utsendelsen, håndtere RATE_LIMITED og synkronisere avmeldinger til sitt abonnentregister.

Sendefunksjonene beholder parameterrekken from, to, subject, body, is_html, attachments, altBody, headers, postmark, opt. Det gamle flagget postmark beholdes for posisjonskompatibilitet. Transportmatrisen styrer valget. Et adressepar har formatet [adresse, visningsnavn]. Bruk opt['reply_to'] for svaradresse. Vedlegg støtter file (path, name), string (data som rå byte, name) og inline (filename, cid). Bruk betrodde vedleggsstier og metadata. Ekstra headere kan være X-headere, List-ID, Precedence eller Auto-Submitted innenfor transportens validering.

Oppgi et stabilt malnavn på hvert kall. Gamle kallere som forventer null eller feiltekst, kan migreres til email_dispatch_legacy. Wrapperen bruker malnavnet legacy_dispatch inntil kalleren oppgir et eget. Uten forretningsreferanse kan to ulike meldinger med samme mal til samme mottaker bli regnet som duplikater.

Volumvern og feil

Konfigurer positive heltall under limits. Standard er dedupe_minutes=5, recipient_hour=20, ip_hour=5, installation_hour=300 og installation_day=2000. Alle forsøk som får sendetillatelse teller mot kvotene, også ved leverandørfeil. En fastlåst eller ukjent sending kan kreve manuell vurdering. Sett user_triggered => true for kontaktskjema, GDPR og glemt passord. Bruk en fast mal uten fritekst fra innsenderen. Begrensningen bruker serverens REMOTE_ADDR. Konfigurer eventuell betrodd proxy i webserveren.

Med env => 'dev' skriver modulen MIME-meldinger til en eksisterende privat katalog angitt i dev_dir. Oppgi også webroot når vertens dokumentrot ikke er synlig i CLI. Utvikling bør bruke egen database slik at utviklingstrafikk har egne kvoter og duplikatnøkler. Databasefeil før reservasjon gir INTERNAL_ERROR uten loggreferanse. Ved usikkerhet etter reservasjon gis SEND_UNKNOWN. Undersøk historikken før manuell resending.

Admin og daglig vedlikehold

Prosjektets egen loggleser ligger i public_html/index.php. Start den lokalt med php -S 127.0.0.1:8972 -t public_html og åpne http://127.0.0.1:8972/. Under en ordinær webserver må denne katalogen være dokumentrot og webserveren må begrense tilgang til administratorer via autentisering med REMOTE_USER. Loggleseren bruker GET, viser 50 rader om gangen og lar deg filtrere på e-posttype, status, mal og forretningsreferanse.

Prosjektets eksempler og CLI-verktøy leser credentials.php via mail-bootstrap.php. Malen _credentials.php viser MySQL-, avsender-, SMTP- og Postmark-innstillingene. Den lokale credentials.php ligger utenfor dokumentroten public_html og er utelatt fra Git og pakkearkiver. Opprett katalogen i dev_dir for lokal EML-test med env => 'dev'.

Easy Webshop-eksempelet består av public_html/admin/email-log.php og public_html/admin/__shell_template.php. Legg begge i vertens adminkatalog. Vertens func.inc.php laster Composer og leverer $mysqli og eventuelt $mail_conf. Åpne email-log.php som innlogget administrator for å se de siste feilene, varsler og sendeloggen. For integrasjoner som tilbyr sending eller reaktivering, kontroller administratorrettighetene også for POST og bruk en tilfeldig CSRF-nøkkel per adminsesjon.

$admin = new \Steinhaug\EmailRoutesHq\MailAdmin($mysqli);
$_SESSION['mail_csrf'] ??= bin2hex(random_bytes(32));
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_POST['mail_action'])) {
    $flash = $admin->handle($_POST, $_SESSION['mail_csrf'], $sendTest, $resend);
    // Lagre flashmeldingen og omdiriger etter vertssystemets vanlige POST-flyt.
} else {
    $admin->render($mail_conf, $_GET, $_SESSION['mail_csrf']);
}
$orderHistory = $admin->history(['ref_type' => 'order', 'ref_id' => $orderId]);

$sendTest() sender en testmal til installasjonens avtalte testmottaker og returnerer MailResult. $resend($row, $opt) gjenoppbygger meldingen fra vertens forretningsdata og bruker opprinnelig funksjon, mal, mottaker, referanse og eventuell egen dedupe-nøkkel. Send videre force_resend og resend_of fra panelet. Kun betrodd adminkode skal kunne sette disse feltene. Meldingstekst og emne lagres aldri for resending.

Kjør php bin/mail-maintain.php daglig i hver installasjon. Du kan oppgi en egen bootstrapfil som argument. Bootstrapfilen returnerer en array med db (MySQLi-forbindelse), og eventuelt anonymize_days og delete_months. Standard er anonymisering etter 90 dager og sletting av loggrader etter 24 måneder. Beskriv behandlingen i vertens personvernerklæring. Begrens tilgang til utviklingskatalogen og slett testmeldinger når de ikke lenger trengs.

Verifikasjon

Kjør php public_html/mailtest.each.php etter installasjon. Den bruker én vanlig tekstmelding per sendefunksjon til steinhaug@gmail.com og skriver status, transport og eventuell loggreferanse. Med env => 'dev' lagres tre EML-filer. Med produksjonsoppsettet kontaktes transportørene.

bin/mail-install.php og public_html/mailtest.each.php tar også en valgfri sti til en PHP-bootstrapfil. Filen returnerer ['db' => $mysqli, 'mail' => $mail_conf]. Installatøren bruker bare db, og kan kjøres på nytt med samme skjema. Bruk migrasjonen over ved oppgradering fra det eldre skjemaet.

Kjør php tests/transport.php, php tests/dispatch.php og php tests/concurrency.php. MySQL-testene bruker MAIL_TEST_MYSQL_PORT på localhost og eventuelt MAIL_TEST_MYSQL_USER og MAIL_TEST_MYSQL_PASSWORD. Hver test oppretter og fjerner sitt eget tilfeldig navngitte skjema. Testene bruker syntetiske meldinger uten ekstern e-postutsending.

Referansebundne meldinger beholder en separat duplikatkvittering med nøkkelhash, mottakerhash og logg-ID etter at detaljloggen utløper. Det gjør at en gammel ordre fortsatt kan gjenkjennes. Ta også denne lagringen med i vertens beskrivelse av databehandlingen.