DEV Community: Rapolas Gruzdys

How to structure, define and reuse Laravel routes with PHP objects

Rapolas Gruzdys — Sat, 19 Feb 2022 20:53:29 +0000

I find routing in Laravel wonderful: it's easy to understand, structured yet highly configurable and flexible,
and overall a pretty solid (pun intended) set of features. My only gripe with it is when it comes to
defining and generating/using your actual routes. Not sure about you, but I'm definitely tired of writing
route('really.long.route.name.that.is.hard.to.remember') over and over again.

At the time of writing, the route() helper only accepts a string for your desired route,
which means you're stuck with using hard coded strings for your route URLs and names.
Or maybe, there just aren't any clear alternative options. Let's explore that in this article.

Since software development is all about solving problems, let's start with a real-life example:

The problem

Let's imagine we have a big brand, with lots of informational pages. Our brand also holds a presence on Facebook.
Our pages may have any layout we can imagine, but one requirement is certain - we'll have navigation and a footer.
We want to display URLs to our Facebook page in both of those sections.

This means, that we have the same URL/route being used in (at least) two different places -
one in the navigation and one in the footer. Depending on the content and implementation, there might be even more.

We've gone ahead and defined these external routes, in a separate route file.
If you'd like to learn about this in more detail - check out this article.
A simple setup might look something like this:

The routes definition (routes/external.php for example):

<?php

use Illuminate\Support\Facades\Route;

Route::name('facebook.')->domain('https://www.facebook.com')->group(function () {
    Route::get('/AcmeCorp/reviews')->name('reviews');
    Route::get('/AcmeCorp/about')->name('about');
});

Let's identify what we've got here: we have a named group, consisting of a domain with two routes.

Now, all need to do is reference this route in our "navigation" and "footer" blade files.
Just type in route('facebook.about') once, then... type in route('facebook.about') the second time... and...
aaand we're duplicating ourselves. What happens when the application scales, and we need to reference visitors to
our FB page over, and over again? Or need to scatter "contact us" links around some articles?

Not to mention, unless you're using special (and sometimes paid) plugins, your IDE doesn't autocomplete this for you.
And you definitely don't remember all of your route names, which means you'll go over to your routes file,
search for your route, copy its name (or rather construct it since it is nested within three named groups),
go back to your original file and paste it in. Loads of fun.

Oh, you remember the name by heart, I hear you say? I'm sure every single one of us has acquainted ourselves with
the occasional typo. Don't want that, no, thank you.

And to top it all off - just imagine how many hard coded strings you'll have to change, once you eventually refactor
your route definitions. That would be a poor excuse, to not change your route group's name
to something more descriptive down the road.

So, what do we do?! Well, we could potentially use class constants to store our route names.
That could work, yes - we have a single defined string, which we're free to modify and our IDE autocompletes,
so we avoid typos. We can also easily find usages of the route!
But take a look at our route definition example once again. We have nested our routes in groups.

If we want to use class constants, we're forced to ditch this feature and define the full name
for every route definition, for example ->name(group.domain.resource.list), ->name(group.domain.resource.show) etc.
If we want to keep the feature, then we have to define route name prefixes in our class constants,
which I wouldn't really call "elegant". Take a look:

<?php

namespace App\Routing\Routes;

class FbRoutes
{
    // if we're not using constants, then we're duplicating the strings
    public const GROUP_NAME_FB = 'facebook.';
    // ... maybe more groups here ...

    public const NAME_REVIEWS = 'reviews';
    public const NAME_ABOUT = 'about';

    public const FULL_NAME_REVIEWS = self::GROUP_NAME_FB . self::FULL_NAME_REVIEWS;
    public const FULL_NAME_ABOUT = self::GROUP_NAME_FB . self::NAME_ABOUT;
}

Seems like this would be difficult to organize. Think how your route definition would look like 🤔.

Okay, so class constants are definitely a no-go. Alright, enough teasing. Seems like we could overcome all of
these issues by using something OOP languages do best - objects! Here's what I've found works rather well:

The solution

Currently, I've got two solutions which are very similar in terms of results. Both of them have a similar structure
and use case. Yet both of them come with pros and cons at the moment of writing. The first uses classes and requires more
boilerplate but is easier to reference. The other uses PHP 8.1 Enumerations - there's significantly less
boilerplate but has a caveat when it comes to referencing them.
I think that both of these are great approaches, so let's hit it off with classes:

Class approach

Basically, all we need is a class with some static methods, which abstract all of this string concatenation logic.
A similar approach can be found with the Feature ... erm feature... in
Laravel Jetstream.
For example, a method call to Feature::teams() just returns the name string of the feature: 'teams'.
This means that we can define simple static methods, and call a bunch of logic within them to construct our route
names however we please: a full name, only the name within the group, or even a URI.
It may look something like:

<?php

namespace App\Routing\Routes;

class FbRoutes
{
    public const GROUP_NAME = 'facebook.';

    public const NAME_REVIEWS = 'reviews';
    public const NAME_ABOUT = 'about';

    public function __construct(private string $routeName)
    {
    }

    public static function reviews(): self
    {
        return new self(self::NAME_REVIEWS);
    }

    public static function about(): self
    {
        return new self(self::NAME_ABOUT);
    }

    public function name(): string
    {
        return $this->routeName;
    }

    public function fullName(): string
    {
        return self::GROUP_NAME . $this->routeName;
    }

    public function path(): string
    {
        $paths = [
            self::NAME_REVIEWS => '/AcmeCorp/reviews',
            self::NAME_ABOUT => '/AcmeCorp/about',
        ];

        return $paths[$this->routeName];
    }

    public function __toString(): string
    {
        return $this->fullName();
    }
}

Here's how you can define your routes:

<?php

use App\Routing\Routes\JobRoutes;
use Illuminate\Support\Facades\Route;

Route::name(FbRoutes::GROUP_NAME)->group(function () {
    Route::get(FbRoutes::reviews()->path())->name(FbRoutes::reviews()->name());
    Route::get(FbRoutes::about()->path())->name(FbRoutes::about()->name());
});

Thanks to the __toString() method, you may now generate your routes with a simple method call
like route(FbRoutes::about()). Neat, this checks all the boxes:

No more hard coded strings, so our code is DRY and free of typos
Our code is easy to modify without refactoring a bunch of files
We get autocompletion from the IDE
The code definition for a class with methods has much less cognitive complexity.

The definition, however, is still rather extensive: it takes at least 4 lines to define a new route (5 if you
include the constant), and there's comparatively a lot of "logic" for the boilerplate. We can make this better!

Enums

With the release of PHP 8.1, we can simplify the above by using Enums.
Here's why I like them a bit more for this use case:

They're just objects - this means they can have properties, methods and implement interfaces
They are instanced with a static call, similar to class constants. Sexy! 😏
Thanks to this instancing, we have less boilerplate with the same amount of IDE support (no magic __callStatic() methods, etc.)

Here's the same approach with (backed) Enums:

<?php

namespace App\Routing\Routes;

enum FbRoutes: string
{
    public const GROUP_NAME = 'facebook.';

    case REVIEWS = 'reviews';
    case ABOUT = 'about';

    public function name(): string
    {
        return $this->value;
    }

    public function fullName(): string
    {
        return self::GROUP_NAME . $this->name();
    }

    public function path(): string
    {        
        return match($this) {
            self::REVIEWS => '/AcmeCorp/reviews',
            self::ABOUT => '/AcmeCorp/about',
        };
    }
}

You define the routes similar to classes:

<?php

use App\Routing\Routes\JobRoutes;
use Illuminate\Support\Facades\Route;

Route::name(FbRoutes::GROUP_NAME)->group(function () {
    Route::get(FbRoutes::REVIEWS->path())->name(FbRoutes::REVIEWS->name());
    Route::get(FbRoutes::ABOUT->path())->name(FbRoutes::ABOUT->name());
});

Unfortunately, because enums don't support the __toString() method, we must generate our routes with an
additional method call to the Enum: route(FbRoutes::ABOUT->fullName()).
Personally, I think this is the only downfall of the Enum approach, compared to the Class one.
It's also a major bummer for me 😞

However, this inconvenience can be somewhat mitigated. By changing our helper to generate routes, we may call
the ->fullName() method internally and call it a day! All we need is an interface to enforce the method and
typehint in the helper function.
Here's where I've faced the biggest limitation - we can not alter the route() function provided by Laravel.
This means we'd have to define a new helper function. To put it lightly - it's unconventional and therefore probably
not worth it for me personally.

In conclusion & TLDR

By now, I'm sure we're on the same page, why using hard coded strings for your route names isn't desirable.
You could also probably agree, that using simple class constants is neither "elegant" nor "flexible".
I'd say it's even messier than hard coded strings, in a way.

That's why you can leverage objects when it comes to managing your route names.
Whether it's Classes or Enums, the benefits are the same:

No hard coded strings, our code is DRY and free of typos
Code is SOLID - we only change a single class instead of many files
We get full IDE support

Just make sure to weigh your options between boilerplate and ease of use between the two approaches.
Personally, I favor Enums and can only hope for better support for them in the future.

Thanks for taking your time, I hope you've got some value from my post ✌️

How to structure and generate external URLs in Laravel

Rapolas Gruzdys — Sat, 19 Feb 2022 14:56:59 +0000

Laravel provides the features and structure for generating your application's URLs straight out of the box.
It includes URL generation, named routes, appending queries, and more.
This works well as long as we're generating URLs within our application.
As soon as it comes to external URLs, though, the framework doesn't really cover anything. Or so I've thought.

In this short post, I'll explain how you can use the internal Laravel's route feature set to generate your external URLs.
You might be wondering why. Since software development is all about solving problems, let's start with a real-life example:

The problem

For the past few months, I've been working on a web application, which is part of a bigger ecosystem of apps.
It is a simple platform that helps customers manage their plans for a virtual product -
see basic information, edit some settings, upgrade their plan and make some purchases.

The business already uses a different application for making purchases/placing orders, and also uses a lot of informational pages
that must be accessible from the whole ecosystem of apps.
So to keep everything maintainable and scalable, a decision was made to create a new separate app and keep its scope simple:
this means, instead of duplicating content or features, we need to link customers from the new application to external sources.

Sounds simple enough - just type in the desired URLs to the anchor tags, and you're done, right?

What happens when you need to reuse the same endpoint multiple times, in multiple pages/components?
Do you just copy and paste your URLs? What do you do when the endpoint or domain name changes for those external sources?
If you've only used hardcoded values in your templates, this could mean going over hundreds of templates/components and refactoring them.

Now sure, you could do yourself a favor and use some constants, and reference them in your templates.
This saves you from the headache when the URLs change, you'll avoid duplication and probably some typos too.
But where do you store those constants, how do you organize them? Do you create a config file or a class constant? Where do you place those?

Moreover, imagine that before displaying said URLs, you need to pre-process them, depending on the current user's request (like adding additional query parameters, etc.).
If you're using constants, you're back to square one - going over each of their usages, wrapping them in methods, or appending some values.

Well guess what - to solve all of these problems, we can actually repurpose Laravel's default route generation 😉
As mentioned previously, it already covers URL structuring, placement, and generating. Here's how:

The solution

We'll define our new routes in a standard Laravel routes file, register them with a new RouteServiceProvider and generate URLs with the route() helper function.
As always, I think examples work best, so let's imagine we're generating routes for our company's pages at Trustpilot and Facebook.

Let's get started:

1. Defining our routes.

Go ahead and create a new file in the routes directory. I'll call mine routes/external.php to place all of my external routes in a single file.
You can split them by provider here, if you wish, for example: routes/trustpilot.php, routes/facebook.php.

We'll learn how to define our routes more elegantly, at another time.
To simply get my point across, it may look something like:

<?php 

use Illuminate\Support\Facades\Route;

Route::name('trustpilot.')->domain('https://www.truspilot.com')->group(function () {
    Route::get('/review/acme.com')
        ->name('reviews');

    Route::get('/evaluate/acme.com')
        ->name('evaluate');
});

Route::name('facebook.')->domain('https://www.facebook.com')->group(function () {
    Route::get('/AcmeCorp/reviews')
        ->name('reviews');

    Route::get('/AcmeCorp/about')
        ->name('about');
});

As you can see, we're using the standard Laravel structure - routes are in their respectful directory,
we're only using the framework's native methods, and we're not using any workarounds to ensure future compatibility.
We're placing our routes in two groups that each use a domain name.
Since we're generating external routes, make sure those domains aren't bound to your current application.

You may also notice, that we didn't define an "action" (like controller methods) for our routes.
That's because Laravel's router accepts null for the second argument, which is registered as a Closure under the hood.
Please keep in mind that Laravel only supports caching routes (php artisan route:cache) with Closures since version 7.

2. Registering new routes

Laravel registers routes by the use of the Illuminate\Foundation\Support\Providers\RouteServiceProvider class.
By default, you should already have a class that implements it, which is usually found in App\Providers\RouteServiceProvider.

Since we've already defined our routes in a separate file, let's stay consistent and whip up a new service provider class.
You can either create a new class from scratch or just use the command provided by Laravel.

Let's call ours ExternalRouteServiceProvider:

php artisan make:provider ExternalRouteServiceProvider

Once the class has been created, make sure to also register it in your app's configuration at config/app.php.

With that out of the way, let's go ahead and extend the original service provider Illuminate\Foundation\Support\Providers\RouteServiceProvider.
It provides us with the routes() method, which we'll use to register the routes, just like in App\Providers\RouteServiceProvider.
I also like to prefix all of my route names as external in the provider.

At the end of the day, it looks something like this:

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\RouteServiceProvider;
use Illuminate\Support\Facades\Route;

class ExternalRouteServiceProvider extends RouteServiceProvider
{
    public function boot()
    {
        $this->routes(function () {
            Route::namespace($this->namespace)->name('external.')
                ->group(base_path('routes/external.php'));
        });
    }
}

And that's it! You should already see your routes by listing them:

php artisan route:list

+-------------------+----------+-------------------+-----------------------------+---------+------------+
| Domain            | Method   | URI               | Name                        | Action  | Middleware |
+-------------------+----------+-------------------+-----------------------------+---------+------------+
| www.truspilot.com | GET|HEAD | review/acme.com   | external.trustpilot.reviews | Closure |            |
| www.truspilot.com | GET|HEAD | evaluate/acme.com | external.truspilot.evaluate | Closure |            |
| www.facebook.com  | GET|HEAD | AcmeCorp/reviews  | external.facebook.reviews   | Closure |            |
| www.facebook.com  | GET|HEAD | AcmeCorp/about    | external.facebook.about     | Closure |            |
+----------------+----------+----------------------+-----------------------------+---------+------------+

3. Generating URLs by using routes

Now you can easily generate your external URLs the same way you do with the internal ones.
Let's say we want to list them in an arbitrary navigation component:

<nav>
  <ul>
    <li><a href="{{ route('external.trustpilot.reviews') }}">Trustpilot Reviews</a></li>
    <li><a href="{{ route('external.facebook.reviews') }}">Facebook Reviews</a></li>
    <li><a href="{{ route('external.truspilot.evaluate') }}">Review us on Trustpilot</a></li>
    <li><a href="{{ route('external.facebook.about') }}">About</a></li>
  </ul>
</nav>

Voilà, that's all there is to it! 👏

Conclusion & TLDR

With this approach, we:

Achieved a consistent and organized solution, by following the framework's provided structure.
Did little to no work and got all the benefits! We've just created a new route file, registered it in a new provider, and generated links with the default route() helper.
Can change our endpoints quickly and without refactoring a bunch of code.
And of course, we can pre-process the routes since we're not using hard-coded strings anymore. Just override the helper function.

Thanks for taking your time. I hope you've got some value from my post ✌️