Add support for a fallback locale (#71)

Author: tanerkay

README.md

@@ -30,7 +30,7 @@ I know you can get punished for this, but you are one of the hopes of those inno
 ## 🧩 Features
 
 - [Automatically register](#-register-routes) a route for each locale.
-- Use [URL slugs or custom domains](#%EF%B8%8F-supported-locales) (or subdomains).
+- Use [URL slugs or custom domains](#-supported-locales) (or subdomains).
 - Optionally [omit the locale slug from the URL for your main locale](#%EF%B8%8F-omit-slug-for-main-locale).
 - Optionally [translate each segment](#-translate-routes) in your URI's.
 - [Generate localized route URL's](#-generate-route-urls) using the `route()` helper.
@@ -90,6 +90,14 @@ Alternatively, you can use a different domain or subdomain for each locale by co
 ],
 ```
 
+#### ☑️ Fallback Locale
+
+When provided, this will be used as the fallback locale when a locale provided in the `route()` helper is not present in the list of supported locales.
+
+```php
+'fallback_locale' => 'en',
+```
+
 #### ☑️ Omit Slug for Main Locale
 
 Specify your main locale if you want to omit its slug from the URL:
@@ -378,6 +386,18 @@ $url = route('en.about', [], true, 'nl'); // /nl/about
 > If you do, you will always need to specify a locale to get the URL, because non-localized routes always have priority
 > when using the `route()` function.
 
+If the locale parameter for the `route()` helper is not a supported locale, and the route does not exist, a `RouteNotFoundException` will be thrown.
+
+A fallback locale can be provided in the config file. When provided, if the locale parameter for the `route()` helper is not a supported locale, the fallback locale will be used instead.
+
+```php
+// when `fallback_locale` is set to "en"
+// and supported locales are "en" and "nl"
+
+$url = route('about', [], true, 'nl'); // /nl/about
+$url = route('about', [], true, 'wk'); // /en/about
+```
+
 ### 🚌 Redirect to Routes
 
 Laravel's `Redirector` uses the same `UrlGenerator` as the `route()` function behind the scenes.

config/localized-routes.php

@@ -7,6 +7,11 @@
      */
     'supported-locales' => [],
 
+    /**
+     * The fallback locale to use when a provided locale is not supported.
+     */
+    'fallback_locale' => null,
+
     /**
      * If you have a main locale and don't want
      * to prefix it in the URL, specify it here.

src/UrlGenerator.php

@@ -54,6 +54,14 @@ public function route($name, $parameters = [], $absolute = true, $locale = null)
         // as a prefix for the route name.
         $locale = $locale ?: $currentLocale;
 
+        // Check if the locale is supported
+        if (!in_array($locale, config('localized-routes.supported-locales'))) {
+            // Use a fallback locale if provided
+            if (config('localized-routes.fallback_locale')) {
+                $locale = config('localized-routes.fallback_locale');
+            }
+        }
+
         // Normalize the route name by removing any locale prefix.
         // We will prepend the applicable locale manually.
         $baseName = $this->stripLocaleFromRouteName($name);

tests/TestCase.php

@@ -67,6 +67,18 @@ protected function setSupportedLocales($locales)
         Config::set('localized-routes.supported-locales', $locales);
     }
 
+    /**
+     * Set the fallback locale config option.
+     *
+     * @param string $locale
+     *
+     * @return void
+     */
+    protected function setFallbackLocale($locale): void
+    {
+        Config::set('localized-routes.fallback_locale', $locale);
+    }
+
     /**
      * Set the 'omit_url_prefix_for_locale' config option.
      *

tests/Unit/HelpersFileTest.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace CodeZero\LocalizedRoutes\Tests\Unit;
+
+use CodeZero\LocalizedRoutes\Tests\TestCase;
+use Illuminate\Support\Facades\Route;
+use Symfony\Component\Routing\Exception\RouteNotFoundException;
+
+class HelpersFileTest extends TestCase
+{
+    /** @test */
+    function it_returns_localized_routes_with_locale_argument(): void
+    {
+        $this->setSupportedLocales(['en', 'nl']);
+        $this->setAppLocale('en');
+
+        Route::localized(function () {
+            Route::get('route')->name('route');
+        });
+
+        $this->assertEquals(url('en/route'), route('route', [], true, null));
+        $this->assertEquals(url('en/route'), route('route', [], true, 'en'));
+        $this->assertEquals(url('nl/route'), route('route', [], true, 'nl'));
+    }
+
+    /** @test */
+    function it_throws_when_route_helper_locale_is_unsupported(): void
+    {
+        $this->setSupportedLocales(['en', 'nl']);
+        $this->setAppLocale('en');
+
+        Route::localized(function () {
+            Route::get('route')->name('route');
+        });
+
+        if ($this->app->version() < 6) {
+            $this->expectExceptionMessage('Route [wk.route] not defined.');
+        } else {
+            $this->expectException(RouteNotFoundException::class);
+        }
+
+        route('route', [], true, 'wk');
+    }
+
+    /** @test */
+    function it_uses_fallback_locale_when_route_helper_locale_is_unsupported(): void
+    {
+        $this->setSupportedLocales(['en', 'nl']);
+        $this->setAppLocale('en');
+        $this->setFallbackLocale('en');
+
+        Route::localized(function () {
+            Route::get('route')->name('route');
+        });
+
+        $this->assertEquals(url('en/route'), route('route', [], true, 'en'));
+        $this->assertEquals(url('nl/route'), route('route', [], true, 'nl'));
+        $this->assertEquals(url('en/route'), route('route', [], true, 'wk'));
+    }
+}