[2.x] Improve Routes facade method naming with find() and get()

RELEASE_NOTES.md

@@ -121,6 +121,10 @@ This serves two purposes:
 - Markdown headings are now compiled using our custom Blade-based heading renderer in https://github.com/hydephp/develop/pull/2047
     - The `id` attributes for heading permalinks have been moved from the anchor to the heading element in https://github.com/hydephp/develop/pull/2052
 - Colored Markdown blockquotes are now rendered using Blade and TailwindCSS, this change is not visible in the rendered result, but the HTML output has changed in https://github.com/hydephp/develop/pull/2056
+- **Improved Routes facade API with more intuitive method names** in https://github.com/hydephp/develop/pull/2179
+    - **Breaking:** Renamed `Routes::get()` to `Routes::find()` to better indicate it may return null
+    - **Breaking:** Renamed `Routes::getOrFail()` to `Routes::get()` to make the exception-throwing behavior the default and match Laravel conventions
+    - This change requires code updates if you were using these methods - see upgrade guide below
 
 ### Deprecated
 
@@ -536,6 +540,33 @@ Hyperlinks::isRemote($source);
 
 This change was implemented in https://github.com/hydephp/develop/pull/1883. Make sure to update any instances of `FeaturedImage::isRemote()` in your codebase to ensure compatibility with HydePHP v2.0.
 
+### Routes facade API changes
+
+The Routes facade API has been improved to better follow Laravel naming conventions and make the API more intuitive. This change affects code that directly uses the Routes facade methods.
+
+#### Changes
+
+- The `Routes::get()` method has been renamed to `Routes::find()` to better indicate that it may return null if a route is not found
+- The `Routes::getOrFail()` method has been renamed to `Routes::get()` to make the exception-throwing behavior the default, matching Laravel conventions
+
+#### Upgrade guide
+
+If you have used the Routes facade in your custom code, update it as follows:
+
+```php
+// Old code:
+$route = Routes::get('some-route'); // Returns null if not found
+$route = Routes::getOrFail('some-route'); // Throws exception if not found
+
+// New code:
+$route = Routes::find('some-route'); // Returns null if not found
+$route = Routes::get('some-route'); // Throws exception if not found
+```
+
+This change provides more intuitive method names and better type safety, with `find()` returning `?Route` and `get()` returning `Route`.
+
+This change was implemented in https://github.com/hydephp/develop/pull/2179.
+
 ## New Asset System
 
 ### Abstract

_pages/404.blade.php

@@ -31,7 +31,7 @@
                     Sorry, the page you are looking for could not be found.
                 </p>
 
-                <a href="{{ Routes::get('index') ?? '/' }}">
+                <a href="{{ Routes::find('index') ?? '/' }}">
                     <button class="bg-transparent text-grey-darkest font-bold uppercase tracking-wide py-3 px-6 border-2 border-grey-light hover:border-grey rounded-lg">
                         Go Home
                     </button>

packages/framework/resources/views/components/navigation/navigation-brand.blade.php

@@ -1,3 +1,3 @@
-<a href="{{ Routes::get('index') }}" class="font-bold px-4" aria-label="Home page">
+<a href="{{ Routes::find('index') }}" class="font-bold px-4" aria-label="Home page">
     {{ config('hyde.name', 'HydePHP') }}
 </a>

packages/framework/resources/views/pages/404.blade.php

@@ -31,7 +31,7 @@
                     Sorry, the page you are looking for could not be found.
                 </p>
 
-                <a href="{{ Routes::get('index') ?? '/' }}">
+                <a href="{{ Routes::find('index') ?? '/' }}">
                     <button class="bg-transparent text-grey-darkest font-bold uppercase tracking-wide py-3 px-6 border-2 border-grey-light hover:border-grey rounded-lg">
                         Go Home
                     </button>

packages/framework/src/Foundation/Facades/Routes.php

@@ -24,28 +24,46 @@ public static function getFacadeRoot(): RouteCollection
         return HydeKernel::getInstance()->routes();
     }
 
+    /**
+     * Check if a route exists by its route key.
+     */
     public static function exists(string $routeKey): bool
     {
         return static::getFacadeRoot()->has($routeKey);
     }
 
-    public static function get(string $routeKey): ?Route
+    /**
+     * Try to get a route by its route key. If it doesn't exist, null is returned.
+     */
+    public static function find(string $routeKey): ?Route
     {
         return static::getFacadeRoot()->get($routeKey);
     }
 
-    /** @throws \Hyde\Framework\Exceptions\RouteNotFoundException */
-    public static function getOrFail(string $routeKey): Route
+    /**
+     * Get a route by its route key. If it doesn't exist, an exception is thrown.
+     *
+     * @throws \Hyde\Framework\Exceptions\RouteNotFoundException
+     */
+    public static function get(string $routeKey): Route
     {
         return static::getFacadeRoot()->getRoute($routeKey);
     }
 
+    /**
+     * Get all the routes for the site as a collection of route instances, keyed by route key.
+     *
+     * @return \Hyde\Foundation\Kernel\RouteCollection<string, \Hyde\Support\Models\Route>
+     */
     public static function all(): RouteCollection
     {
         return static::getFacadeRoot()->getRoutes();
     }
 
-    /** Get the current route for the page being rendered. */
+    /**
+     * Get the route instance for the page currently being rendered.
+     * If a render is not in progress, this will return null.
+     */
     public static function current(): ?Route
     {
         return Hyde::currentRoute();

packages/framework/src/Framework/Views/Components/BreadcrumbsComponent.php

@@ -31,7 +31,7 @@ public function render(): ViewContract
     protected function makeBreadcrumbs(): array
     {
         $identifier = Hyde::currentRoute()->getPage()->getIdentifier();
-        $breadcrumbs = [(Routes::get('index')?->getLink() ?? '/') => 'Home'];
+        $breadcrumbs = [(Routes::find('index')?->getLink() ?? '/') => 'Home'];
 
         if ($identifier === 'index') {
             return $breadcrumbs;

packages/framework/src/Pages/Concerns/HydePage.php

@@ -309,7 +309,7 @@ public function getRouteKey(): string
      */
     public function getRoute(): Route
     {
-        return Routes::get($this->getRouteKey()) ?? new Route($this);
+        return Routes::find($this->getRouteKey()) ?? new Route($this);
     }
 
     /**

packages/framework/src/Pages/DocumentationPage.php

@@ -30,7 +30,7 @@ class DocumentationPage extends BaseMarkdownPage
 
     public static function home(): ?Route
     {
-        return Routes::get(static::homeRouteName());
+        return Routes::find(static::homeRouteName());
     }
 
     public static function homeRouteName(): string

packages/framework/tests/Unit/Facades/RouteFacadeTest.php

@@ -29,7 +29,7 @@ public function testGetOrFailThrowsExceptionIfRouteIsNotFound()
     {
         $this->expectException(RouteNotFoundException::class);
 
-        Routes::getOrFail('not-found');
+        Routes::get('not-found');
     }
 
     public function testGetReturnsRouteFromRouterIndex()
@@ -44,7 +44,7 @@ public function testGetReturnsRouteFromRouterIndexForTheRightPage()
 
     public function testGetFromReturnsNullIfRouteIsNotFound()
     {
-        $this->assertNull(Routes::get('not-found'));
+        $this->assertNull(Routes::find('not-found'));
     }
 
     public function testCurrentReturnsCurrentRoute()

packages/realtime-compiler/src/Http/DashboardController.php

@@ -296,7 +296,7 @@ protected function openInExplorer(): void
     protected function openPageInEditor(): void
     {
         $routeKey = $this->request->data['routeKey'] ?? $this->abort(400, 'Must provide routeKey');
-        $page = Routes::getOrFail($routeKey)->getPage();
+        $page = Routes::get($routeKey)->getPage();
 
         $binary = $this->findGeneralOpenBinary();
         $path = Hyde::path($page->getSourcePath());

packages/realtime-compiler/src/Routing/PageRouter.php

@@ -82,9 +82,9 @@ public static function handle(Request $request): Response
     protected function getPageFromRoute(): HydePage
     {
         try {
-            return Routes::getOrFail($this->normalizePath($this->request->path))->getPage();
+            return Routes::get($this->normalizePath($this->request->path))->getPage();
         } catch (RouteNotFoundException $exception) {
-            $index = Routes::get($this->normalizePath($this->request->path).'/index');
+            $index = Routes::find($this->normalizePath($this->request->path).'/index');
 
             if ($index) {
                 return $index->getPage();