Cast Laravel Model Fields to "Illuminate\Support\Uri" with "AsUri"

Introduction

I recently contributed a new feature to the Laravel framework that allows you to cast model properties to an instance of Illuminate\Support\Uri. This feature was added in PR #55909 and released in Laravel 12.17.

If you're not familiar with casts, you might be interested in my existing articles which cover them:

In this Quickfire article, I'm going to quickly cover how to use the new Illuminate\Database\Eloquent\Casts\AsUri cast in your Laravel models.

Casting Laravel Model Properties to "Illuminate\Support\Uri"

To provide some context about this feature, let's look at an example. Imagine we're building a URL shortener application, and we want to store the destination URL that the user should be redirected to when they visit the shortened URL.

Typically, we might want to treat this URL as a string in our application. However, Laravel now has a handy Illuminate\Support\Uri which allows us to work with URIs in a more structured way. It provides methods for manipulating and validating URIs, making it easier to work with URLs in our application.

So instead of passing the destination URL around our application as a string, we can cast it to an instance of Illuminate\Support\Uri instead. To do this, we can define the cast in our model like so:

declare(strict_types=1);
  
namespace App\Models;

use Illuminate\Database\Eloquent\Casts\AsUri;
use Illuminate\Database\Eloquent\Model;

final class ShortUrl extends Model
{
    protected function casts(): array
    {
        return [
            // ...
            'destination_url' => AsUri::class,
        ];
    }
}

As we can see in the code example above, we've specified that the destination_url field of our App\Models\ShortUrl model should use the Illuminate\Database\Eloquent\Casts\AsUri cast.

This means we can now set the destination_url field to an instance of Illuminate\Support\Uri, and it will automatically be converted to a string when saved to the database:

use Illuminate\Support\Uri;

$shortUrl->destination_url = new Uri(
  'https://www.example.com:1234/hello?param=value'
);

$shortUrl->save();

// The field in the database will now be the following string:
// https://www.example.com:1234/hello?param=value

And vice versa, we can read the destination_url field like so:

use Illuminate\Support\Uri;

// Assume the value in the database is the following string:
// https://www.example.com:1234/hello?param=value

$url = ShortUrl::first()->destination_url;

// $url will now be an instance of Illuminate\Support\Uri

// Illuminate\Support\Uri {
//   #uri: League\Uri\Uri {
//     -scheme: "https"
//     -user: null
//     -pass: null
//     -userInfo: null
//     -host: "www.example.com"
//     -port: 1234
//     -authority: "www.example.com:1234"
//     -path: "/hello"
//     -query: "param=value"
//     -fragment: null
//     -uri: "https://www.example.com:1234/hello?param=value"
//   }
// }

Conclusion

In this Quickfire article, we've taken a quick look at how to use the new Illuminate\Database\Eloquent\Casts\AsUri class to cast Laravel model properties to an instance of Illuminate\Support\Uri. This allows us to work with URIs in a more structured way, providing methods for manipulating and validating URIs.

If you enjoyed reading this post, you might be interested in checking out my 220+ page ebook "Battle Ready Laravel" which covers similar topics in more depth.

Or, you might want to check out my other 440+ page ebook "Consuming APIs in Laravel" which teaches you how to use Laravel to consume APIs from other services.

If you're interested in getting updated each time I publish a new post, feel free to sign up for my newsletter.

Keep on building awesome stuff! 🚀