README

此包为 Laravel Filament 应用构建器提供 PhoneNumber 字段、PhoneNumberColumn 和 PhoneNumberEntry Infolist 条目，用于在数据库中规范化、格式化、隐藏和验证电话号码。它还提供了一个 Artisan 命令，用于规范数据库中已捕获的任何电话号码数据。

它确保存储在数据库中的号码是规范化格式，通常是 E164（+12345551212），并以国家或国际格式显示。它支持大多数由 ISO 国家代码定义的区域格式。

将电话号码视为日期。无论您如何显示和输入它们，您总是希望它们以标准格式存储。

注意 - 如果您更愿意通过在模型中铸造属性来处理规范化，并且不需要此插件提供的附加功能，例如现有数据的规范化、改进的搜索和验证，那么您可能更喜欢使用出色的 Laravel-Phone 包。

安装

注意：此包目前仅与 Filament v3 兼容，目前没有发布 v2 兼容版本的计划。

您可以通过 composer 安装此包

composer require cheesegrits/filament-phone-numbers

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="filament-phone-numbers-config"

这是发布配置文件的内容

return [
    'defaults' => [
        'region' => env('FILAMENT_PHONE_NUMBERS_ISO_COUNTRY', 'US'),
        'database_format' => env('FILAMENT_PHONE_NUMBERS_DATABASE_FORMAT', PhoneNumberFormat::E164),
        'display_format' => env('FILAMENT_PHONE_NUMBERS_DISPLAY_FORMAT', PhoneNumberFormat::NATIONAL),
        'icon' => env('FILAMENT_PHONE_NUMBERS_ICON', 'heroicon-m-phone'),
    ],
];

这些配置值定义了字段和列的所有使用的默认值。它们可以在每个字段或列的基础上进行覆盖。

而不是发布配置，我们建议使用环境变量。

FILAMENT_PHONE_NUMBERS_ISO_COUNTRY - 标准两个字母（alpha-2）ISO 国家代码。

FILAMENT_PHONE_NUMBERS_DATABASE_FORMAT, FILAMENT_PHONE_NUMBERS_DDISPLAY_FORMAT - 以下整数之一

0 - E164
1 - 国际
2 - 国家
3 - RFC3966

我们强烈建议将数据库格式保留为 E164。

FILAMENT_PHONE_NUMBERS_ICON - 任何有效的 Heroicons v2 图标名称。

PhoneNumber 字段

PhoneNumber 字段的简单用法是

use Cheesegrits\FilamentPhoneNumbers;

FilamentPhoneNumbers\Forms\Components\PhoneNumber::make('phone')

这将使用您全局配置的区域、数据库和显示格式。

它将尝试根据您的区域设置掩码，并将根据配置的区域在“宽容”模式下自动验证号码，其中它仅检查号码是否有正确数量的数字。

完整选项集如下。

要覆盖显示或数据库格式，请使用可用的 PhoneFormat 枚举之一

use Cheesegrits\FilamentPhoneNumbers;

FilamentPhoneNumbers\Forms\Components\PhoneNumber::make('phone')
    ->displayFormat(FilamentPhoneNumbers\Enums\PhoneFormat::INTERNATIONAL)
    ->databaseFormat(FilamentPhoneNumbers\Enums\PhoneFormat::INTERNATIONAL)

要执行更严格的验证，该验证使用已发布的元数据来确定号码是否“可能”，请使用 strict() 方法。

请注意使用此功能，因为元数据可能不是最新的。

use Cheesegrits\FilamentPhoneNumbers;

FilamentPhoneNumbers\Forms\Components\PhoneNumber::make('phone')
    ->strict()

要覆盖全局配置的区域，请使用 region() 方法并传递有效的两个字母（alpha-2）ISO 国家代码。

use Cheesegrits\FilamentPhoneNumbers;

FilamentPhoneNumbers\Forms\Components\PhoneNumber::make('phone')
    ->region('GB')

如果字段自动应用的掩码不符合您的需求，您可以使用标准 Filament mask() 方法覆盖它

use Cheesegrits\FilamentPhoneNumbers;

FilamentPhoneNumbers\Forms\Components\PhoneNumber::make('phone')
    ->mask('99 99-99-99-99')

PhoneNumberColumn

PhoneNumberColumn 的基本用法是

use Cheesegrits\FilamentPhoneNumbers;

FilamentPhoneNumbers\Columns\PhoneNumberColumn::make('phone'),

未进行任何修改时，这将使用全局默认的显示格式和区域。

您可以覆盖格式和区域，并可选地指定 dial() 方法，该方法将数字渲染为可点击的 'tel' URI。

use Cheesegrits\FilamentPhoneNumbers;

FilamentPhoneNumbers\Columns\PhoneNumberColumn::make('phone')
    ->displayFormat(FilamentPhoneNumbers\Enums\PhoneFormat::NATIONAL)
    ->region('CA')
    ->dial(),

搜索

将电话号码标准化为 E164 后，格式化数字的搜索通常不会立即生效。例如，搜索 555-1212 不会找到号码 +12345551212。同样，搜索 (234) 也不会找到。

为了克服这个问题，我们重写了 searchable() 的默认行为。首先，我们检查用户输入的第一个字符是否是左括号 '('。如果是，我们假设他们正在查找区号。因此，我们删除任何括号，获取当前配置区域的国际电话区号，并将其添加到搜索字符串的开头。然后，我们从字符串中删除所有其他非数字字符。因此，在 'US' 区域中搜索 '(2' 会转换为 +12。或者 '(234) 5' 会是 '+12345'。如果没有使用括号，我们不会添加国家代码，而只是删除非数字字符。因此，555-1212 变成 5551212。

如果您不想使用这种行为（例如，如果您不使用 E164 作为您的数据库格式，尽管我们强烈建议您这样做），您可以添加 useDefaultSearch() 方法，这将绕过搜索查询修改。此外，如果您在 searchable() 方法中指定了自己的 $query，这将绕过我们的修改。

use Cheesegrits\FilamentPhoneNumbers;
use Illuminate\Database\Query\Builder;

// uses modified search query described above
FilamentPhoneNumbers\Columns\PhoneNumberColumn::make('phone')
    ->searchable(),

// bypasses query modification to use standard Filament query
FilamentPhoneNumbers\Columns\PhoneNumberColumn::make('phone')
    ->useDefaultSearch()
    ->searchable(),

// uses your own query, bypassing custom query
FilamentPhoneNumbers\Columns\PhoneNumberColumn::make('phone')
    ->searchable(query: function (Builder $query, string $search) { 
        // your query here
    }),

PhoneNumberEntry

PhoneNumberEntry Infolist 字段的基本用法如下

use Cheesegrits\FilamentPhoneNumbers;

FilamentPhoneNumbers\Infolists\Components\PhoneNumberEntry::make('phone'),

未进行任何修改时，这将使用全局默认的显示格式和区域。

您可以覆盖格式和区域，并可选地指定 dial() 方法，该方法将数字渲染为可点击的 'tel' URI。

use Cheesegrits\FilamentPhoneNumbers;

FilamentPhoneNumbers\Infolists\Components\PhoneNumberEntry::make('phone')
    ->displayFormat(FilamentPhoneNumbers\Enums\PhoneFormat::INTERNATIONAL)
    ->region('GB')
    ->dial(),

Artisan 命令

我们提供了一个 Artisan 命令，用于标准化您数据库表（s）中已经收集的电话号码。

php artisan filament-phone-numbers:normalize

这将以测试模式运行命令，不会进行任何实际更改。

您将需要输入以下内容

模型（例如 Location 或 Maps/Dealership）
要标准化的电话属性（例如 phone 或 phone_number）
要标准化的属性（例如 normalized_phone，留空以就地修改）
电话号码格式（除非您有非常好的理由不这样做，否则请使用 E164）
两个字母（alpha-2）ISO 国家代码（例如 US 或 GB）

命令将输出如下反馈

No change: +15555551212
No change: +12561231234
No change: +14444564657
No change: +441332412251
No change: +12569909359
Normalizing: 2569909359 => +12569909359
Invalid number, no change: 465746

如果您希望从表中删除无效号码，可以提供 --delete-invalid 选项，这将无效号码设置为 null。请注意，您的数据库字段必须是可空的才能使此操作生效。

一旦您确认更改正确，您可以使用 --commit 选项调用命令

php artisan filament-phone-numbers:normalize --commit

... 或者 ...

php artisan filament-phone-numbers:normalize --commit --delete-invalid

如果您不想被提示输入，您也可以在命令行上提供所有参数，如下面的示例所示。

# --format is e164 (strongly recommended), international, national or rfc8966 (not recommended)
php artisan filament-phone-numbers::normalize --commit --model=Contacts/Customer --field=phone --target=new_phone --format=e164 --region=US

# --target is optional, if not given you should add the --in-place option (normalize in-place to same field name)
# If the --delete-invalid option is give, will set any invalid numbers to null 
php artisan filament-phone-numbers::normalize --commit --delete-invalid --model=User --field=mobile_phone --in-place --format=e164 --region=US

测试

克隆存储库并运行 ...

composer test

更改日志

有关最近更改的更多信息，请参阅更改日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

有关如何报告安全漏洞的详细信息，请参阅我们的安全策略。

致谢

此插件还使用了 Benjamin Morel 的 Brick\PhoneNumber 包，该包本身是对 giggsey/libphonenumber-for-php 包的包装，该包又基于 Google 的 google/libphonenumber 包。一路到底。

许可协议

MIT 许可协议（MIT）。有关更多信息，请参阅许可文件。

cheesegrits / filament-phone-numbers

维护者

详细信息