add fallback resource

README.md

@@ -6,6 +6,7 @@
 - [Grouping Resources](#grouping-resources)
 - [Bounded Resources](#bounded-resources)
 - [Wildcard Resources](#wildcard-resources)
+- [Fallback Resource](#fallback-resource)
 - [Resolving Resources](#resolving-resources)
 ### [Widgets](#widgets)
 - [Defining Widgets](#defining-widgets)
@@ -93,6 +94,22 @@ public static function wildcard(): bool
 
 When `wildcard` returns `true`, Flexi dispatches all paths prefixed by the resource's `uriKey`. As a result, you can access the ungrouped wildcard `Post` resource using the `http://localhost/posts/ANYTHING` URL, where `ANYTHING` can be any string combined with the URL path separator.
 
+
+### Wildcard Resources 
+Laravel's fallback routes allow you to handle undefined routes or 404 errors gracefully by redirecting them to a specific route or controller action. With the new feature added to the "Flexi" package, you can now specify a fallback resource, which is a Flexi resource, to handle these fallback routes within your Laravel application.
+If you want to determine a resource as fallback, override the `fallback` method of the resource:
+
+```bash  
+/**
+* Determine if the resource is a fallback resource.
+*/
+public static function fallback(): bool
+{
+    return true;
+}
+```
+
+This feature is handy when you want to customize the behavior of the fallback routes and provide a user-friendly experience when users encounter undefined routes or pages. pay attention that a `wildcard` `ungrouped` `unbounded` resource, also can work like a `fallback` resource.
 ### Resolving Resources
 Each resource generated by the Flexi command contains a `resolve` method that allows you to customize data retrieval and attach it to the resource after it is resolved by the request. For example, if you need to retrieve a model from the database for the requested resource, you can do so using the following approach:
 

src/Collections/ResourceCollection.php

@@ -15,11 +15,11 @@ public function find(string $key, mixed $default = null): ?string
     }
 
     /**
-     * Find first wildcard resource in the collection.
+     * Find first fallback resource in the collection.
      */
-    public function wildcard(): ?string
+    public function fallback(): ?string
     {
-        return $this->first(fn ($resource) => $resource::wildcard());
+        return $this->first(fn ($resource) => $resource::fallback());
     }
 
     /**

src/Flexi.php

@@ -128,11 +128,11 @@ public static function resourceForKey(string $key): ?string
     }
 
     /**
-     * Get the wildcard resource class name.
+     * Get the fallback resource class name.
      */
-    public static function wildcardResource(): ?string
+    public static function fallbackResource(): ?string
     {
-        return static::resourceCollection()->wildcard();
+        return static::resourceCollection()->fallback();
     }
 
     /**

src/Http/Requests/InteractsWithResources.php

@@ -57,7 +57,7 @@ public function newResource()
      */
     public function resource()
     {
-        return tap($this->matchedResource() ?? Flexi::wildcardResource(), function ($resource) {
+        return tap($this->matchedResource() ?? Flexi::fallbackResource(), function ($resource) {
             abort_if(is_null($resource), 404);
         });
     }

src/PendingRouteRegistration.php

@@ -66,6 +66,7 @@ public function mapWebRoutes(): void
             ->each(function ($resources, $group) {
                 Route::prefix($group)->group(function ($router) use ($resources) {
                     collect($resources)
+                        ->reject(fn ($resource) => $resource === Flexi::fallbackResource())
                         ->sortBy(fn ($resource) => intval($resource::wildcard()) - intval($resource::bounded()))
                         ->each(function ($resource) use ($router) {
                             $path = '/';
@@ -82,6 +83,10 @@ public function mapWebRoutes(): void
                         });
                 });
             });
+        // handle fallbacks
+        if ($fallbackResource = Flexi::fallbackResource()) {
+            Route::fallback([ResourceController::class, 'handle'])->name($fallbackResource::uriKey());
+        }
     }
 
     /**

src/Resource.php

@@ -38,6 +38,14 @@ public static function bounded(): bool
         return true;
     }
 
+    /**
+     * Determine if the resource is a fallback resource.
+     */
+    public static function fallback(): bool
+    {
+        return false;
+    }
+
     /**
      * Get the resource name.
      */

tests/Feature/APITest.php

@@ -3,14 +3,15 @@
 use Flexi\Events\ResourceMatched;
 use Flexi\Events\WidgetRendered;
 use Flexi\Flexi;
+use Flexi\Tests\Fixtures\Fallback;
 use Flexi\Tests\Fixtures\Grouped;
-use Flexi\Tests\Fixtures\GroupedWildcard;
 use Flexi\Tests\Fixtures\GroupedUnbounded;
 use Flexi\Tests\Fixtures\GroupedUnboundedWildcard;
+use Flexi\Tests\Fixtures\GroupedWildcard;
 use Flexi\Tests\Fixtures\Ungrouped;
-use Flexi\Tests\Fixtures\UngroupedWildcard;
 use Flexi\Tests\Fixtures\UngroupedUnbounded;
 use Flexi\Tests\Fixtures\UngroupedUnboundedWildcard;
+use Flexi\Tests\Fixtures\UngroupedWildcard;
 use Flexi\Tests\Fixtures\Widgetized;
 use Flexi\Tests\Fixtures\Widgets\TestWidget;
 use Illuminate\Support\Facades\Event;
@@ -101,3 +102,13 @@
     Event::assertDispatched(ResourceMatched::class, fn ($event) => $event->resource->uriKey() === Widgetized::uriKey());
     Event::assertDispatched(WidgetRendered::class, fn ($event) => $event->widget instanceof TestWidget);
 });
+
+// test fallback resource
+it('find fallback resource', function () {
+    Event::fake();
+
+    Flexi::replaceResources([Fallback::class]);
+
+    $this->get(time())->assertStatus(200);
+    Event::assertDispatched(ResourceMatched::class, fn ($event) => $event->resource->uriKey() === Fallback::uriKey());
+});

tests/Fixtures/Fallback.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Flexi\Tests\Fixtures;
+
+use Flexi\Http\Requests\FlexiRequest;
+use Flexi\Resource;
+
+class Fallback extends Resource
+{
+    /**
+     * Determine if the resource is a fallback resource.
+     */
+    public static function fallback(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Resolve the resource for incoming request.
+     */
+    public function resolve(FlexiRequest $request)
+    {
+
+    }
+}