README

Introducing our Laravel Recurring package - the ultimate solution for adding recurring functionality to your Laravel Models! Whether you need simple daily, weekly, or every n days recurrence, or more complex patterns like repeating a model on the second Friday of every month, our package has got you covered. With a seamless integration into your Laravel application, you can easily manage and automate recurring tasks with just a few lines of code.

Installation

You can install the package via composer:

composer require mohammedmanssour/laravel-recurring-models

You can publish and run the migrations with:

php artisan vendor:publish --tag="recurring-models-migrations"
php artisan migrate

Usage

Adding the recurring functionality to Models:

Make sure you models implements Repeatable Contract.

use MohammedManssour\LaravelRecurringModels\Contracts\Repeatable as RepeatableContract;

class Task extends Model implements RepeatableContract
{

}

Add the Repeatable trait to your Model

use MohammedManssour\LaravelRecurringModels\Contracts\Repeatable as RepeatableContract;
use MohammedManssour\LaravelRecurringModels\Concerns\Repeatable;

class Task extends Model implements RepeatableContract
{
    use Repeatable;
}

Optionaly, customize Model base date.

/**
 * define the base date that we would use to calculate repetition start_at
 */
public function repetitionBaseDate(RepetitionType $type = null): Carbon
{
    return $this->created_at;
}

Model Recurring rules

The Repeatable trait has repeat method that will help you define the recurrence rules for the model.

The repeat method will return Repeat helper class that has 4 methods: daily, everyNDays, weekly, and complex

1. Daily Recurrence

This will help you to create daily recurring rule for the model.

$model->repeat()->daily()

The recurrence will start the next day based on the repetitionBaseDate returned value.

2. Every N Days Recurrence

This will help you to create every N Days recurring rules for the model.

$model->repeat()->everyNDays(days: 3)

The recurrence will start after n=3 days based on the repetitionBaseDate returned value.

3. Weekly Recurrence

This will help ypi create weekly recurrence rule for the model.

$model->repeat()->weekly()

The recurrence will start after 7 days based on the repetitionBaseDate returned value.

You can specify the days of the recurrence using the on method.

$model->repeat()->weekly()->on(['sunday', 'monday', 'tuesday'])

4. Complex Recurrence.

This will help you create complex recurrence rules for the task.

$model->repeat()
    ->complex(
        year: '*',
        month: '*',
        day: '*',
        week: '*',
        weekOfMonth: '*',
        weekday: '*'
    )

Examples

Repeat model on the second friday of every month.

$model->repeat()->complex(weekOfMonth: 2, weekday: Carbon::FRIDAY)

Repeat model on the 15th day of every month.

$model->repeat()->complex(day: 15)

Model Scopes

use whereOccurresOn scope to get models that occurres on a specific date.

Task::whereOccurresOn(Carbon::make('2023-05-01'))->get()

use whereOccurresBetween scope to get the models that occurres between two sepcific dates.

Task::whereOccurresBetween(Carbon::make('2023-05-01'), Carbon::make('2023-05-30'))->get()

1. End Recurrance

use endsAt to end occurrance on a specific date

$model->repeat()->daily()->endsAt(
    Carbon::make('2023-06-01')
)

use endsAfter to end occurrance after n times.

$model->repeat()->daily()->endsAfter($times);

2. Start Recurrance

use startsAt method to start occurrance after a specific date.

$model->repeat()->daily()->startsAt(
    Carbon::make()
)

Testing

composer test

Credits

Mohammed Manssour

License

The MIT License (MIT). Please see License File for more information.

marshmallow / laravel-recurring-models

Maintainers

Details