Add 'orFail' variants to query methods

Author: inxilpro

src/Entity/Country.php

@@ -7,6 +7,7 @@
 use CommerceGuys\Addressing\Country\Country as BaseCountry;
 use CommerceGuys\Addressing\Subdivision\SubdivisionRepositoryInterface;
 use Galahad\LaravelAddressing\Collection\AdministrativeAreaCollection;
+use Galahad\LaravelAddressing\Exceptions\AdministrativeAreaNotFoundException;
 
 /**
  * @property-read $country_code
@@ -85,6 +86,15 @@ public function administrativeArea(string $code): ?AdministrativeArea
 			?? $this->administrativeAreas()->first(fn(AdministrativeArea $subdivision) => 0 === strcasecmp($subdivision->getCode(), $code));
 	}
 
+	public function administrativeAreaOrFail(string $code): AdministrativeArea
+	{
+		if ($administrative_area = $this->administrativeArea($code)) {
+			return $administrative_area;
+		}
+		
+		throw new AdministrativeAreaNotFoundException($this->getCountryCode(), $code);
+	}
+	
 	public function administrativeAreaByName(string $name): ?AdministrativeArea
 	{
 		return $this->administrativeAreas()

src/Entity/DecoratesEntity.php

@@ -5,12 +5,23 @@
 use BadMethodCallException;
 use Exception;
 use Illuminate\Support\Str;
+use Illuminate\Support\Traits\ForwardsCalls;
+use Illuminate\Support\Traits\Macroable;
 
 trait DecoratesEntity
 {
+	use ForwardsCalls;
+	use Macroable {
+		__call as macroCall;
+	}
+	
 	public function __call($name, $arguments)
 	{
-		return $this->decoratedEntity()->$name(...$arguments);
+		if (static::hasMacro($name)) {
+			return $this->macroCall($name, $arguments);
+		}
+		
+		return $this->forwardCallTo($this->decoratedEntity(), $name, $arguments);
 	}
 
 	public function __get($name)

src/Exceptions/AdministrativeAreaNotFoundException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Galahad\LaravelAddressing\Exceptions;
+
+use Illuminate\Database\RecordsNotFoundException;
+
+class AdministrativeAreaNotFoundException extends RecordsNotFoundException
+{
+	public function __construct(string $country_code, string $administrative_area_code)
+	{
+		parent::__construct("Unable to find administrative area '{$administrative_area_code}' in country '{$country_code}'.");
+	}
+}

src/Exceptions/CountryNotFoundException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Galahad\LaravelAddressing\Exceptions;
+
+use Illuminate\Database\RecordsNotFoundException;
+
+class CountryNotFoundException extends RecordsNotFoundException
+{
+	public function __construct(string $country_code)
+	{
+		parent::__construct("Unable to find country '{$country_code}'.");
+	}
+}

src/LaravelAddressing.php

@@ -8,9 +8,13 @@
 use CommerceGuys\Addressing\Subdivision\SubdivisionRepositoryInterface;
 use Galahad\LaravelAddressing\Collection\CountryCollection;
 use Galahad\LaravelAddressing\Entity\Country;
+use Galahad\LaravelAddressing\Exceptions\CountryNotFoundException;
+use Illuminate\Support\Traits\Macroable;
 
 class LaravelAddressing
 {
+	use Macroable;
+	
 	protected string $locale;
 
 	protected string $fallback_locale;
@@ -68,6 +72,15 @@ public function country(string $country_code, ?string $locale = null): ?Country
 
 		return $this->countries->get($country_code, null);
 	}
+	
+	public function countryOrFail(string $country_code, ?string $locale = null): Country
+	{
+		if ($country = $this->country($country_code, $locale)) {
+			return $country;
+		}
+		
+		throw new CountryNotFoundException($country_code);
+	}
 
 	/**
 	 * Get all countries as a collection.

src/Support/Facades/Addressing.php

@@ -9,6 +9,7 @@
 
 /**
  * @method static Country|null country($country_code, $locale = null)
+ * @method static Country countryOrFail($country_code, $locale = null)
  * @method static CountryCollection countries($locale = null)
  * @method static Country|null countryByName($name)
  * @method static Country|null findCountry($input)

tests/CountryEntityTest.php

@@ -5,6 +5,7 @@
 use Galahad\LaravelAddressing\Entity\AdministrativeArea;
 use Galahad\LaravelAddressing\Entity\Country;
 use Galahad\LaravelAddressing\Entity\Subdivision;
+use Galahad\LaravelAddressing\Exceptions\AdministrativeAreaNotFoundException;
 use Galahad\LaravelAddressing\Support\Facades\Addressing;
 
 class CountryEntityTest extends TestCase
@@ -88,6 +89,13 @@ public function test_it_returns_null_on_invalid_administrative_areas(): void
 	{
 		$this->assertNull($this->country->administrativeArea('XX'));
 	}
+	
+	public function test_it_triggers_an_exception_when_using_or_fail_method(): void
+	{
+		$this->expectException(AdministrativeAreaNotFoundException::class);
+		
+		$this->country->administrativeAreaOrFail('XX');
+	}
 
 	public function test_a_administrative_area_can_be_loaded_by_name(): void
 	{

tests/LaravelAddressingTest.php

@@ -3,6 +3,7 @@
 namespace Galahad\LaravelAddressing\Tests;
 
 use Galahad\LaravelAddressing\Entity\Country;
+use Galahad\LaravelAddressing\Exceptions\CountryNotFoundException;
 use Galahad\LaravelAddressing\LaravelAddressing;
 
 class LaravelAddressingTest extends TestCase
@@ -41,6 +42,13 @@ public function test_it_returns_null_when_an_unknown_country_code_is_provided():
 	{
 		$this->assertNull($this->addressing->country('XX'));
 	}
+	
+	public function test_it_triggers_an_exception_when_using_or_fail_method(): void
+	{
+		$this->expectException(CountryNotFoundException::class);
+		
+		$this->addressing->countryOrFail('XX');
+	}
 
 	public function test_a_country_can_be_loaded_by_its_name(): void
 	{