zarbinco/laravel-persian-core

# Laravel Persian Core [](https://github.com/zarbinco/laravel-persian-core/actions/workflows/tests.yml) [](https://packagist.org/packages/zarbinco/laravel-persian-core) [](https://packagist.org/packages/zarbinco/laravel-persian-core) [](LICENSE.md) [](composer.json) `zarbinco/laravel-persian-core` 是一个用于 Laravel 应用程序的轻量级波斯语/伊朗实用工具基础包。 它负责处理文本规范化、数字转换、手机号规范化、金额辅助工具、验证规则以及离线银行/银行卡/Sheba 检测。它为 Laravel 应用程序提供了一个小巧、低依赖的基础，用于处理常见的波斯语和伊朗输入，而不包含特定的业务功能。 [阅读波斯语版的 README](README.fa.md)。 ## 功能特性 - 波斯语和阿拉伯语文本规范化。 - 波斯语、阿拉伯语和英语数字转换。 - 存储、显示和搜索规范化管道。 - 一流的波斯语搜索规范化，用于索引和查询清理。 - 数字清理、解析和格式化。 - 伊朗手机号规范化和掩码基础。 - Toman/Rial 金额解析、格式化和转换辅助工具。 - 用于常见伊朗/波斯语输入的 Laravel 验证 Rule 对象。 - 通过银行卡 BIN/IIN 值和 Sheba 银行代码进行离线的尽力而为的伊朗银行检测。 - 可发布的配置和翻译文件。 - Artisan 安装、诊断和关于命令。 ## 本包不包含什么 这个核心包特意不包含： - 支付网关、PSP 集成或支付处理。 - 银行验证、所有权检查或实时账户/卡状态检查。 - 发送短信。 - 贾拉利历支持。 - 发票或 PDF 生成。 - 管理面板或 Filament 集成。 - 税务、Modian、会计或簿记工作流。 - 全文搜索引擎、排名系统、词干提取、模糊匹配或 Scout/数据库集成。 - 地址、省或城市数据库。 - 特定业务的验证策略。 ## 验证与规范化 规范化器设计用于清理、格式化、转换以及可预测的存储/显示/搜索输出。某些规范化器可能是宽松的，因为它们对于提取或清理杂乱的用户输入很有用。 验证器是为 Laravel 验证设计的。它们在适用的情况下验证形状、所需的结构和校验和。它们不证明现实世界的所有权、账户存在性、运营商所有权、卡片状态或实时银行状态。 当您需要规范化输出时，请使用规范化器。当您需要拒绝无效输入时，请使用验证规则。当字段必须存在时，请将验证规则与 Laravel 的 `required` 规则结合使用。 ## 银行检测边界 银行/卡/Sheba 检测是离线的且是尽力而为的。它使用本地元数据进行伊朗卡 BIN/IIN 值和 Sheba 银行代码检测，未知银行返回 `null`。 银行检测不证明： - 账户所有权。 - 账户存在性。 - 卡所有权。 - 卡状态。 - 卡到账户的可转换性。 - 银行是否仍在积极发行或接受特定标识符。 需要验证时，请使用 `IranianCardNumber` 和 `IranianSheba` 验证规则。即便如此，验证也仅限于适用情况下的格式和校验和检查，而不是实时银行验证。 ## 兼容性 兼容性基于 `composer.json`： - PHP `^8.2`。 - Laravel 组件 `^11.0`、`^12.0` 或 `^13.0`。 - 包发现机制会自动注册服务提供者和 Facade。 - 许可证：MIT。 ## 安装说明 ``` composer require zarbinco/laravel-persian-core ``` Laravel 包发现机制会自动注册服务提供者和 Facade。 ## 发布 发布包配置： ``` php artisan vendor:publish --tag=persian-core-config ``` 发布验证翻译： ``` php artisan vendor:publish --tag=persian-core-lang ``` 或者使用包安装程序同时发布两者： ``` php artisan persian-core:install ``` 当您有意要覆盖之前发布的文件时，请使用 `--force`。 ## 快速用法 ``` use Zarbinco\PersianCore\Facades\Persian; Persian::text('علي كاظمي')->normalize(); // علی کاظمی Persian::number('۱۲۳٤٥۶')->toEnglish(); // 123456 Persian::clean('علي كاظمي شماره ۰۹۱۲۱۲۳۴۵۶۷'); // علی کاظمی شماره 09121234567 Persian::normalize('علي كاظمي شماره 09121234567')->forDisplay(); // علی کاظمی شماره ۰۹۱۲۱۲۳۴۵۶۷ Persian::mobile('۰۹۱۲ ۱۲۳ ۴۵۶۷')->international(); // +989121234567 Persian::money(1250000)->format(); // ۱,۲۵۰,۰۰۰ تومان ``` ## 文本 文本规范化将阿拉伯语的 Yeh 和 Kaf 转换为波斯语的 Yeh 和 Kaf，删除阿拉伯语变音符号和 Tatweel，删除有问题的不可见字符同时保留 ZWNJ，并规范化空格。 ``` Persian::text('علي كاظمي')->normalize(); // علی کاظمی Persian::text('سلام ، علی ! خوبی ؟')->forDisplay(); // سلام، علی! خوبی؟ Persian::text('می‌روم')->forSearch(); // می روم ``` `normalize()` 和仅处理文本的 `forStorage()` 保持保守。`forDisplay()` 应用适合显示的标点符号清理。`forSearch()` 应用更激进的搜索规范化，例如标点符号移除和可配置的 ZWNJ 处理。 ## 数字 数字规范化器专注于数字转换。数字解析辅助工具清理格式化的输入以供数字使用。 ``` Persian::number('۱۲۳٤٥۶')->toEnglish(); // 123456 Persian::number('123456')->toPersian(); // ۱۲۳۴۵۶ Persian::number('۱,۲۵۰,۰۰۰')->clean(); // 1250000 Persian::number('abc ۱۲۳ def')->digitsOnly(); // 123 Persian::number('۱۲٫۵')->toFloat(); // 12.5 Persian::number('۱۲۳۴۵۶۷')->format(); // ۱,۲۳۴,۵۶۷ Persian::number('۱۲۳۴۵۶۷')->format('en'); // 1,234,567 ``` ## 规范化管道 `Persian::clean()` 是存储规范化的别名。存储和显示的数字输出由配置驱动。 ``` Persian::normalize('علي كاظمي شماره ۰۹۱۲۱۲۳۴۵۶۷')->forStorage(); // علی کاظمی شماره 09121234567 Persian::normalize('علي كاظمي شماره 09121234567')->forDisplay(); // علی کاظمی شماره ۰۹۱۲۱۲۳۴۵۶۷ Persian::normalize('علي مبلغ ۱,۲۵۰,۰۰۰ تومان')->forSearch(); // علی مبلغ 1250000 تومان ``` ## 搜索规范化 搜索规范化为索引和用户查询匹配准备确定性的文本。它规范化波斯语/阿拉伯语字母变体，删除变音符号和 Tatweel，根据配置处理 ZWNJ，将波斯语和阿拉伯语数字转换为英语，默认情况下删除标点符号，并折叠数字组。 ``` Persian::search('كیكِ شکلاتي')->normalize(); // کیک شکلاتی Persian::search('آب‌میوه سن‌ایچ ۱۲,۵۰۰ تومان!')->normalize(); // اب میوه سن ایچ 12500 تومان Persian::search('آب‌میوه سن‌ایچ')->tokens(); // ['اب', 'میوه', 'سن', 'ایچ'] ``` `Persian::searchable($value)` 作为直接的字符串辅助工具保留，并使用相同的搜索规范化器： ``` $model->searchable_name = Persian::search($model->name)->normalize(); $model->save(); $query = Persian::search($request->input('q'))->normalize(); Product::query() ->where('searchable_name', 'like', "%{$query}%") ->get(); ``` 这是用于搜索/索引的规范化。它不是全文搜索引擎、词干提取系统、音译层、模糊匹配器、Scout 集成或特定于数据库的排名工具。 ## 手机号 手机号辅助工具规范化伊朗手机号码，并将其格式化为国内或国际形式。 ``` Persian::mobile('۰۹۱۲ ۱۲۳ ۴۵۶۷')->normalize(); // 09121234567 Persian::mobile('+989121234567')->national(); // 09121234567 Persian::mobile('09121234567')->international(); // +989121234567 Persian::mobile('09121234567')->e164(); // +989121234567 Persian::mobile('09121234567')->mask(); // 0912***4567 ``` 可以通过 `mobile.iran.mask_pattern` 更改默认掩码。无效掩码将安全回退到 `0912***4567`。 ## 金额 金额辅助工具解析和格式化 Toman/Rial 值。它们不是会计、税务、发票或支付工具。 ``` Persian::money('۱,۲۵۰,۰۰۰ تومان')->value(); // 1250000 Persian::money('۱۲,۵۰۰,۰۰۰ ریال')->detectedCurrency(); // rial Persian::money(1250000)->format(); // ۱,۲۵۰,۰۰۰ تومان Persian::money(1250000)->format('toman', 'en'); // 1,250,000 toman Persian::money(12500000)->fromRial()->toToman(); // 1250000 Persian::money(1250000)->fromToman()->toRial(); // 12500000 ``` 默认转换率为 `1 toman = 10 rial`，可以通过 `money.rial_to_toman_rate` 更改。 ## 银行检测 银行检测通过伊朗卡 BIN/IIN 值和 Sheba 银行代码提供尽力而为的元数据。它仅限离线，不调用外部服务，未知银行返回 `null`。 ``` $bank = Persian::card('6037991234567890')->bank(); $bank?->toArray(); // [ // 'slug' => 'melli', // 'name' => 'Bank Melli Iran', // 'name_fa' => 'بانک ملی ایران', // 'card_bins' => ['603799'], // 'sheba_codes' => ['017'], // ] Persian::card('6037991234567890')->bankSlug(); // melli Persian::sheba('IR170170000000000000000000')->bankNameFa(); // بانک ملی ایران ``` 当您只需要银行对象时，可以使用直接辅助工具： ``` Persian::bankFromCard('۶۰۳۷۹۹ ۱۲۳۴ ۵۶۷۸ ۹۰۱۲')?->slug(); // melli Persian::bankFromSheba('ir170170000000000000000000')?->name(); // Bank Melli Iran ``` 银行检测不是验证，不证明所有权、存在性、账户状态或卡/账户可转换性。需要验证时，请使用 `IranianCardNumber` 和 `IranianSheba` 验证规则。 ## 验证 本包包含 Laravel 验证 Rule 对象。默认情况下，空值会通过验证，因此当字段必须存在时，请将这些规则与 Laravel 的 `required` 规则结合使用。 ``` use Zarbinco\PersianCore\Rules\IranianMobile; use Zarbinco\PersianCore\Rules\IranianNationalCode; use Zarbinco\PersianCore\Rules\PersianAlpha; $request->validate([ 'name' => ['required', new PersianAlpha()], 'mobile' => ['required', new IranianMobile()], 'national_code' => ['nullable', new IranianNationalCode()], ]); ``` 可用规则： - `PersianText` - `PersianAlpha` - `PersianAlphaNum` - `IranianMobile` - `IranianNationalCode` - `IranianPostalCode` - `IranianSheba` - `IranianCardNumber` - `PersianMoneyAmount` 验证边界： - `IranianMobile` 检查规范化的伊朗手机号格式，而不是运营商所有权。 - `IranianSheba` 检查格式和 IBAN 校验和，而不是银行账户所有权。 - `IranianCardNumber` 默认检查格式和 Luhn 校验，而不是卡所有权。 - `PersianMoneyAmount` 检查格式和可解析性，而不是业务的最小/最大规则。 ### 严格验证模式 验证器默认是严格的。严格模式会拒绝周围文本中仅包含有效值的值，而规范化器对于提取和清理用例保持宽松。 ``` 'validation' => [ 'strict' => true, 'empty_values_pass' => true, ], ``` 对于传统行为，请全局或按规则禁用严格验证： ``` config(['persian-core.validation.strict' => false]); new IranianMobile(strict: false); new IranianCardNumber(strict: true); ``` 严格验证仍然接受波斯语、阿拉伯语和英语数字，以及用于完整值的常见分隔符，例如 `0912-123-4567`、`6037 9900 0000 0006`、`IR18 0100 0000 0000 0000 0000 00` 和 `۱,۲۵۰,۰۰۰ تومان`。 ## Artisan 命令 ``` php artisan persian-core:install php artisan persian-core:doctor php artisan persian-core:about ``` `persian-core:doctor` 检查常见的设置和配置错误。`persian-core:about` 打印包、环境、配置、模块和命令信息。 ## 配置 默认配置发布到 `config/persian-core.php`。 ``` 'numbers' => [ 'storage_digits' => 'en', 'display_digits' => 'fa', 'thousands_separator' => ',', 'decimal_separator' => '.', ], ``` `numbers.storage_digits` 控制存储规范化： - `en` 表示 `forStorage()` 和 `clean()` 返回英语数字。 - `fa` 表示 `forStorage()` 和 `clean()` 返回波斯语数字。 `numbers.display_digits` 控制显示规范化： - `fa` 表示 `forDisplay()` 返回波斯语数字。 - `en` 表示 `forDisplay()` 返回英语数字。 默认值为 `storage_digits: en` 和 `display_digits: fa`。不受支持的数字模式将安全回退到这些默认值。 其他值得注意的配置组： - `text`：基本文本清理以及显示/搜索规范化行为。 - `mobile`：伊朗手机号国家代码、国内前缀和掩码模式。 - `money`：默认货币、标签、显示数字、分隔符和转换率。 - `banks`：银行检测行为文档切换开关。 - `bank_data`：捆绑的离线银行数据集的信息元数据。 - `validation`：验证规则的严格程度和空值行为。 - `developer_experience`：保留的开发者体验切换开关。字符串宏默认处于禁用状态。 ## 扩展 / 覆盖服务 核心服务绑定到小型契约，因此应用程序可以通过 Laravel 的容器覆盖实现细节： ``` use App\Support\CustomTextNormalizer; use Zarbinco\PersianCore\Contracts\PersianTextNormalizerContract; $this->app->bind(PersianTextNormalizerContract::class, CustomTextNormalizer::class); ``` 自定义实现应保留契约预期的文档化行为和返回类型。除非您的应用程序明确将其替换为自己的服务，否则银行检测仍保持基于离线元数据。 ## 测试 / 质量 可用的 Composer 质量命令： ``` composer validate --strict composer test composer analyse composer format -- --test composer lint ``` `composer test` 运行 PHPUnit。`composer analyse` 运行 PHPStan/Larastan。`composer format -- --test` 在检查模式下运行 Pint。`composer lint` 运行 Composer 验证、PHPStan 和 PHPUnit。 ## 安全 有关支持的版本和漏洞报告，请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 MIT 许可证 (MIT)。请参阅 [LICENSE.md](LICENSE.md)。

标签：API密钥检测, ffuf, Laravel, OpenVAS, PHP, Web开发工具, 数据格式化, 波斯语/伊朗本地化, 输入验证