Creating a Timeslot - gpaddis/timeslot GitHub Wiki

The basic Timeslot

The Timeslot class accepts three arguments: start time, hours and minutes.
The start time can be either a Carbon instance, a DateTime object or a datetime string that Carbon::parse() can understand.

Here is an example of a 30-minutes timeslot instantiation:

// Create a 30-minutes timeslot starting at 15:00
$timeslot = new Timeslot(Carbon::parse('2017-08-19 15:00:00', 0, 30));

// Create a 90-minutes Timeslot from a DateTime instance
$timeslot = new Timeslot(new DateTime('2010-04-24 10:00:00'), 1, 30);

// Create a default timeslot (1 hour) from a string starting at 15:00
$timeslot = new Timeslot('2017-08-19 15:00:00');

Duration, start and end time

If you don't pass any arguments, the timeslot will start at the moment of the instantiation and will have a default duration of one hour. The seconds will be rounded up to the minute start, to include the moment of instantiation in the timeslot.

// Timeslot created on 2017-08-19 15:08:35, its start time is set at 15:08:00
$timeslot = new Timeslot();

If you want to reset the start time of your timeslot at hh:00:00 and recalculate its end time according to the duration specified, you can call the round() method on the instance.
In this case, you might find the Timeslot::create() fluent syntax more convenient:

$timeslot = Timeslot::create('2017-08-19 15:08:35')->round();
// Sets the start time at 15:00:00 and the end time at 15:59:59

The method round() works with any timeslot duration:

$timeslot = Timeslot::create('2019-11-04 12:15:15', 3, 30)->round();
// Will set the start time at 12:00:00 and the end time at 15:29:59 (3h 30m)

Shortcut: creating a 1-hour rounded timeslot

Very often, I want to create a default 1-hour timeslot that fits the current hour. The static method Timeslot::now() does exactly this:

// Time of instantiation: hh:34:08
$timeslot = Timeslot::now(); // Duration: 1h, start: hh:00:00, end: hh:59:59

Getting start and end time from an instance

Start() and end() methods return Carbon instances. This way, you can manipulate them with Carbon methods (e.g. ->toDateTimeString(), ->timestamp, etc.: see the API docs).

To get the start and end date of a timeslot object, call its start() and end() methods:

$timeslot = Timeslot::create('2017-08-19 15:08:35')->round();
$timeslot->start(); // Returns a Carbon instance
$timeslot->start()->toDateTimeString(); // Returns 2017-08-19 15:00:00
$timeslot->end()->toDateTimeString(); // Returns 2017-08-19 15:59:59

Creating previous and next timeslot with after() and before()

These static methods return new timeslots with a duration identical to that of the timeslot passed. The method before() will create a timeslot ending where the current starts, the method after() will create one that starts where the current ends.

$timeslot = new Timeslot('2017-08-19 15:00:00', 0, 30); 
// Duration: 30m, start: 15:00:00, end: 15:29:59

$nextTimeslot = Timeslot::after($timeslot); 
// Duration: 30m, start: 15:30:00, end: 15:59:59

$previousTimeslot = Timeslot::before($timeslot); 
// Duration: 30m, start: 14:30:00, end: 14:59:59

The method has()

By calling has on a Timeslot instance, you can check whether a Carbon object is within the timeslot's start and end time:

$timeslot = new Timeslot('2017-01-18 15:00:00');

$within = Carbon::parse('2017-01-18 15:00:00');
$outside = Carbon::parse('2017-01-18 16:30:00');

$timeslot->has($within); // true
$timeslot->has($outside); // false