Download the PHP package skywarth/chaotic-schedule without Composer

On this page you can find all versions of the php package skywarth/chaotic-schedule. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of skywarth/chaotic-schedule

Informations about the package chaotic-schedule

Chaotic Schedule

Laravel package for randomizing command schedule intervals via pRNGs.

Reliability Rating Maintainability Rating Duplicated Lines (%)

codecov Quality Gate Status

DeepSource DeepSource

Packagist: https://packagist.org/packages/skywarth/chaotic-schedule

Table of Contents

Installation

  1. Consider the requirements

    • PHP >=7.4 is required

  2. Install the package via composer:

  3. (optional) Publish the config in order to customize it

  4. Done. You may now use random time and date macros on schedules

Problem Definition

Ever wanted to run your scheduled commands on random times of the day, or on certain days of the week? Or you may need to send some notifications not on fixed date times, but rather on random intervals hence it feels more human. Then this is the package you're looking for.

This Laravel packages enables you to run commands on random intervals and periods while respecting the boundaries set exclusively by you.

Use Cases

Documentation

Random Time Macros

1. ->atRandom(string $minTime, string $maxTime,?string $uniqueIdentifier=null,?callable $closure=null)

Used for scheduling your commands to run at random time of the day.

Parameter Type Example Value Description
minTime string '14:15' Minimum value for the random time range (inclusive)
maxTime string '22:38' Maximum value for the random time range (inclusive)
uniqueIdentifier string (nullable) 'my-custom-identifier' Custom identifier that will be used for determining seed for the given command. If null/default provided, command's signature will be used for this. It is primarily used for distinguishing randomization of same command schedules.
closure callable (nullable) 
function(int $motd){

return $motd+5;
}
 Optional closure to tweak the designated random minute of the day according to your needs. For example you may use this to run the command only on odd-numbered minutes. int minute of the day and Event (Schedule) instance is injected, meanwhile int response is expected from the closure.

Run a command daily on a random time between 08:15 and 11:42

Run a command every Tuesday, Saturday and Sunday on a random time between 04:20 and 06:09

Run a command every Sunday between 16:00 - 17:00 and also on Monday between 09:00 - 12:00

Notice the unique identifier parameter

2. ->dailyAtRandom(string $minTime, string $maxTime,?string $uniqueIdentifier=null,?callable $closure=null)

Identical to atRandom macro. Just a different name.

3. ->hourlyAtRandom(int $minMinutes=0, int $maxMinutes=59,?string $uniqueIdentifier=null,?callable $closure=null)

Used for scheduling you commands to run every hour at random minutes.

Parameter Type Example Value Description
minMinutes int 15 Minimum value for the random minute of hour (inclusive)
maxMinutes int 44 Maximum value for the random minute of hour (inclusive)
uniqueIdentifier string (nullable) 'my-custom-identifier' Custom identifier that will be used for determining seed for the given command. If null/default provided, command's signature will be used for this. It is primarily used for distinguishing randomization of same command schedules.
closure callable (nullable) 
function(int $randomMinute, Event $schedule){

return $randomMinute%10;
}
 Optional closure to tweak the designated random minute according to your needs. For example you may use this to run the command only on multiplies of 10.

Generated int random minute (between 0-59) and Event (Schedule) instance is injected, meanwhile int response that is between 0-59 is expected from the closure.

Run a command every hour between 15th and 25th minutes randomly.

Run a command every hour twice, once between 0-12 minute mark, another between 48-59 minute mark.

Run a command every hour, between minutes 30-45 but only on multiplies of 5.

4. ->hourlyMultipleAtRandom(int $minMinutes=0, int $maxMinutes=59, int $timesMin=1, int $timesMax=1, ?string $uniqueIdentifier=null,?callable $closure=null)

Similar to ->hourlyAtRandom, it is used for scheduling your commands to run every hour on random minutes. Difference between this and ->hourlyAtRandom is: ->hourlyMultipleAtRandom allows you to run a command multiple times per hour.

Example use case: I want to run a command every hour, 1-5 times at random, on random minutes. E.g. run minutes:[5,11,32,44]

Parameter Type Example Value Description
minMinutes int 15 Minimum value for the random minute of hour (inclusive)
maxMinutes int 44 Maximum value for the random minute of hour (inclusive)
timesMin int 3 Minimum amount of times to run this command per hour (inclusive). E.g: $timesMin=3, $timesMax=10, the command will run at least 3, at the most 10 times per hour. Run amounts decided per hour basis.
timesMax int 10 Maximum amount of times to run this command per hour (inclusive). E.g: $timesMin=5, $timesMax=17, the command will run at least 5, at the most 17 times per hour. Run amounts decided per hour basis.
uniqueIdentifier string (nullable) 'my-custom-identifier' Custom identifier that will be used for determining seed for the given command. If null/default provided, command's signature will be used for this. It is primarily used for distinguishing randomization/seeding of same command schedules.
closure callable (nullable) 
function(Collection $minutes,Event $e){

 return $minutes->diff([4,8,15,16,23,42])
->values();
 };
 Optional closure to tweak the designated random run minutes according to your needs. For example you may use this to run the command only on those minutes which are not in an array.

Designated random run minutes Collection that consist of int minutes (between 0-59) and Event (Schedule) instance is injected, meanwhile Collection response that contains int minutes between 0-59 is expected from the closure.

Run a command 4-5 (random) times per hour, only on weekdays (constant, every day), between 08:00 and 18:00 (constant, every hour between these). Minutes of each hour are random.

https://www.reddit.com/r/laravel/comments/18v714l/comment/ktkyc72/?utm_source=share&utm_medium=web2x&context=3

Run a command exactly 8 times an hour, it should run only between 20-40 minute marks, run only on wednesdays.

Run a command 2-6 times an hour, it should run only between 10-48 minute marks, run only on; tuesday,thursday,saturday, it should run only on even(divisible by 2) minutes.

Random Date Macros

1. ->randomDays(int $periodType, ?array $daysOfTheWeek, int $timesMin, int $timesMax, ?string $uniqueIdentifier=null,?callable $closure=null)

Used for scheduling your commands to run at random dates for given constraints and period.

Parameter Type Example Value Description
periodType int RandomDateScheduleBasis::Week The most crucial parameter for random date scheduling. It defines the period of the random date range, seed basis/consistency and generated random dates. It defines the seed for the random dates, so for the given period your randoms stay consistent. You may use any value presented in RandomDateScheduleBasis class/enum.
daysOfWeek array (nullable) [Carbon::Sunday, Carbon::Tuesday] Days of the week that will be used for random date generation. Only those days you pass will be picked and used. For example: if you pass [Carbon::Wednesday, Carbon:: Monday], random dates will be only on wednesdays and mondays. Since it is optional, if you don't pass anything for it that means all days of the week will be available to be used.
timesMin int 2 Defines the minimum amount of times the command is expected to run for the given period. E.g: period is week and timesMin=4, that means this command will run at least 4 times each week.
timesMax int 12 Defines the maximum amount of times the command is expected to run for the given period. E.g: period is month and timesMin=5 and timesMax=12, that means this command will run at least 5, at most 12 times each month. Exact number of times that it'll run is resolved in runtime according to seed.
uniqueIdentifier string (nullable) 'my-custom-identifier' Custom identifier that will be used for determining seed for the given command. If null/default provided, command's signature will be used for this. It is primarily used for distinguishing randomization of same command schedules.
closure callable (nullable) 
function(Collection $possibleDates, Event $schedule){

return $possibleDates->filter(function (Carbon $date){

     return $date->day%2!==0;//odd numbered days only 
});
}
 Closure parameter for adjusting random dates for the command.
This closure is especially useful if you would like to exclude certain dates, or add some dates to the possible dates to choose from.

Possible dates as Carbon instances are injected as collection to the closures, these dates represent the pool of possible dates to choose from for random dates, it doesn't represent designated run dates. Event (Schedule) instance is injected as well. Closure response is expected to be a collection of Carbon instances.

Run a command 5 to 10 times/days (as in dates) each month randomly.

Run a command exactly 2 times (as in dates) per week, but only on wednesdays or saturdays.

Run a command 15-30 times (as in dates) per year, only on Fridays.

Run a command 1 to 3 times (as in dates) per month, only on weekends, and only on odd days .

Joint examples

Examples about using both random time and random date macros together.

Run a command 1 to 2 times (as in dates) among Friday, Tuesday, Sunday, and only between 14:48 - 16:54

Info for nerds

Consistency, seed and pRNG

It was a concern to generate consistent and same random values for the duration of the given interval. This is due to the fact that the Laravel scheduler is triggered via CRON tab every minute. So we needed a solution to generate consistent randoms for each trigger of the scheduler. Otherwise, it would simply designate random date/time runs each time it runs, which will result in: commands never running at all (because run designation changes constantly), or commands running more that desired/planned.

In the world of cryptography and statistics, such challenges are tackled via pRNGs (pseudo random number generators). pRNGs as indicated in its name: is a pseudo random number generator which works with seed values and generates randoms determined by that seed, hence the name. Therefore, pRNGs would allow us to generate consistent and exactly same random values as long as seed remains the same. Now the question is what seed shall we pair pRNG with? After some pondering around, I deduced that if I give corresponding date/time of the interval, it would effectively be consistent throughout the interval. Henceforth, all the randomizing methods and macros work by utilizing SeedGenerationService which is responsible for generating seeds based on certain intervals (day, month, week etc.) This ensures your random run date/times are consistent throughout the interval, enabling consistency.

To those with a keen eye, this might present a possible problem. If the seed is paired only with interval, wouldn't that result in identical random date/time runs for separate commands? Exactly! Because of this, SeedGenerationService also takes command signatures into consideration by incorporating uniqueIdentifier (which is either command signature or custom identifier) into it's seed designation methods. This way, even if the separate commands have identical random scheduling, they'll have distinct randomization for them thanks to the uniqueIdentifier

Asserting the chaos

When dealing with pRNGs, nothing is truly chaotic and random, actually. It's all mathematics and statistics, it's deterministic. In order to ensure no harm could come from these randoms, I've prepared dozens of unit and feature tests for the different aspects of the library. From seed generation to generated random consistency, from distribution uniformity to validations, from design pattern implementation to dependency injection, all is well tested and asserted. See the code coverage reports and CI/CD runs regarding these functional tests.

Performance

As you might already know, Laravel scheduler runs every minute via CRON tab entry (see: https://laravel.com/docs/10.x/scheduling#running-the-scheduler). And since kernel.php (where you define your schedules) runs every minute, Laravel has to determine whether each command is designated to run at this minute or not. This is performed by running & checking datetime scheduling assignments and ->when() statements on your command scheduling.

This library heavily relies on pRNG, seed generation based on date/time and run designations. Hence, it is no surprise these calculations, randomization (pseudo) and designations are performed each time your kernel.php runs, which is every minute as explained on the previous paragraph. So yes, if you're on low-specs, it could affect your pipeline. Because these seed determination, run date/time designations, pseudo-random values are determined on each schedule iteration. Massive amounts (250+) of randomized command schedules could clog your server performance a bit in terms of memory usage.

But other than that, as the Jules from Pulp Fiction said:

"As far as I know, MF is tip-top"

Roadmap & TODOs

Credits & References

RNGs

This project has been developed using JetBrains products. Thanks for their support for open-source development.

JetBrains Logo (Main) logo. PhpStorm logo.

All versions of chaotic-schedule with dependencies

PHP Build Version
Package Version
Requires php Version >=7.4
paragonie/seedspring Version ^1.2
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package skywarth/chaotic-schedule contains the following files

Loading the files please wait ....