‏Postcodes for Laravel: کار با کدپستی‌های بریتانیا تو لاراول

Postcodes for Laravel یه کلاینت لاراولی برای GB Postcodes API هست که Joshua Dovey ساخته. تو این مقاله از Laravel News اومده که خروجی‌ش به‌جای آرایه، آبجکت‌های تایپ‌دار (یعنی کلاس‌هایی با فیلد و متد مشخص) هست. اگه قبلاً از wrapper لاراول برای Postcodes.io استفاده کرده باشی، این یکی به یه سرویس دیگه وصل می‌شه و دادهٔ مرزها و جمعیت رو هم داره.

متد get() یه آبجکت Postcode برمی‌گردونه. اگه کدپستی پیدا نشه null می‌ده، ولی getOrFail() یه NotFoundException پرت می‌کنه:

use JoshDovey\Postcodes\Facades\Postcodes;

$postcode = Postcodes::get('M16 0RA');

$postcode?->latitude();
$postcode?->geography->localAuthorityName;

آبجکت geography شامل تقسیمات اداری مثل حوزه‌های انتخاباتی پارلمان، مناطق NHS و حوزهٔ پلیس هست. آمار سرشماری و تخمین جمعیت هم در دسترسه. برای فرم‌ها، autocomplete() با یه کدپستی ناقص یه collection از گزینه‌ها برمی‌گردونه و search() تا ۱۰۰ کدپستی رو تو یه درخواست جواب می‌ده.

قانون ValidPostcode چک می‌کنه کدپستی واقعاً تو دیتاست هست، نه اینکه فقط شکلش درست باشه. unit() یعنی کدپستی باید کامل باشه:

$request->validate([
    'postcode' => ['required', ValidPostcode::unit()],
]);

مقداری که شکلش غلطه بدون درخواست به API رد می‌شه. یه نکتهٔ مهم: اگه API خطا بده، به‌صورت پیش‌فرض مقدار قبول می‌شه. برای رد کردنش باید strict() رو صدا بزنی یا postcodes.validation.strict رو تو کانفیگ true کنی.

برای محدودهٔ ارسال یا حوزهٔ خدمات، radius() کدپستی‌های نزدیک رو پیدا می‌کنه و within() یه چندضلعی GeoJSON می‌گیره. فاصله پیش‌فرض کیلومتره و مایل هم داره. جواب‌های موفق یه روز کش می‌شن و خطاهای موقت مثل timeout دو بار تکرار می‌شن، ولی تموم شدن سهمیهٔ پلن دوباره امتحان نمی‌شه. برای تست هم Postcodes::fake() جواب‌های ساختگی می‌ده و درخواست‌ها رو ثبت می‌کنه تا با assertSent چکشون کنی.

نکات کلیدی:

• نیاز به PHP 8.2 به بالا و Laravel 12 یا 13 داره و با composer require joshdovey/postcodes نصب می‌شه
• کلید API با متغیر POSTCODES_API_KEY تنظیم می‌شه
• search() تا ۱۰۰ کدپستی رو تو یه درخواست جواب می‌ده
• ValidPostcode وجود واقعی کدپستی رو چک می‌کنه و حالت strict هم داره
• کش پیش‌فرض یه روزه و خطاهای موقت دو بار دوباره امتحان می‌شن
• با withoutBoundaries() می‌شه دادهٔ مرزها رو از جواب حذف کرد و حجمش رو کم کرد