laravel model status

تعيين الحالات لنماذج Eloquent

تخيل أنك تريد أن يكون لنموذج Eloquent حالة. يمكن حلها بسهولة بمجرد إضافة حقل status إلى هذا النموذج والانتهاء منه. ولكن في حالة احتياجك إلى سجل تغييرات الحالة أو الحاجة إلى تخزين بعض المعلومات الإضافية حول سبب تغيير الحالة، فإن مجرد إضافة حقل واحد لن يفي بالغرض.

توفر هذه الحزمة سمة HasStatuses التي تتيح لك، بمجرد تثبيتها على النموذج، القيام بأشياء مثل هذه:

 // set a status
$ model -> setStatus ( ' pending ' , ' needs verification ' );

// set another status
$ model -> setStatus ( ' accepted ' );

// specify a reason
$ model -> setStatus ( ' rejected ' , ' My rejection reason ' );

// get the current status
$ model -> status (); // returns an instance of SpatieModelStatusStatus

// get the previous status
$ latestPendingStatus = $ model -> latestStatus ( ' pending ' );

$ latestPendingStatus -> reason ; // returns 'needs verification' 

ادعمنا

نحن نستثمر الكثير من الموارد في إنشاء أفضل الحزم مفتوحة المصدر في فئتها. يمكنك دعمنا عن طريق شراء أحد منتجاتنا المدفوعة.

نحن نقدر بشدة إرسالك لنا بطاقة بريدية من مسقط رأسك، مع ذكر الحزمة (الحزم) التي تستخدمها. ستجد عنواننا على صفحة الاتصال لدينا. ننشر جميع البطاقات البريدية المستلمة على جدار البطاقات البريدية الافتراضية لدينا.

تثبيت

يمكنك تثبيت الحزمة عبر الملحن:

composer require spatie/laravel-model-status

يجب عليك نشر الترحيل باستخدام:

php artisan vendor:publish --provider= " SpatieModelStatusModelStatusServiceProvider " --tag= " migrations "

ترحيل جدول statuses :

php artisan migrate

اختياريًا، يمكنك نشر ملف التكوين باستخدام:

php artisan vendor:publish --provider= " SpatieModelStatusModelStatusServiceProvider " --tag= " config "

هذه هي محتويات الملف الذي سيتم نشره على config/model-status.php

 return [

    /*
     * The class name of the status model that holds all statuses.
     *
     * The model must be or extend `SpatieModelStatus Status ` .
     */
    ' status_model ' => Spatie  ModelStatus Status::class,

    /*
     * The name of the column which holds the ID of the model related to the statuses .
     *
     * You can change this value if you have set a different name in the migration for the statuses table .
     */
    ' model_primary_key_attribute ' => ' model_id ' ,

];

الاستخدام

أضف سمة HasStatuses إلى النموذج الذي ترغب في استخدام الحالات عليه.

 use Spatie  ModelStatus  HasStatuses ;

class YourEloquentModel extends Model
{
    use HasStatuses;
}

تعيين حالة جديدة

يمكنك تعيين حالة جديدة مثل هذا:

 $ model -> setStatus ( ' status-name ' );

يمكن تمرير سبب تغيير الحالة كوسيطة ثانية.

 $ model -> setStatus ( ' status-name ' , ' optional reason ' );

إسترجاع الحالات

يمكنك الحصول على الحالة الحالية للنموذج:

 $ model -> status ; // returns a string with the name of the latest status

$ model -> status (); // returns the latest instance of `SpatieModelStatusStatus`

$ model -> latestStatus (); // equivalent to `$model->status()`

يمكنك أيضًا الحصول على أحدث حالة لاسم معين:

 $ model -> latestStatus ( ' pending ' ); // returns an instance of `SpatieModelStatusStatus` that has the name `pending`

احصل على جميع أسماء الحالات المتاحة للنموذج.

 $ statusNames = $ model -> getStatusNames (); // returns a collection of all available status names.

ستعرض الأمثلة التالية حالات من النوع status 1 أو status 2 ، أيهما الأحدث.

 $ lastStatus = $ model -> latestStatus ([ ' status 1 ' , ' status 2 ' ]);

// or alternatively...
$ lastStatus = $ model -> latestStatus ( ' status 1 ' , ' status 2 ' );

يمكن استرداد جميع الحالات المرتبطة بالنموذج على النحو التالي:

 $ allStatuses = $ model -> statuses ;

سيؤدي هذا إلى التحقق مما إذا كان النموذج لديه الحالة:

 $ model -> setStatus ( ' status1 ' );

$ isStatusExist = $ model -> hasStatus ( ' status1 ' ); // return true
$ isStatusExist = $ model -> hasStatus ( ' status2 ' ); // return false

استرجاع النماذج مع أحدث حالة معينة

سيُرجع نطاق currentStatus النماذج التي لها حالة بالاسم المحدد.

 $ allPendingModels = Model:: currentStatus ( ' pending ' );

//or array of statuses
$ allPendingModels = Model:: currentStatus ([ ' pending ' , ' initiated ' ]);
$ allPendingModels = Model:: currentStatus ( ' pending ' , ' initiated ' );

استرجاع النماذج دون حالة معينة

سيعيد نطاق otherCurrentStatus جميع النماذج التي ليس لها حالة بالاسم المحدد، بما في ذلك أي نموذج ليس له أي حالات مرتبطة به.

 $ allNonPendingModels = Model:: otherCurrentStatus ( ' pending ' );

يمكنك أيضًا توفير مجموعة من أسماء الحالات لاستبعادها من الاستعلام.

 $ allNonInitiatedOrPendingModels = Model:: otherCurrentStatus ([ ' initiated ' , ' pending ' ]);

// or alternatively...
$ allNonInitiatedOrPendingModels = Model:: otherCurrentStatus ( ' initiated ' , ' pending ' );

التحقق من الحالة قبل تعيينها

يمكنك إضافة تحقق مخصص عند تعيين الحالة عن طريق الكتابة فوق التابع isValidStatus :

 public function isValidStatus ( string $ name , ? string $ reason = null ): bool
{
    . . .

    if (! $ condition ) {
        return false ;
    }

    return true ;
}

إذا قامت isValidStatus بإرجاع false ، فسيتم طرح استثناء SpatieModelStatusExceptionsInvalidStatus .

يمكنك تجاوز التحقق باستخدام التابع forceSetStatus :

 $ model -> forceSetStatus ( ' invalid-status-name ' );

تحقق مما إذا تم تعيين الحالة

يمكنك التحقق من تعيين حالة معينة على النموذج في أي وقت باستخدام التابع hasEverHadStatus :

 $ model -> hasEverHadStatus ( ' status 1 ' );

تحقق مما إذا لم يتم تعيين الحالة مطلقًا

يمكنك التحقق مما إذا لم يتم تعيين حالة معينة على النموذج في أي وقت باستخدام التابع hasNeverHadStatus :

 $ model -> hasNeverHadStatus ( ' status 1 ' );

حذف الحالة من النموذج

يمكنك حذف أي حالة معينة تم تعيينها على النموذج في أي وقت باستخدام التابع deleteStatus :

حذف حالة فردية من النموذج:

 $ model -> deleteStatus ( ' status 1 ' );

حذف حالات متعددة من النموذج مرة واحدة:

 $ model -> deleteStatus ([ ' status 1 ' , ' status 2 ' ]);

الأحداث

سيتم إرسال الحدث SpatieModelStatusEventsStatusUpdated عند تحديث الحالة.

 namespace Spatie  ModelStatus  Events ;

use Illuminate  Database  Eloquent  Model ;
use Spatie  ModelStatus  Status ;

class StatusUpdated
{
    /** @var SpatieModelStatus Status | null */
    public $ oldStatus ;

    / ** @var SpatieModelStatus Status */
    public $ newStatus ;

    / ** @var IlluminateDatabaseEloquent Model */
    public $ model ;

    public function __construct (? Status $ oldStatus , Status $ newStatus , Model $ model )
    {
        $ this -> oldStatus = $ oldStatus ;

        $ this -> newStatus = $ newStatus ;

        $ this -> model = $ model ;
    }
}

النموذج المخصص والهجرة

يمكنك تغيير النموذج المستخدم عن طريق تحديد اسم فئة في مفتاح status_model لملف تكوين model-status .

يمكنك تغيير اسم العمود المستخدم في جدول الحالة ( model_id افتراضيًا) عند استخدام ترحيل مخصص حيث قمت بتغيير ذلك. في هذه الحالة، ما عليك سوى تغيير مفتاح model_primary_key_attribute الخاص بملف تكوين model-status .

اختبار

تحتوي هذه الحزمة على اختبارات التكامل التي يتم تشغيلها بواسطة الأوركسترا/testbench.

يمكنك إجراء جميع الاختبارات باستخدام:

composer test

سجل التغيير

الرجاء مراجعة سجل التغيير لمزيد من المعلومات عما تغير مؤخرًا.

المساهمة

يرجى الاطلاع على المساهمة للحصول على التفاصيل.

حماية

إذا وجدت خطأً يتعلق بالأمان، فيرجى إرسال بريد إلكتروني إلى العنوان [email protected] بدلاً من استخدام أداة تعقب المشكلات.

الاعتمادات

• توماس فيرهيلست
• فريك فان دير هيرتن
• جميع المساهمين

رخصة

رخصة معهد ماساتشوستس للتكنولوجيا (MIT). يرجى الاطلاع على ملف الترخيص لمزيد من المعلومات.