Meta Fields

Meta Field برای داده هایی است که جزو فیلدهای اصلی ورود نیستند، اما باید در ثبت نام، ویرایش و نمایش کاربر وجود داشته باشند. مثال های رایج:

• birthdate
• gender
• address
• postal_code
• company_name

این فیلدها با Authenticator::userMetaFields() تعریف می‌شوند.

اگر از فرم های آماده package استفاده کنید، این فیلدها در formهای user management و auth flowهای مرتبط استفاده می‌شوند. اگر فرم custom برای panel یا API دارید، همین definitionها می‌توانند منبع ساخت schema، validation و display شما باشند.

چه زمانی از meta field استفاده کنیم؟

از meta field استفاده کنید وقتی:

• فیلد فقط برای پروفایل یا ثبت نام مهم است، نه برای login
• می‌خواهید فرم های کاربر بدون migration یا view اختصاصی سنگین توسعه‌پذیرتر شوند
• فیلد ممکن است برای person typeهای مختلف متفاوت باشد

از auth field استفاده کنید وقتی:

• همان فیلد در login، registration یا forget password نقش مستقیم دارد

تعریف meta field

app/Providers/AppServiceProvider.php

use Dornica\AccessHub\Authentication\Authenticator;
use Dornica\AccessHub\Authentication\Builders\UserMetaField;
use App\Enums\Admin\Gender;

private function setMetaFields(): void
{
    Authenticator::userMetaFields([
        UserMetaField::make()
            ->onlyReal()
            ->type('datetime')
            ->name('birthdate')
            ->label('Birth date')
            ->rules([
                'required',
                'date',
                'before:today',
            ]),

        UserMetaField::make()
            ->onlyReal()
            ->type('radio')
            ->name('gender')
            ->label('Gender')
            ->rules([
                'required',
                'in:1,2',
            ])
            ->componentAttributes([
                'container-class' => 'col-6',
                'options' => Gender::componentOptions(),
                'checked' => Gender::MALE->value,
            ])
            ->showAsBadge()
            ->badgeVariant([
                Gender::MALE->value => 'info',
                Gender::FEMALE->value => 'danger',
            ])
            ->badgeAppearance('light')
            ->badgeSize('sm'),
    ]);
}

ساختار UserMetaField

متدهای پایه

متد	کاربرد
name()	نام کلید ذخیره شده در user_meta
label()	لیبل نمایشی
rules()	قوانین اعتبارسنجی
type()	نوع فیلد
componentAttributes()	تنظیمات ورودی برای فرم
onlyReal()	نمایش فقط برای شخص حقیقی
onlyLegal()	نمایش فقط برای شخص حقوقی

type های پشتیبانی شده

• text
• textarea
• number
• datetime
• radio

نکته

اگر فیلد شما option-based است، مثل radio، بهتر است options را داخل componentAttributes() تعریف کنید تا هم فرم و هم نمایش نهایی بتوانند label انسانی را به‌درستی resolve کنند.

نمایش meta fieldها در صفحه show

زیرساخت package از displayAttributes برای نمایش meta fieldها هم پشتیبانی می‌کند. این یعنی لازم نیست برای هر فیلد enum-like داخل Blade شرط بنویسید.

متدهای display روی UserMetaField

متد	کاربرد
displayAttributes()	تنظیم مستقیم display config
showAsBadge()	نمایش فیلد به صورت badge
badgeVariant()	رنگ badge
badgeAppearance()	ظاهر badge
badgeSize()	اندازه badge

مثال

UserMetaField::make()
    ->type('radio')
    ->name('account_type')
    ->label('Account type')
    ->rules(['required'])
    ->componentAttributes([
        'options' => [
            ['label' => 'Basic', 'value' => 1],
            ['label' => 'Pro', 'value' => 2],
        ],
    ])
    ->showAsBadge()
    ->badgeVariant([
        1 => 'secondary',
        2 => 'success',
    ])
    ->badgeAppearance('light')
    ->badgeSize('sm');

در این سناریو:

• فرم از options برای ساخت input استفاده می‌کند
• صفحه نمایش کاربر همان options را برای تبدیل مقدار خام به label انسانی استفاده می‌کند
• badge styling هم از metadata همان فیلد خوانده می‌شود

helperهای خواندن meta fieldها

array userMetaFieldGroups()
array userMetaFields(?PersonType $personType = null)

use Dornica\AccessHub\Authentication\Enums\PersonType;

$allMetaFields = userMetaFieldGroups();
$realPersonMetaFields = userMetaFields(PersonType::REAL);

userMetaFields(?PersonType $personType = null): array

meta fieldهای تعریف‌شده را برمی‌گرداند.

پارامتر	نوع	توضیح
personType	PersonType | null	اگر مقدار داشته باشد فقط fieldهای همان person type برگردانده می‌شود

سناریوی رایج:

• ساخت فرم dynamic ثبت نام
• ساخت schema برای endpoint سفارشی
• نمایش fieldهای مجاز برای person type خاص
• ساخت خروجی انسانی برای fieldهای enum-like

شخص حقیقی و شخص حقوقی

اگر enable_legal_person در کانفیگ فعال باشد، سیستم می‌تواند برای person typeهای مختلف، auth field و meta field متفاوت داشته باشد.

مثال های رایج:

• شخص حقیقی: birthdate, gender
• شخص حقوقی: company_name, national_id

متد مرتبط:

bool Authenticator::isLegalPersonEnabled()