Add recipes files. Fix for link to other between recipe.

Signed-off-by: Sacha Telgenhof <[email protected]>

docs/filters.md

@@ -9,5 +9,5 @@ filters are currently available in Yasumi:
 - **Seasonal** - Holidays that are celebrated due to its seasonal character (e.g. Halloween).
 - **Other** - Holidays that fall outside any of the above type.
 - **Between** - Filters all holidays between a given start and given end date. Check out
-  this [recipe](/docs/cookbook/between_filter) on how to use the Between filter.
+  this [recipe](/recipes/between_filter.md) on how to use the Between filter.
 - **On** - Filters all holidays that happen on a given date.

docs/recipes/basic.md

@@ -0,0 +1,117 @@
+# A basic starter
+
+Yasumi is very easy to use. Let's find out how easy with this basic exercise.
+
+We need to include Yasumi using the Composer autoloader first, then we can create a new holiday provider
+instance (we will be using the United States of America):
+
+``` php
+<?php
+
+require 'vendor/autoload.php';
+
+// Use the factory to create a new holiday provider instance
+$holidays = Yasumi\Yasumi::create('USA', (int) date('Y'));
+```
+
+Now we can access and use the various API methods of Yasumi. Let's see how many holidays the US has in
+2023:
+
+``` php
+// Get the number of defined holidays
+echo $holidays->count() . PHP_EOL;
+
+// 11 (Substituted holidays are only accounted for once)
+```
+
+To get an overview of all the holidays of the US, we can simply loop through the results since each Yasumi
+Holiday Provider implements the [ArrayIterator](https://www.php.net/manual/en/class.arrayiterator.php). Getting a
+list of holidays for the US with the internal short names can be obtained as follows:
+
+``` php
+// Get a list all of the holiday names (short names)
+foreach ($holidays->getHolidayNames() as $name) {
+    echo $name . PHP_EOL;
+}
+
+// 'newYearsDay'
+// 'substituteHoliday:newYearsDay'
+// 'martinLutherKingDay'
+// 'washingtonsBirthday'
+// 'memorialDay'
+// 'juneteenth'
+// 'independenceDay'
+// 'labourDay'
+// 'columbusDay'
+// 'veteransDay'
+// 'substituteHoliday:veteransDay'
+// 'thanksgivingDay'
+// 'christmasDay'
+```
+
+> These short names are not the names used for display purposes: they are simply used as internal identifiers by Yasumi.
+> Later we will see how we can use the (display) names of holidays we are typically used to.
+
+Now let's get all the holiday dates:
+
+``` php
+// Get a list all of the holiday dates
+foreach ($holidays->getHolidayDates() as $date) {
+    echo $date . PHP_EOL;
+}
+
+// 2023-01-01
+// 2023-01-02
+// 2023-01-16
+// 2023-02-20
+// 2023-05-29
+// 2023-06-19
+// 2023-07-04
+// 2023-09-04
+// 2023-10-09
+// 2023-11-10
+// 2023-11-11
+// 2023-11-23
+// 2023-12-25
+```
+
+Independence Day is an important holiday in the US. What details can Yasumi tell us about this holiday?
+Using the 'getHoliday' function we can retrieve information like the localized name, date and type of holiday of
+Independence Day:
+
+``` php
+// Get a holiday object for Independence Day
+$independenceDay = $holidays->getHoliday('independenceDay');
+
+// Get the localized name
+echo $independenceDay->getName() . PHP_EOL;
+
+// 'Independence Day'
+
+// Get the date
+echo $independenceDay . PHP_EOL;
+
+// '2023-07-04'
+
+// Get the type of holiday
+echo $independenceDay->getType() . PHP_EOL;
+
+// 'official'
+```
+
+Lastly, if you are a developer, you might be interested in getting the holiday information as a JSON object:
+
+``` php
+// Print the holiday as a JSON object
+echo json_encode($independenceDay, JSON_PRETTY_PRINT);
+
+// {
+//     "shortName": "independenceDay",
+//     "translations": {
+//         "en": "Independence Day"
+//     },
+//     "date": "2023-07-04 00:00:00.000000",
+//     "timezone_type": 3,
+//     "timezone": "America\/New_York"
+// }
+```

docs/recipes/between_filter.md

@@ -0,0 +1,49 @@
+# Holidays based on a given date range
+
+Let's say you are running an online store, and you want to send shoppers a promotion e-mail about new seasonal products.
+Yasumi can help you find holidays that occur in a certain date range.
+
+For your shoppers in Italy, you would like to know which holidays occur in December. Simply use the Yasumi
+'BetweenFilter' class like this:
+
+``` php
+<?php
+
+// Require the composer auto loader
+require 'vendor/autoload.php';
+
+$year = date('Y');
+
+// Use the factory to create a new holiday provider instance
+$holidays           = Yasumi\Yasumi::create('Italy', $year);
+$holidaysInDecember = $holidays->between(
+                        new DateTime('12/01/' . $year),
+                        new DateTime('12/31/' . $year)
+                      );
+```
+
+We then can see the following holidays in Italy in December:
+
+``` php
+foreach ($holidaysInDecember as $holiday) {
+    echo $holiday . ' - ' . $holiday->getName() . PHP_EOL;
+}
+
+// 2023-12-08 - Immaculate Conception
+// 2023-12-25 - Christmas
+// 2023-12-26 - St. Stephen’s Day
+```
+
+Using this, you can select new products that you would like to promote to your shoppers. Simple as that!
+
+Use the `count` method to show how many holidays are present:
+
+``` php
+echo $holidaysInDecember->count();
+
+// 3
+```
+
+> Yasumi works only with holidays for the year you have specified when creating the holiday provider instance.
+> This means that if you use either a start or end date beyond this year, holidays before or after the given year will
+> not be retrieved.

docs/recipes/custom_provider.md

@@ -0,0 +1,93 @@
+# Create a Custom Provider
+
+What if you want to manage holidays that are similar to those of a country but slightly different?
+
+A good example of such a situation is the observed holidays by the New York Stock
+Exchange ([NYSE](https://www.nyse.com/index)): All NYSE markets observe U.S. holidays however these differ somewhat from
+the standard Federal U.S. holidays:
+
+- The NYSE markets observe Good Friday as a holiday, where the Federal holidays do not celebrate this.
+- The NYSE markets do not observe Columbus Day and Veterans Day as an official holiday
+
+Yasumi is very flexible in that it can also work with custom holiday providers instead of the predefined
+holiday providers.
+
+First step is to create a custom class that extends an existing holiday provider. In this case, we are going to extend
+the USA Holiday Provider class to form a new custom provider that covers the NYSE observed holidays. This new class will
+then contain modifications that reflect differences from the U.S. holidays.
+
+The custom holiday provider class will look like this:
+
+```php
+/**
+ * Provider for all observed holidays by the NYSE (New York Stock Exchange)
+ */
+class NYSE extends \Yasumi\Provider\USA
+{
+    /**
+     * Initialize holidays for the NYSE.
+     * @throws \Exception
+     */
+    public function initialize(): void
+    {
+        parent::initialize();
+
+        // Add Good Friday
+        $this->addHoliday($this->goodFriday($this->year, $this->timezone, $this->locale));
+
+        // Remove Columbus Day and Veterans Day
+        $this->removeHoliday('columbusDay');
+        $this->removeHoliday('veteransDay');
+    }
+}
+```
+
+Here you can see, that we use Yasumi's `addHoliday` and `removeHoliday` methods to add Good Friday and,
+respectively, remove Columbus Day and Veterans Day from the internal list of defined holidays.
+
+Now we can instantiate a Yasumi Holiday Provider object with our new custom provider class:
+
+```php
+// Use the factory method to create a new holiday provider instance
+$NYSEHolidays = Yasumi\Yasumi::create(NYSE::class, 2023);
+```
+
+We then can retrieve the NYSE observed holidays in 2023 in the usual manner:
+
+```php
+// Display all holidays
+foreach ($NYSEHolidays as $day) {
+    echo $day->getName() . PHP_EOL;
+}
+
+// 'New Year’s Day observed'
+// 'New Year’s Day'
+// 'Dr. Martin Luther King Jr’s Birthday'
+// 'Washington’s Birthday'
+// 'Good Friday'
+// 'Memorial Day'
+// 'Juneteenth'
+// 'Juneteenth observed'
+// 'Independence Day'
+// 'Labor Day'
+// 'Thanksgiving Day'
+// 'Christmas'
+// 'Christmas observed'
+```
+
+```php
+// Use the count() method to show how many holidays are returned
+echo $NYSEHolidays->count() . PHP_EOL;
+
+// 10
+```
+
+> The `count` method does not double count holidays that are observed. Hence, in the example above 10 holidays are counted.
+
+As you can see, Yasumi's open design allows even for scenarios that are atypical. Alternatively, you can
+also create custom filters, however these are best suited for situations when you only need to exclude holidays from a
+Holiday Provider.
+
+Sources:
+
+* [NYSE Holidays and Trading Hours](https://www.nyse.com/markets/hours-calendars)

docs/recipes/filters.md

@@ -0,0 +1,54 @@
+# Filter only certain holidays
+
+Each Yasumi Holiday Provider contains many holidays that can be classified by different types. As you may
+want to select a specific set of holidays, Yasumi provides a number of filters that can help you with
+that. Yasumi comes currently with the following filters:
+
+- **Official** - Holidays that are marked as public or statutory.
+- **Observed** - Holidays that are not necessarily official however are being observed.
+- **Bank** - A public holiday in the United Kingdom, some Commonwealth countries and some other European countries.
+- **Seasonal** - Holidays that are celebrated due to its seasonal character (e.g. Halloween).
+- **Other** - Holidays that fall outside any of the above type.
+- **Between** - Filters all holidays between a given start and given end date. Check out
+  this [recipe](/recipes/between_filter.md) on how to use the Between filter.
+- **On** - Filters all holidays that happen on a given date.
+
+So, how do we for example go about getting only the official holidays from Yasumi? In that case we can
+use the 'OfficialHolidaysFilter'.
+
+First, we start with the basics, using the Netherlands as an example:
+
+``` php
+<?php
+
+// Require the composer auto loader
+require 'vendor/autoload.php';
+
+// Use the factory to create a new holiday provider instance
+$holidays = Yasumi\Yasumi::create('Netherlands', (int) date('Y'));
+```
+
+Then we include the following line to create the filter object for the official holidays:
+
+``` php
+$official = new Yasumi\Filters\OfficialHolidaysFilter($holidays->getIterator());
+```
+
+That's all it takes! Now, you can use the usual Yasumi API methods to process the holidays (which are now
+filtered). Which could look like this:
+
+``` php
+foreach ($official as $day) {
+    echo $day->getName() . PHP_EOL;
+}
+
+// 'New Year’s Day'
+// 'Easter Sunday'
+// 'Easter Monday'
+// 'Kings Day'
+// 'Ascension Day'
+// 'Whitsunday'
+// 'Whitmonday'
+// 'Christmas'
+// 'Second Christmas Day'
+```