Merge pull request #73 from spatie/feature/regions-v2

Add documentation on how to contribute

README.md

@@ -11,7 +11,7 @@ use Spatie\Holidays\Holidays;
 
 // returns an array of Belgian holidays
 // for the current year
-$holidays = Holidays::for('be')->get(); 
+$holidays = Holidays::for('be')->get();
 ```
 
 ## Support us
@@ -40,21 +40,22 @@ You can get all holidays for a country by using the `get` method.
 
 ```php
 use Spatie\Holidays\Holidays;
+use Spatie\Holidays\Countries\Belgium;
 
 // returns an array of Belgian holidays
 // for the current year
-$holidays = Holidays::for('be')->get(); 
+$holidays = Holidays::for(Belgium::make())->get(); 
 ```
 
-Alternatively, you could also pass an instance of `Country` to the `for` method.
+Alternatively, you could also pass an ISO code to the `for` method.
+But region specific holidays will not be included.
 
 ```php
 use Spatie\Holidays\Holidays;
-use Spatie\Holidays\Countries\Belgium;
 
 // returns an array of Belgian holidays
 // for the current year
-$holidays = Holidays::for(Belgium::make())->get(); 
+$holidays = Holidays::for('be')->get();
 ```
 
 ### Getting holidays for a specific year
@@ -87,6 +88,36 @@ use Spatie\Holidays\Holidays;
 Holidays::for('be')->getName('2024-01-01'); // Nieuwjaar
 ```
 
+## Contributing a new country
+
+If you want to add a new country, you can create a pull request.
+
+1. Create a new class in the `Countries` directory. It should extend the `Country` class.
+2. Add a test for the new country in the `tests` directory.
+
+In case your country has specific rules for calculating holidays,
+for example region specific holidays, you can pass this to the constructor of your country class.
+
+```php
+$holidays = Holidays::for(Austria::make('de-bw'))->get();
+
+class Austria extends Country
+{
+    protected function __construct(
+        protected ?string $region = null,
+    ) {
+    }
+
+    protected function allHolidays(int $year): array
+    {
+        // Here you can use $this->region (or other variables) to calculate holidays
+    }
+```
+
+Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for more details.
+
+
+
 ## Testing
 
 ```bash
@@ -97,10 +128,6 @@ composer test
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
 
-## Contributing
-
-Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.
-
 ## Security Vulnerabilities
 
 Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

src/Countries/Austria.php

@@ -6,6 +6,11 @@
 
 class Austria extends Country
 {
+    protected function __construct(
+        public ?string $region = null
+    ) {
+    }
+
     public function countryCode(): string
     {
         return 'at';

src/Countries/Country.php

@@ -37,7 +37,7 @@ public function get(int $year): array
 
     public static function make(): static
     {
-        return new static();
+        return new static(...func_get_args());
     }
 
     public static function find(string $countryCode): ?Country

tests/Countries/AustriaTest.php

@@ -3,6 +3,7 @@
 namespace Spatie\Holidays\Tests\Countries;
 
 use Carbon\CarbonImmutable;
+use Spatie\Holidays\Countries\Austria;
 use Spatie\Holidays\Holidays;
 
 it('can calculate austrian holidays', function () {
@@ -16,3 +17,15 @@
 
     expect(formatDates($holidays))->toMatchSnapshot();
 });
+
+it('can calculate austrian holidays with region holidays', function () {
+    CarbonImmutable::setTestNowAndTimezone('2024-01-01');
+
+    $holidays = Holidays::for(Austria::make('bg'))->get();
+
+    expect($holidays)
+        ->toBeArray()
+        ->not()->toBeEmpty();
+
+    expect(formatDates($holidays))->toMatchSnapshot();
+})->skip('Austria class has to be extended with regions first.');