Symfony: Usavršite uvoz za bilten uz AI provjeru adresa e-pošte i ručnu obradu
Uvoz pretplatnika na newsletter može izgledati uspješno, a pritom neprimjetno pogoršati kvalitetu popisa za slanje. Očite tipografske pogreške lako je ukloniti. Teže je postupiti s adresama koje djeluju uvjerljivo: domena postoji, infrastruktura za poštu odgovara, a rizik pri dostavi i dalje je neizvjestan.
Ova aplikacija Symfony pretvara CSV u tri jasno odvojena rezultata: očišćene kontakte, odbijene kontakte i red za ručni pregled. Provjera adresa e-pošte pruža podatke; vaša aplikacija odlučuje što ti podaci dopuštaju. Prekid rada usluge nikada ne smije dovesti do toga da neprovjerena adresa bude odobrena za pretplatu.
Pristupite usluzi i konfigurirajte token usluge
- Registrirajte račun ili se prijavite.
- Otvorite stranicu usluge Email Validator i njezinih paketa, odaberite dostupni paket Free, Plus ili Pro i dovršite aktivaciju.
- Otvorite službenu dokumentaciju. Pronađite ploču Service token i kopirajte token namijenjen toj usluzi.
- Pohranite ga u konfiguraciju okruženja svojeg projekta. Ponovno generiranje tog tokena opoziva prethodni aktivni token pa je pri zamjeni potrebno uskladiti ažuriranja aplikacije.
Za ovu je uslugu potreban token. Točan je zahtjev GET https://ai.mihajlo.mk/api/email-validator/v1/check-email, s parametrima upita token i email. Minimalni zahtjev izgleda ovako; zamjenski tekst zamijenite samo u sigurnom okruženju:
curl --get 'https://ai.mihajlo.mk/api/email-validator/v1/check-email' \
--data-urlencode 'token=YOUR_SERVICE_TOKEN' \
--data-urlencode '[email protected]'
Odgovor sadrži status, score, recommendation, checks i podatke o kvoti. Nemojte pretpostavljati nedokumentirane vrijednosti statusa, ljestvice bodovanja, nazive provjera ili značenje podataka o kvoti. Prije uključivanja automatskog prihvaćanja proučite dokumentaciju.
Izradite jednostavan Symfony uvoznik s ograničenjima
Upotrijebite PHP 8.3 ili noviji, Composer i Symfony 7.4. Ova se implementacija izvršava sinkrono putem konzole, što je razuman kompromis za administrativne uvoze ograničenog opsega. Messenger bi povećao operativnu složenost bez poboljšanja ovog konkretnog postupka.
composer create-project symfony/skeleton:"7.4.*" newsletter-import
cd newsletter-import
composer require symfony/http-client:"7.4.*" symfony/monolog-bundle:"^3.10"
composer require --dev phpunit/phpunit:"^11.5"
Prije izrade funkcionalnosti dodajte pristupni podatak u .env.local:
EMAIL_VALIDATOR_TOKEN=YOUR_SERVICE_TOKEN
Nemojte uključivati tu datoteku u sustav za kontrolu verzija. U produkciji bi se ista varijabla trebala prosljeđivati putem upravitelja tajni. Projektu se dodaju src/EmailVerifier.php, src/Command/ImportContacts.php, config/email-policy.json i tests/EmailVerifierTest.php.
Izradite datoteku s pravilima sa sadržajem {"accept":[],"reject":[]}. Time se namjerno započinje u načinu rada s pregledom. Svako odobreno pravilo mora sadržavati točne vrijednosti za status, recommendation i checks te numeričke granice rezultata min i max. Unesite ih na temelju provjerene dokumentacije i reprezentativnih odgovora; granice se određuju prema stvarnoj ljestvici bodovanja usluge.
Zahtjev za točnim podudaranjem provjera konzervativan je pristup: novi ili promijenjeni podaci vraćaju se na pregled. Podaci o kvoti također moraju biti prisutni i ne smiju imati vrijednost null da bi automatska odluka bila moguća. Zadržavamo njihovu punu vrijednost za pregled, bez izmišljanja polja za preostalu kvotu.
Dodajte ove unose ispod postojećeg ključa services: u datoteci config/services.yaml:
App\EmailVerifier:
arguments:
$token: '%env(EMAIL_VALIDATOR_TOKEN)%'
$policyPath: '%kernel.project_dir%/config/email-policy.json'
App\Command\ImportContacts:
arguments:
$projectDir: '%kernel.project_dir%'
Oprezno postupajte na granici HTTP komunikacije
Provjera prvo lokalno provjerava sintaksu, a zatim upotrebljava Symfonyjev ubrizgani HttpClientInterface. Vremensko ograničenje neaktivnosti od tri sekunde obuhvaća zastoje pri povezivanju i čitanju; ukupno trajanje od osam sekundi ograničava svaki pokušaj. Ponovno se pokušava samo nakon pogrešaka u prijenosu i odabranih privremenih HTTP pogrešaka.
<?php
// src/EmailVerifier.php
namespace App;
use Psr\Log\LoggerInterface;
use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;
final class EmailVerifier
{
private array $policy;
private ?string $blocked = null;
public function __construct(
private HttpClientInterface $http,
private LoggerInterface $logger,
private string $token,
string $policyPath,
) {
$this->policy = json_decode(
file_get_contents($policyPath), true, 512, JSON_THROW_ON_ERROR
);
}
public function fingerprint(): string
{
return hash('sha256', json_encode($this->policy, JSON_THROW_ON_ERROR));
}
private function result(string $decision, string $reason, array $evidence = []): array
{
return compact('decision', 'reason', 'evidence');
}
public function check(string $email): array
{
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
return $this->result('reject', 'local_syntax');
}
if ($this->blocked !== null) {
return $this->result('review', $this->blocked);
}
for ($attempt = 0; $attempt < 3; ++$attempt) {
$status = 0;
$retryAfter = null;
try {
$response = $this->http->request('GET',
'https://ai.mihajlo.mk/api/email-validator/v1/check-email', [
'query' => ['token' => $this->token, 'email' => $email],
'timeout' => 3,
'max_duration' => 8,
'max_redirects' => 0,
]);
$status = $response->getStatusCode();
if ($status === 200) {
try {
$data = json_decode(
$response->getContent(false), true, 512,
JSON_THROW_ON_ERROR
);
} catch (\JsonException) {
return $this->result('review', 'invalid_json');
}
return $this->map($data);
}
$retryAfter = $response->getHeaders(false)['retry-after'][0] ?? null;
$response->cancel();
} catch (TransportExceptionInterface) {
// Never log the exception: it may contain the credential-bearing URL.
}
$this->logger->warning('email_verification_failed', [
'http_status' => $status,
'attempt' => $attempt + 1,
]);
$temporary = in_array($status, [0, 429, 502, 503, 504], true);
$delay = 0.1 * (2 ** $attempt);
if ($status === 429) {
// Retry only a short, explicit integer Retry-After.
if (!is_string($retryAfter) || !ctype_digit($retryAfter)
|| (int) $retryAfter > 2) {
$temporary = false;
} else {
$delay = (float) $retryAfter;
}
}
if (!$temporary || $attempt === 2) {
$reason = $status === 429 ? 'rate_limited' : 'verification_unavailable';
if (in_array($status, [0, 401, 403, 429, 502, 503, 504], true)) {
$this->blocked = $reason;
}
return $this->result('review', $reason);
}
usleep((int) ($delay * 1_000_000) + random_int(0, 50_000));
}
throw new \LogicException('Unreachable');
}
private function map(mixed $data): array
{
if (!is_array($data)) {
return $this->result('review', 'invalid_contract');
}
$evidence = array_intersect_key($data, array_flip([
'status', 'score', 'recommendation', 'checks', 'quota',
]));
if (!is_string($data['status'] ?? null)
|| !is_string($data['recommendation'] ?? null)
|| !(is_int($data['score'] ?? null) || is_float($data['score'] ?? null))
|| !is_finite((float) $data['score'])
|| !is_array($data['checks'] ?? null)
|| !isset($data['quota'])) {
return $this->result('review', 'invalid_contract', $evidence);
}
// Reject wins if configuration accidentally contains overlapping rules.
foreach (['reject', 'accept'] as $decision) {
foreach ($this->policy[$decision] ?? [] as $rule) {
if (($rule['status'] ?? null) === $data['status']
&& ($rule['recommendation'] ?? null) === $data['recommendation']
&& ($rule['checks'] ?? null) === $data['checks']
&& is_numeric($rule['min'] ?? null)
&& is_numeric($rule['max'] ?? null)
&& $data['score'] >= $rule['min']
&& $data['score'] <= $rule['max']) {
return $this->result($decision, 'policy_match', $evidence);
}
}
}
return $this->result('review', 'uncertain', $evidence);
}
}
Nakon neuspjele autentifikacije nikada se ne pokušava ponovno. Odgovor koji upućuje na ograničenje broja zahtjeva, bez kratkog primjenjivog vremena čekanja, zaustavlja daljnje udaljene pozive za taj proces; preostali kontakti šalju se na pregled. Vrijednosti koje nedostaju u odgovoru ili su neočekivanog tipa također se šalju na pregled. Ako je u dokumentaciji usluge naveden drukčiji prikaz kvote, prilagodite ovu jedinstvenu točku obrade i njezine testove.
Objavite potpune rezultate uvoza
Zaglavlje ulazne datoteke mora biti točno email,consent_reference. Referenca na privolu upućuje na vaš postojeći zapis o dopuštenju; sama njezina prisutnost ne dokazuje postojanje privole. Provjera nikada ne daje dopuštenje za slanje.
Naredba ograničava ulaz na 1.000 kontakata i dva megabajta, uklanja duplikate potpuno jednakih adresa i objavljuje tri JSONL datoteke preimenovanjem dovršenog privremenog direktorija. JSONL ujedno smanjuje potrebu da osoblje otvara nepouzdane vrijednosti adresa e-pošte izravno kao formule u proračunskoj tablici.
<?php
// src/Command/ImportContacts.php
namespace App\Command;
use App\EmailVerifier;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
#[AsCommand(name: 'app:import-contacts')]
final class ImportContacts extends Command
{
public function __construct(
private EmailVerifier $verifier,
private string $projectDir,
) {
parent::__construct();
}
protected function configure(): void
{
$this->addArgument('csv', InputArgument::REQUIRED);
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$base = $this->projectDir.'/var/imports';
if (!is_dir($base) && !mkdir($base, 0700, true)) {
throw new \RuntimeException('Cannot create import directory');
}
$lock = fopen($base.'/.lock', 'c');
if (!$lock || !flock($lock, LOCK_EX | LOCK_NB)) {
throw new \RuntimeException('Another import is running');
}
try {
$bytes = file_get_contents($input->getArgument('csv'), false, null, 0, 2_000_001);
if ($bytes === false || strlen($bytes) > 2_000_000) {
throw new \RuntimeException('Unreadable or oversized CSV');
}
$stream = fopen('php://temp', 'w+');
fwrite($stream, $bytes);
rewind($stream);
if (fgetcsv($stream, 0, ',', '"', '') !== ['email', 'consent_reference']) {
throw new \RuntimeException('Unexpected CSV header');
}
$rows = [];
while (($row = fgetcsv($stream, 0, ',', '"', '')) !== false) {
if (count($row) !== 2 || count($rows) >= 1000) {
throw new \RuntimeException('Invalid row or contact limit exceeded');
}
$rows[] = $row;
}
fclose($stream);
// Bump v1 when decision logic changes.
$id = hash('sha256', 'v1'.$bytes.$this->verifier->fingerprint());
$target = $base.'/'.$id;
if (is_dir($target)) {
$output->writeln('Already published: '.$id);
return Command::SUCCESS;
}
$stage = $target.'.tmp.'.bin2hex(random_bytes(6));
if (!mkdir($stage, 0700)) {
throw new \RuntimeException('Cannot create staging directory');
}
$counts = ['accept' => 0, 'review' => 0, 'reject' => 0];
foreach (['clean', 'review', 'reject'] as $name) {
if (file_put_contents($stage.'/'.$name.'.jsonl', '') === false) {
throw new \RuntimeException('Cannot initialize output');
}
}
$seen = [];
foreach ($rows as [$email, $consent]) {
$email = trim($email);
if (isset($seen[$email])) {
continue;
}
$seen[$email] = true;
$result = trim($consent) === ''
? ['decision' => 'review', 'reason' => 'missing_consent_reference',
'evidence' => []]
: $this->verifier->check($email);
$record = ['email' => $email, 'consent_reference' => $consent] + $result;
$name = $result['decision'] === 'accept' ? 'clean' : $result['decision'];
$line = json_encode($record, JSON_THROW_ON_ERROR)."\n";
if (file_put_contents($stage.'/'.$name.'.jsonl', $line, FILE_APPEND)
!== strlen($line)) {
throw new \RuntimeException('Incomplete output write');
}
++$counts[$result['decision']];
}
if (!rename($stage, $target)) {
throw new \RuntimeException('Cannot publish import');
}
$output->writeln(json_encode(['import' => $id] + $counts, JSON_THROW_ON_ERROR));
return Command::SUCCESS;
} finally {
flock($lock, LOCK_UN);
fclose($lock);
}
}
}
Osobe zadužene za pregled pregledavaju review.jsonl, provjeravaju izvorni zapis o privoli i u sustavu za upravljanje pretplatnicima bilježe izričito odobrenje, odbijanje ili ispravak. Ispravljeni podaci ponovno prolaze provjeru. Samo se clean.jsonl upotrebljava za automatsko dodavanje pretplatnika, pri čemu bi se pravila o privoli i isključivanju trebala provoditi i neovisno o toj datoteci.
Testirajte odluke bez vanjskih zahtjeva
Ove testne vrijednosti sintetičke su; nisu enumeracijske vrijednosti usluge ni tvrdnja o njezinoj ljestvici bodovanja. Testovi provjeravaju prihvaćanje, oprezno postupanje u neizvjesnim slučajevima i neuspjelu autentifikaciju bez ponovnog pokušaja.
<?php
// tests/EmailVerifierTest.php
namespace App\Tests;
use App\EmailVerifier;
use PHPUnit\Framework\TestCase;
use Psr\Log\NullLogger;
use Symfony\Component\HttpClient\MockHttpClient;
use Symfony\Component\HttpClient\Response\MockResponse;
final class EmailVerifierTest extends TestCase
{
public function testDecisions(): void
{
$path = tempnam(sys_get_temp_dir(), 'email-policy-');
$rule = ['status' => 'fixture-ok', 'recommendation' => 'fixture-allow',
'checks' => ['fixture' => true], 'min' => 7, 'max' => 9];
file_put_contents($path, json_encode(['accept' => [$rule], 'reject' => []]));
try {
$body = ['status' => 'fixture-ok', 'recommendation' => 'fixture-allow',
'score' => 8, 'checks' => ['fixture' => true], 'quota' => ['fixture' => 4]];
foreach ([
[$body, 200, 'accept'],
[array_replace($body, ['status' => 'unknown']), 200, 'review'],
[array_diff_key($body, ['quota' => true]), 200, 'review'],
[$body, 401, 'review'],
] as [$payload, $status, $expected]) {
$calls = 0;
$http = new MockHttpClient(function () use (&$calls, $payload, $status) {
++$calls;
return new MockResponse(json_encode($payload), ['http_code' => $status]);
});
$verifier = new EmailVerifier($http, new NullLogger(), 'TEST_TOKEN', $path);
self::assertSame($expected, $verifier->check('[email protected]')['decision']);
self::assertSame(1, $calls);
}
} finally {
unlink($path);
}
}
}
Postavite, nadzirite i provjerite
Pokrenite postupak pod korisničkim računom s restriktivnim umaskom, privatnim prostorom za pohranu u koji je dopušteno pisanje i isključenim otklanjanjem pogrešaka u produkciji. Privremeni i završni direktorij držite na istom lokalnom datotečnom sustavu; ovaj način zaključavanja pretpostavlja da aplikacija radi na jednom poslužitelju. Uvoze rasporedite tako da se izvršavaju jedan za drugim.
vendor/bin/phpunit tests
umask 077
APP_ENV=prod APP_DEBUG=0 php bin/console cache:clear
APP_ENV=prod APP_DEBUG=0 php bin/console app:import-contacts contacts.csv
Dnevnici prikazuju HTTP status i broj pokušaja; izlaz naredbe prikazuje zbirne podatke o odlukama. Postavite upozorenja za porast broja kontakata na pregledu i neuspjelih autentifikacija. Budući da se za autentifikaciju upotrebljava parametar upita, isključite profiliranje u produkciji i uklonite osjetljive podatke iz URL-ova odlaznih zahtjeva u HTTP dijagnostici, posredničkim poslužiteljima i sustavima za praćenje.
Prekinuti uvoz za sobom ostavlja neobjavljeni privremeni direktorij. Tijekom održavanja uklonite zastarjele privremene direktorije; ponovno pokretanje može ponoviti provjere koje se naplaćuju. Dovršeni uvozi ponovno se upotrebljavaju na temelju otiska ulaznih podataka i pravila. Zaštitite rezultate kao osobne podatke i primijenite raspored njihova čuvanja.
Uobičajene neočekivane situacije mogu se objasniti: prazna pravila šalju rezultate udaljene provjere na pregled; promijenjena struktura provjera prekida podudaranje; zamjena tokena zahtijeva ponovno pokretanje procesa koji zadržavaju staru konfiguraciju. Sam uspješan HTTP odgovor nikada ne jamči prihvaćanje.
- Pokrenite testove i provjerite da se neispravan CSV odbacuje prije udaljenih poziva.
- Potvrdite da sintaktičke pogreške dovode do odbijanja, a nepoznati podaci do pregleda.
- Simulirajte odgovor 429 i provjerite da se za sljedeće kontakte ne šalju zahtjevi.
- Odobrite dokumentirana pravila prije nego što očekujete očišćene kontakte.
- Potvrdite da se ponovnim pokretanjem objavljenog uvoza ne obavljaju dodatne provjere.
- Provjerite dopuštenja, provedbu pravila o privoli, popise za isključivanje i odgovornost za ručni pregled.
Koristan je rezultat popis na kojem se svaka odluka može objasniti. Očišćeni kontakti prolaze dalje, nedvojbeno neispravni zaustavljaju se, a neizvjesni slučajevi dolaze do osobe koja ih može riješiti.