Symfony: Усовршете ги увозите на претплатници за билтенот со проверка на е-пошта со вештачка интелигенција и рачна обработка
Увозот на билтен може да изгледа успешен, а притоа незабележливо да го влоши квалитетот на листата за испраќање. Очигледните печатни грешки лесно се отстрануваат. Проблематичните адреси изгледаат веродостојно: доменот постои, инфраструктурата за е-пошта одговара, но ризикот при испорака останува неизвесен.
Оваа Symfony апликација го претвора CSV во три јасни резултати: исчистени контакти, одбиени контакти и редица за рачна проверка. Верификацијата на е-поштата обезбедува докази; вашата апликација одлучува што дозволуваат тие докази. Прекин во работата никогаш не смее да претвори непроверена адреса во одобрен претплатник.
Добијте пристап и конфигурирајте го токенот за услугата
- Регистрирајте сметка или најавете се.
- Отворете ја страницата за услугата Email Validator и нејзините планови, изберете еден од достапните планови Free, Plus или Pro и завршете ја активацијата.
- Отворете ја официјалната документација. Најдете го панелот Service token и копирајте го токенот наменет за услугата.
- Зачувајте го во конфигурацијата на околината на вашиот проект. Со повторно генерирање на овој токен се отповикува претходниот активен токен, па затоа замената бара усогласување со ажурирањата на апликацијата.
За оваа услуга е потребен токен. Точното барање е GET https://ai.mihajlo.mk/api/email-validator/v1/check-email, со параметри за пребарување token и email. Минималното барање изгледа вака; заменете го местодржачот само во безбедна околина:
curl --get 'https://ai.mihajlo.mk/api/email-validator/v1/check-email' \
--data-urlencode 'token=YOUR_SERVICE_TOKEN' \
--data-urlencode '[email protected]'
Одговорот содржи status, score, recommendation, checks и податоци за квотата. Не претпоставувајте недокументирани вредности за статусот, скали за оценување, имиња на проверки или значења на податоците за квотата. Консултирајте ја документацијата пред да овозможите автоматско прифаќање.
Создајте мал Symfony увозник со јасни ограничувања
Користете PHP 8.3 или понова верзија, Composer и Symfony 7.4. Оваа имплементација се извршува синхроно преку Console: разумен компромис за административни увози со ограничен обем. Messenger би додал оперативни трошоци без да го подобри овој конкретен работен тек.
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"
Пред да ја изградите функционалноста, додајте го акредитивот во .env.local:
EMAIL_VALIDATOR_TOKEN=YOUR_SERVICE_TOKEN
Не вклучувајте ја таа датотека во системот за контрола на верзии. Во продукција, истата променлива треба да се обезбеди преку системот за управување со тајни. Во проектот се додаваат src/EmailVerifier.php, src/Command/ImportContacts.php, config/email-policy.json и tests/EmailVerifierTest.php.
Создајте ја датотеката со правила со {"accept":[],"reject":[]}. Така намерно се започнува во режим на рачна проверка. Секое одобрено правило мора да содржи точни вредности за status, recommendation и checks, како и нумерички долна граница min и горна граница max за оценката. Пополнете ги врз основа на проверена документација и репрезентативни одговори; границите ја користат вистинската скала за оценување на услугата.
Точното совпаѓање на проверките е претпазлив пристап: новите или променетите докази се испраќаат на проверка. Податоците за квотата исто така мора да бидат присутни и да не се null за да може да се донесе автоматска одлука. Ја задржуваме нивната целосна вредност за проверка, без да измислуваме поле за преостаната квота.
Додајте ги овие записи под постојниот клуч services: во 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%'
Применете претпазлив пристап на HTTP границата
Верификаторот локално ја проверува синтаксата, а потоа го користи вметнатиот Symfony HttpClientInterface. Временското ограничување од три секунди при неактивност ги опфаќа заглавените поврзувања и читања; вкупното времетраење од осум секунди го ограничува секој обид. Се повторуваат само обидите што завршиле со транспортни грешки и одредени привремени HTTP грешки.
<?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);
}
}
Неуспешните обиди за автентикација никогаш не се повторуваат. Одговорот за ограничување на бројот на барања без кратко употребливо време на чекање ги запира понатамошните повици кон услугата за овој процес; преостанатите контакти се испраќаат на проверка. На проверка се испраќаат и одговорите со вредности што недостигаат или се од неочекуван тип. Ако услугата документира друг начин на претставување на квотата, приспособете ја оваа граница и нејзините тестови.
Објавете ги целосните резултати од увозот
Заглавието на влезната датотека мора да биде точно email,consent_reference. Референцата за согласност укажува на вашиот постоен запис за дозвола; самото нејзино присуство не утврдува дека постои согласност. Верификацијата никогаш не дава дозвола за испраќање.
Командата го ограничува влезот на 1.000 контакти и два мегабајта, ги отстранува целосно идентичните дупликатни адреси и објавува три JSONL датотеки со преименување на завршен привремен директориум. JSONL исто така помага да не се поттикнува персоналот да отвора недоверливи вредности за е-пошта директно како формули во табеларни пресметки.
<?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);
}
}
}
Лицата задолжени за проверка ја прегледуваат review.jsonl, го проверуваат оригиналниот запис за согласност и бележат изречно одобрување, одбивање или исправка во системот за претплатници. Исправките повторно поминуваат низ верификација. Само clean.jsonl се користи за автоматско запишување, кое треба независно да ги спроведува правилата за согласност и исклучување.
Тестирајте ги одлуките без надворешни барања
Овие тест-вредности се синтетички и не претставуваат наброени вредности на услугата ниту тврдење за нејзината скала за оценување. Тестовите ги проверуваат прифаќањето, претпазливото постапување кога нема совпаѓање и неуспешната автентикација без повторен обид.
<?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);
}
}
}
Пуштете во продукција, следете и проверете
Извршувајте го процесот преку работна сметка со ограничувачки umask, приватен простор за складирање во кој може да се запишува и исклучено дебагирање во продукција. Привремените и конечните директориуми нека бидат на истиот локален датотечен систем; овој начин на заклучување претпоставува еден домаќин на апликацијата. Закажувајте ги увозите да се извршуваат последователно.
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
Дневниците ги прикажуваат HTTP статусот и бројот на обиди; излезот од командата прикажува збирни податоци за одлуките. Поставете известувања за пораст на бројот на контакти за проверка и за неуспешни автентикации. Бидејќи автентикацијата користи параметар за пребарување, исклучете го профилирањето во продукција и прикривајте ги излезните URL-адреси во HTTP дијагностиката, прокси-серверите и системите за следење.
Прекинатиот увоз остава необјавен привремен директориум. Отстранувајте ги застарените привремени директориуми при одржување; повторното започнување може да ги повтори проверките што се наплаќаат. Завршените увози повторно се користат според отпечатокот на влезните податоци и правилата. Заштитете ги резултатите како лични податоци и применете распоред за нивно задржување.
Вообичаените неочекувани ситуации имаат објаснување: празни правила ги испраќаат резултатите од услугата на проверка; променетата структура на проверките го спречува совпаѓањето; заменетиот токен бара повторно започнување на процесите што ја користат старата конфигурација. Самиот успешен HTTP одговор никогаш не гарантира прифаќање.
- Извршете ги тестовите и проверете дали CSV со неправилен формат предизвикува неуспех пред повиците кон услугата.
- Потврдете дека синтаксичките грешки водат до одбивање, а непознатите докази до проверка.
- Тестирајте симулиран одговор 429 и проверете дали за следните контакти не се испраќаат барања.
- Одобрете ги документираните правила пред да очекувате исчистени контакти.
- Потврдете дека повторното извршување на објавен увоз не прави дополнителни проверки.
- Проверете ги дозволите, спроведувањето на согласноста, листите за исклучување и одговорноста за рачната проверка.
Корисниот резултат е листа чии одлуки можат да се објаснат. Исчистените контакти продолжуваат понатаму, јасните неуспеси се запираат, а неизвесните случаи стигнуваат до место каде што лице може да ги разреши.