Download the PHP package zarbinco/laravel-iran-locations without Composer
On this page you can find all versions of the php package zarbinco/laravel-iran-locations. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download zarbinco/laravel-iran-locations
More information about zarbinco/laravel-iran-locations
Files in zarbinco/laravel-iran-locations
Package laravel-iran-locations
Short Description Iran provinces, cities, neighborhoods, safe sync, and Persian normalization for Laravel.
License MIT
Homepage https://github.com/zarbinco/laravel-iran-locations
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package laravel-iran-locations
Laravel Iran Locations
زبانها: فارسی | English
این پکیج دادههای مکانی ایران را برای پروژههای Laravel آماده میکند؛ از استان و شهرستان تا بخش، دهستان، شهر، منطقه شهری و محله. اگر فقط لیست آماده برای select، API خواندنی یا اعتبارسنجی میخواهید، میتوانید از JSON driver استفاده کنید و هیچ migration یا sync اجرا نکنید. اگر لازم دارید دادهها وارد دیتابیس شوند، رکورد سفارشی داشته باشید، admin CRUD فعال کنید یا با رابطههای Eloquent کار کنید، database driver برای همین سناریو است.
وضعیت انتشار: پکیج هنوز منتشر نشده و برای فاز beta/pre-release آماده میشود. نسخه داده فعلی
0.2.0-devاست. برای release پایدار، وضعیت منبع داده، مجوز بازنشر و کاملبودن دادهها باید جداگانه بررسی شود.
قابلیتها
- دادههای آماده برای استان، شهرستان، بخش، دهستان، شهر، مناطق شهری تهران و محلههای تهران
- دو حالت ذخیرهسازی:
databaseبرای sync و رکوردهای سفارشی، وjsonبرای استفاده read-only بدون migration - کدهای عمومی و پایدار مثل
p.01وs.01.01.01.01بهجای تکیه بر id دیتابیس - نرمالسازی متن فارسی با
zarbinco/laravel-persian-core - sync امن دیتابیس با
--dry-run، حفظ رکوردهای custom و منسوخکردن رکوردهای package که از داده جدید حذف شدهاند - مدلها، رابطههای Eloquent، query builder و فیلترهای آماده
- API خواندنی اختیاری
- Blade component ساده برای selectها، بدون نیاز به JavaScript
- admin UI اختیاری برای حالت database
- تستهای کیفیت داده برای شمارشها، checksum، رابطههای والد/فرزند، متن فارسی و مراکز استانها
نیازمندیها
| Laravel | PHP |
|---|---|
| 11 | PHP 8.2+ |
| 12 | PHP 8.2+ |
| 13 | PHP 8.3+ |
zarbinco/laravel-persian-coreبا نسخه^0.1یا^1.0- اکستنشن PHP
zipفقط برای توسعه خود پکیج و release/archive check لازم است؛ مصرفکننده پکیج برای runtime معمولی به آن نیاز ندارد.
نصب
پکیج بهصورت پیشفرض با database driver بالا میآید:
اگر فقط داده آماده و read-only میخواهید، driver را روی json بگذارید:
انتخاب driver
JSON driver؛ بدون migration
در این حالت پکیج مستقیماً از فایلهای data/*.json داخل package میخواند:
در JSON driver اینها لازم نیست:
- publish کردن migrationهای پکیج
- اجرای
php artisan migrateبرای جدولهای پکیج - اجرای
iran-locations:sync
این حالت برای dropdown، لیستهای خواندنی، API options/search، validation list و پروژههایی مناسب است که نمیخواهند جدول جدید داشته باشند.
محدودیتهای مهم JSON mode:
- read-only است.
- sync ندارد.
- admin CRUD ندارد.
- رکورد custom ندارد.
- رابطههای دیتابیسی Eloquent ندارد.
- مقدار select و API،
codeاست نه database id. - فیلترها و propهای id مثل
province_idیاprovinceIdفقط برایdatabase driverهستند. در JSON mode باید ازprovince_code،city_code،provinceCode،cityCodeو propهای code استفاده کنید.
Cache بین requestها در JSON mode بهصورت پیشفرض خاموش است. اگر خودتان فعال کنید، cache key شامل data version و manifest checksum میشود:
Database driver؛ sync و رکورد سفارشی
در این حالت دادهها وارد جدولهای برنامه میشوند و میتوانید از مدلها، relationها، admin، رکوردهای custom و queryهای دیتابیسی استفاده کنید:
مسیر معمول راهاندازی:
برای بررسی وضعیت:
sync جدولها را truncate نمیکند. رکوردهای source = custom حفظ میشوند. رکوردهای package که دیگر در داده فعلی نیستند، بهصورت پیشفرض deprecated میشوند و hard delete نمیشوند.
نمونه config
استفاده خواندنی با Facade
این API با driver فعلی کار میکند؛ یعنی همین کد هم در JSON mode و هم در database mode قابل استفاده است:
استفاده با read repository
اگر dependency injection را ترجیح میدهید، contract خواندنی پکیج را inject کنید:
متدهای اصلی repository:
all(string $type, array $filters = [])find(string $type, string $code)options(string $type, array $filters = [], ?int $limit = null)search(string $term, array $types = [], ?int $limit = null)
استفاده Eloquent در database mode
مدلهای Eloquent فقط وقتی معنا دارند که دادهها در دیتابیس sync شده باشند:
Blade componentها
Componentها زیر namespace iran-locations ثبت میشوند. مقدار optionها code است:
Propهای code مثل province-code و city-code در هر دو driver کار میکنند. Propهای id مثل province-id فقط برای database mode هستند و در JSON mode نباید برای گرفتن فرزندها استفاده شوند.
API خواندنی
API بهصورت پیشفرض خاموش است. برای فعالسازی:
Endpointها زیر prefix پیشفرض iran-locations/api قرار میگیرند:
API فقط خواندنی است. در JSON mode مقدارها و route parentها بر اساس code هستند. اگر فیلتر database id مثل province_id=1 بفرستید، پاسخ 422 میگیرید و باید فیلتر code متناظر را استفاده کنید.
کدهای عمومی داده
code مقدار عمومی و پایدار پکیج است. این مقدار را در فرمها، URLها، API و تنظیمات خودتان نگه دارید؛ نه id جدول دیتابیس را. idهای دیتابیس محلی هستند و بعد از sync در هر برنامه میتوانند متفاوت باشند.
نمونه کدها:
- استان:
p.01 - شهرستان:
c.01.01 - بخش:
b.01.01.01 - دهستان:
d.01.01.01.01 - شهر:
s.01.01.01.01 - منطقه شهری:
r.01.01.01.01.05 - محله:
n.01.01.01.01.05.001
کدها با scheme کوتاه و fixed-width خود پکیج ساخته شدهاند. مقدارهای شبیه کد در فایلهای منبع بهعنوان source_id نگه داشته میشوند و public code نیستند. چون پکیج هنوز public نشده، کدهای قدیمی pre-release مثل ir.* حفظ نشدهاند و compatibility map هم برای آنها وجود ندارد.
محدوده داده
داده فعلی package شامل این تعداد رکورد است:
- 31 استان
- 484 شهرستان
- 1087 بخش
- 73 دهستان
- 1456 شهر
- 22 منطقه شهری تهران
- 0 ناحیه شهری
- 568 محله یا مکان شهری تهران
- 568 رابطه محله-منطقه
- 0 alias
ساختار رسمی داده شامل استان، شهرستان، بخش، شهر و دهستان است. ساختار شهری جدا نگه داشته شده: منطقه شهری، ناحیه شهری و محله. ناحیه شهری و alias در schema پشتیبانی میشوند، ولی در داده package نسخه 0.2.0-dev فعلاً خالی هستند مگر اینکه برنامه شما رکورد custom اضافه کند.
نامهای فارسی public از ك/ي عربی به ک/ی فارسی نرمال شدهاند. مرکز استانها هم در داده علامتگذاری شدهاند.
شفافیت منبع و مجوز داده
داده package از فایلهای spreadsheet وارد و curate شده است. این پکیج ادعا نمیکند که دادهها همیشه کامل، رسمی، بهروز یا مناسب استفاده حقوقی، لجستیکی، مقرراتی یا حساس هستند.
قبل از استفاده production که به خود داده وابسته است، وضعیت منبع، مجوز بازنشر، نیازهای attribution و کاملبودن دادهها را بررسی کنید:
- DATA-SOURCES.md
- DATA-LICENSE.md
چیزی که فعلاً در scope نیست
- پوشش کامل روستاها
- boundary، routing، postal code یا مختصات کامل
- بهروزرسانی تضمینی روزنامه رسمی یا تقسیمات کشوری
- تضمین مناسببودن برای کاربردهای حقوقی، مقرراتی، لجستیکی یا high-stakes
Admin UI
Admin UI پیشفرض خاموش است و فقط در database driver ثبت میشود:
برای محیط واقعی، routeهای admin را پشت middleware احراز هویت و در صورت نیاز gate برنامه خودتان نگه دارید. بهصورت پیشفرض، ویرایش مستقیم رکوردهای source = package محدود است و رکوردهای custom برای تغییرات برنامه شما در نظر گرفته شدهاند.
تست و release gate
release:check validation، تستها، Pint، PHPStan، ساخت Composer archive و archive hygiene را اجرا میکند.
مستندات بیشتر
- English README
- Data
- Query examples with Tehran city
- Sync
- Admin UI
- API
- Blade components
- Extending
- Consumer smoke test
- Release checklist
- Changelog
License
کد پکیج با مجوز DATA-LICENSE.md را جداگانه بخوانید.
All versions of laravel-iran-locations with dependencies
illuminate/contracts Version ^11.0|^12.0|^13.0
illuminate/database Version ^11.0|^12.0|^13.0
illuminate/routing Version ^11.0|^12.0|^13.0
illuminate/support Version ^11.0|^12.0|^13.0
zarbinco/laravel-persian-core Version ^0.1|^1.0