Download the PHP package umulmrum/holiday without Composer
On this page you can find all versions of the php package umulmrum/holiday. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package holiday
Holiday
Holiday is a library that computes holidays in a very flexible way. It is possible to filter holiday lists by various criteria and format them in different ways. It is easy to add more holiday providers, filters and formatters, so even if this library does not perfectly fit your needs, you can simply extend it.
Requirements
- PHP >= 7.3
- Symfony translator is recommended for translations (built-in translator requires version 4.3+, but can be trivially reimplemented for older versions).
That's it really.
Installation
Install the library using Composer.
Usage Examples
Simple example:
This results in a HolidayList
which contains all holidays for 2020; this list can then be used for output or further
computation. Holidays are always computed for one full year and can then be narrowed down using filters.
More complex example:
This results in an array of date strings. Note that we used the ISO-3166-2 code DE-BY
to get the holidays for Bavaria.
See section Resolving Holiday Providers
below for different ways to request holidays.
There are also some helper methods that simplify some common holiday computations. Using the GetHolidayForMonth
helper,
the example above can be substituted by this:
One last example shows how to compute all holidays, Saturdays and Sundays in the years 2020 and 2021 for the German state Baden-Wuerttemberg, sort these holidays by date and format the result as JSON (all in 2 lines of code):
Detailed Usage
First create a HolidayList
for holidays in one or more years by using the HolidayCalculator
. Pass one or more holiday
providers to the calculator to get holidays for these providers, e.g. a country, a religion or event a specific weekday.
HolidayList
is basically an augmented array of Holiday
objects.
See the complete list of built-in providers under src/Provider
or use them as examples to create your own. Be aware that
a holiday is NOT equivalent to a day off - holidays in the sense of this lib is more of a "special day" as defined by
providers, and might be traditional or religious days without impact on working hours. To restrict a HolidayList
to
days off, use the IncludeTypeFilter
as described below in the Filters
section.
The HolidayList
can then be asked for information or holidays can be added or removed, the list can be filtered or formatted.
Resolving Holiday Providers
The examples above already showed two different ways to specify for which region or other "entity" holidays should be calculated. There is also a third way, and complete customization is also possible - let's have a look at all of them:
-
Fully qualified class name:
This is suggested as default, since you only need to remember the region to request and IDEs should provide autocompletion to save keystrokes.
-
Instantiated class:
Use an instantiated class of the same type as you would specify when using way 1. Do this if a provider has constructor arguments, such as additional holiday types as seen in the example (Sundays aren't automatically days off).
-
ISO-3166 names:
Use ISO-3166-1 country codes or ISO-3166-2 region codes e.g. if your application already uses them to simplify integration and decoupling of the Holiday lib. The list of supported countries and regions can be found in
src/Resolver/isoData.php
. There is a fallback to the base country in case the region code is not found - see the comment in theIsoResolver
class for details. -
Custom
Use this to add custom resolving logic.
ResolverHandler
takes an array ofProviderResolverInterface
s (and implementsResolverHandlerInterface
, so can even be exchanged with more custom code).
Filters
Use filters to narrow down the list of holidays to the desired subset.
See the complete list of built-in filters under src/Filter
or use them as examples to create your own (extend
AbstractFilter
or implement HolidayFilterInterface
).
Formatters
Use formatters to - you guessed it - format HolidayList
s and Holiday
s.
Formatters may return a string or an array of strings.
See the complete list of built-in formatters under src/Formatter
or use them as examples to create your own (implement
HolidayFormatterInterface
).
Holiday Types
A HolidayList
contains Holiday
objects. Apart from a (technical) name and date, each holiday has one or more types.
Return these types as an integer bit mask by calling Holiday::getType()
, or ask for specific types using
Holiday::hasType()
.
The type is normally a combination of
- the holiday's origin, e.g. religious or traditional,
- the holiday's legal status (official or not),
- the holiday's impact on working hours (e.g. if it's a full or half day off, if schools or government agencies are closed).
See the HolidayType
class for available types. This class also contains translation keys for these types
which can then get translated for localized readable names - see e.g. JsonFormatter
for details.
Which Holidays are Returned
HolidayCalculator
only returns holidays that are legally defined in the scope of the chosen holiday provider, or
if there's "secular impact", e.g. it's a day off. This means there are differences between providers; e.g. Easter Sunday
is an official holiday in Brandenburg/Germany, so it is included for Brandenburg. In the rest of Germany (as well as
most other countries) it is not a holiday as it is a Sunday anyway, and therefore not included as a holiday.
Similarly, Sundays are normally not included if they are no official holidays in the scope of the holiday provider,
although they are days off in the Western hemisphere. To find out which days are days off, provide both the respective
holiday provider and the one for Sundays (or use GetNoWorkDaysForTimeSpan()
).
If your use case requires other holiday lists, consider combining multiple providers (e.g. Switzerland
and
ChristianHolidays
), or remove some using filters (e.g. combine IncludeTypeFilter
and InverseFilter
) to remove
Sundays from Brandenburg
lists.
Translations
Some formatters can be initialized with an optional translator. See TranslatorInterface
and the translation files
under res/trans
.
Helpers
To simplify some common holiday-related tasks, see the helpers under src/Helper
(e.g. the GetNoWorkDaysForTimeSpan
helper takes holiday providers and a timespan and calculates a list of all days off for these arguments).
Supported Calendars
Currently only the Gregorian calendar is supported, for years < 10000.
Supported Countries
(map created by simplemaps.com - licensed under MIT)
- Austria (incl. Burgenland, Carinthia, Lower Austria, Salzburg, Styria, Tyrol, UpperAustria, Vienna, Vorarlberg)
- Belgium
- Brazil
- Denmark
- France (incl. Bas-Rhin, French Guiana, Guadeloupe, Haut-Rhin, Martinique, Moselle, Reunion)
- Germany (incl. Baden-Wuerttemberg, Bavaria, Berlin, Brandenburg, Bremen, Hamburg, Hesse, Lower Saxony, Mecklenburg-Vorpommern, North-rhine Westphalia, Rhineland Palatinate, Saarland, Saxony, Saxony-Anhalt, Schleswig-Holstein, Thuringia)
- Ireland
- Italy (incl. South Tyrol)
- Liechtenstein
- Luxembourg
- Mexico
- The Netherlands
- Poland
- Russia
- Spain (common holidays only yet)
- Switzerland (incl. Aargau, Appenzell-Ausserrhoden, Appenzell-Innerrhoden, Basel Landschaft, Basel Stadt, Bern, Fribourg, Geneva, Glarus, Grisons, Jura, Lucerne, Neuchatel, Nidwalden, Obwalden, Schaffhausen, Schwyz, Solothurn, St Gallen, Thurgau, Ticino, Uri, Valais, Vaud, Zuerich, Zug)
- USA (federal holidays only yet)
To create your own holiday providers have a look at the existing code, it should be self-explanatory. I will happily merge pull requests to support more countries (see below).
Notes on German Holidays
- Easter Sunday/Ostersonntag and Whit Sunday/Pfingstsonntag are not public holidays in most states.
- Every Sunday is a public holiday in Hesse.
- Assumption/Mariä Himmelfahrt is a public holiday in about 1700 of about 2000 communities in Bavaria. This is implemented as a partial holiday, so you might want to add your logic that filters this date.
- In Bavaria schools are closed on Assumption Day and on Repentance and Prayer Day. There is no special handling of this "behavior".
- Corpus Christi/Fronleichnam is a public holiday in some communities in Saxony and Thuringia.
- Regional holidays with traditionally (but not publicly) limited opening hours are not considered yet (e.g. carnival days).
- Some ports at the German Ocean celebrate some holidays as "High Holidays". It is generally not allowed to work on these days, and work time ends at 12 o'clock the day before. This is not considered yet.
- Also there are some quiet days that are not public holidays in various states. This is also not considered yet.
- New states of Germany are treated as if they had always been part of the Federal Republic of Germany. For years before 1990 holidays are therefore not correct.
Notes on Swiss Holidays
- Holidays in Switzerland are really complicated as there is wide fragmentation on if or how holidays are celebrated. The implemented rules are a best guess of what makes sense in the scope of this library (written by someone who isn't from Switzerland). I'm open for improvements.
Notes on Christian Holidays
- Only holidays of Western churches are taken into account.
- Only the most important holidays are taken into account, as interpreted by me (which is most likely far from accurate; please feel free to contribute changes).
Note on Holidays Way in the Past or Future
If computing holidays for past years, be aware that they may not be accurate. All holidays were introduced at some point in time, so this lib might return holidays for years in which they really were not in existence, as well as omit holidays that haven't been celebrated for a long time.
Likewise holidays might of course change in the future. Also, Easter date calculation will change in the far future due to astronomical reasons.
This lib aims to be accurate for "recent" years at least, approximately for years after World War II until present. Again, contributions are welcome.
Versioning
This library follows Semantic Versioning. Everything in the library can be considered the public API except:
- code annotated with
@internal
, - tests,
-
code that can only be accessed by using reflection (e.g. private methods).
Note that the library is still in a 0.* version which allows the public API to change anytime.
Contribution
Contributions are highly welcome. Please follow these rules when submitting a PR:
- Mimic existing code for style and structure.
- Add unit tests for all of your code.
- Use the Symfony code style (call
php-cs-fixer fix
in the library root without further arguments).
By submitting a PR you agree that all your contributed code may be used under the MIT license.
How To Add a New Country or Region
- Add a provider for that country or region inside
src/Provider/...
. - Should you need to add country-specific holiday names, add those to
Constant\HolidayName
and provide English translations insideumulmrum_holiday.en.xliff
. - Lookup the ISO code for your country or region and add it to
Resolver\isoData
. - Provide tests inside
tests/Provider/...
that ideally cover all edge cases.
License
Holiday is licensed under the MIT License. See LICENSE for details.
In short, this license allows you to use this code for almost anything you like. If you somehow make use of it to suppress, injure, kill, spy, or any other thing considered evil, there is nothing in this license that holds you back. But fuck you anyway.
For all other people I hope this little lib helps you and perhaps even gives you some pleasure.