README

Calculate the exact financial year, week-in-year, quarter, period, and week-in-period for any given date according to the Network Rail financial calendar.

Installation

Financial Calendar may be used as a standalone class or as part of a Laravel project. Both Service Provider and Facade options are provided.

• PHP ^8
• Nesbot/Carbon ^2

You may include the library in your project using: composer require networkrailbusinesssystems/financial-calendar.

Usage

The Financial Calendar class may be directly included or called through the Laravel service provider.

Out of the box, with or without a specific facade call, it can be used both as an instanced class and as a facade.

$calendar = new FinancialCalendar('2018-05-08');

$calendar = FinancialCalendar::parse('2018-05-08');

Date Formats

Out of the box this class supports dates in the following formats:

• 2018-07-01 (Y-m-d)
• 2018-07-01 00:00:00 (Y-m-d h:i:s)
• Carbon instance
• DateTime instance
• 1530403200 (Timestamp)

You may pass a specific format as the second parameter of any method that accepts a date.

$calendar = new FinancialCalendar('01-01-2010', 'm-d-Y');

FinancialCalendar::parse('01-01-2010', 'm-d-Y');

Should you need support for another format, please submit a pull request.

Year Start Dates

By default every financial year begins on April 1st. If you require a calendar that begins on another date, simply call the setYearStart function.

Year Start Overrides

An array of known custom year starts can be supplied to setYearStartOverrides:

[ year => [month, day] ]

$yearStartOverrides = [
    2017 => [4, 2]
];

$calendar->setYearStartOverrides($yearStartOverrides);

Any known year starts for the financial calendar have been preset.

Short Weeks

Sometimes the financial year is adjusted to prevent very short reporting weeks. This is compensated for with the following mechanisms:

Short Week Limit

If the first week of the financial year is shorter than the set short week limit, it is automatically extended to the end of the next full working week.

Week Length Overrides

Should the automatic short week limit be insufficient, or a long week is required anywhere other than the first week, an array of week lengths is available.

The array contains a set of years, with pairs of week numbers and the length of that week, which can be applied by calling setWeekLengthOverrides:

[ year => [week => length] ]

$weekLengthOverrides = [
    2020 => [
        1 => 11
    ]
];

$calendar->setWeekLengthOverrides($weekLengthOverrides);

Any known week lengths for the financial calendar have been preset.

Navigating the Calendar

Move the calendar to the next financial period or week:

$calendar
    ->nextPeriod()
    ->nextWeek();

If you would find other calendar navigating methods useful, get in touch or submit a PR.

Trait

If you are not storing the year and period in the database, or you need to be able to search for arbitrary dates based on a year or period in the financial calendar, you may use the HasFinancialDates trait on any eloquent model with an appropriate date column:

$myModel->forFinancialYear(2001)->get();
$myModel->forFinancialPeriod(2001, 12)->get();

Endpoints

You may utilise the calendar as an instanced or static class, and some commands support a fluent interface.

Instance

Static

Testing

This helper has been tested using PHPUnit for accuracy and functionality, tested against actual calendar data.

• 54 tests with 8103 assertions
• Calculations verified for 2004 - 2035
• Date Calculation
• Accepted Date Formats
• Class Usage