Download the PHP package jrbarnard/recurrence without Composer

Recurrence

This library allows you to create recurring DateTimes based on intervals, e.g every last wednesday of the month for the next 2 years.

It comes with some core Intervals, but it's built to allow you to create and use your own for your own project requirements.

It acts much like the DatePeriod PHP iterator in that it accepts a start date, end date and an interval object, however it gives us some more functionality also.

Contents

1. Requirements
2. Installation
3. Usage
4. Contributing
5. License

Requirements

The only requirement currently is a minimum PHP version of 5.6.

CURRENTLY HACK / HHVM IS NOT SUPPORTED

Installation

Composer is the recommended installation method:

However you can also download this repo, unzip it and include it in your project.

Usage

The package comprises of three class types, these can be used separately or all together.

Occurrences

The occurrences class is a container to store DateTimes. It's basically just a wrapper around an array, but allows us a bit more flexibility in the future if we want to deal with a collection of DateTimes / the stored occurrences from the iterator.

Occurrences also implements the ArrayAccess interface meaning we can use the occurrences object just like an array:

Currently it doesn't have any internal validation, fancier methods for filtering etc. These are things we may add in the future.

Intervals

Intervals are the classes that define how we get the next occurrence within the iterator. They mirror the functionality of PHP's core DateIntervals where their purpose is to take a datetime and return back a datetime after applying their interval to it.

E.g Datetime of 2012-01-01, interval of 1 day, we would expect to get back a datetime of 2012-01-02.

Intervals can be as simple or as complex as you want, we provide a few, however you can make and use your own, they just must implement the IntervalInterface.

E.g:

The above example would apply the interval of 12 minutes to the date time, you can see this very basic interval is at it's core utilising a PHP DateInterval. This works well for simple Intervals, however may not be suitable for more complex ones.

Intervals also accept a direction, forwards or backwards, you can use the constants defined within the IntervalInterface.

The intervals that come with the package as standard are:

• DailyInterval - Accepts an integer number of days and will add / sub that number of days from the passed in DateTime

• HourlyInterval - Accepts a numeric (can be float) number of hours and will add / sub that number of minutes from the passed in DateTime - E.g if you pass 3.5, that will equate to 210 minutes. If you pass 1.472826 that will equate to 88 minutes.

• WeeklyInterval - Accepts days of the week and the weekly occurrence, so you can do intervals such as: every Tuesday and Wednesday of every 3rd week.

• MonthlyInterval - Accepts days of the week and the monthly occurrence, so you can do intervals such as: the last Wednesday and Thursday of every other month.

Iterator

The Iterator is the class you can use to apply your intervals over a set DateTime / Occurrence range.

For example it lets you do things like:

• Get an occurrence every hour and a half until next week:

• Get the next 50 occurrences of every 2nd Wednesday and Thursdays:

This allows us to calculate dates for things like recurring events easily.

As mentioned above, you can create your own intervals, so you should be able to create an interval / iterator to fit your own needs.

Iterators also have a few extra features:

• They are countable, if all you want is how many times an occurrence will occur you can do:

• You can specify to skip certain DateTimes: E.g if you want an occurrence every hour and half, but not one of the occurrences for whatever reason, you can:

• You can set when the iterator should end to a DateTime or a number of occurrences, for example you may want to get an occurrence every hour before 5:30pm on a certain day, you can and it will stop iterating when the next occurrence it would get goes beyond this limit. Or if you prefer to set a number of occurrence limit, e.g every hour for the next 10 hours, you can by just passing an int:

• You can set a hard upper limit on number of occurrences to prevent the iterator accidentally iterating too much:

• You can set a direction for the iterator, so you can get the say every last Wednesday of every month from now, back 2 years:

• You can get the occurrences object from the iterator, it will internally run the iterator to ensure it's populated before returning:

Contributing

Please look at the contributing file

License

MIT License