networkrailbusinesssystems / financial-calendar
Calculate the exact financial calendar period, week, quarter, and year, for any given date
Installs: 1 458
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Requires
- php: ^8.3
- nesbot/carbon: ^3
Requires (Dev)
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