Ampliando la clase URI de Laravel con macros personalizados

#Comprendiendo la clase URI

La clase Illuminate\Support\Uri de Laravel ofrece una forma clara y orientada a objetos de trabajar con URL. Permite analizar, manipular y crear URL sin recurrir a las funciones nativas de URL de PHP ni a la manipulación de cadenas. Su uso básico sería de la siguiente forma:

use Illuminate\Support\Uri;

$uri = new Uri('https://laravel.com/docs/12.x');
echo $uri->getHost(); // laravel.com
echo $uri->getPath(); // /docs/12.x

Si bien esta API ya es bastante conveniente, Laravel ahora la ha hecho aún más poderosa y personalizable.

#El poder de Macroable

El trait Macroable es un patrón utilizado en Laravel que permite añadir métodos personalizados a clases existentes en tiempo de ejecución. Es una forma sencilla de ampliar la funcionalidad sin modificar el código fuente ni crear estructuras de herencia complejas.

Con la clase URI implementando este trait, puedes definir tus propios métodos de manipulación de URL que se ajusten a las necesidades específicas de tu aplicación.

#Creando tu primer macro para URI

Veamos cómo puedes crear una macro URI simple:

use Illuminate\Support\Uri;

Uri::macro('docs', fn () => $this->withPath('docs'));

$uri = new Uri('https://laravel.com/');
$docsUri = $uri->docs(); // https://laravel.com/docs

Esta macro agrega un método docs() a todas las instancias URI, lo que cambia la ruta a "docs" de forma práctica. Lo mejor es que se lee como un método nativo, lo que hace que el código sea claro e intuitivo.

#Ejemplo práctico

Exploremos un ejemplo más práctico. Imaginemos que está desarrollando una aplicación que necesita generar con frecuencia diferentes tipos de URL para su API:

use Illuminate\Support\Uri;

// Register macros in a service provider
class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        // Add version to API URL
        Uri::macro('v1', function () {
            return $this->withPath('api/v1/' . trim($this->getPath(), '/'));
        });
        
        // Convert to documentation URL
        Uri::macro('apiDocs', function () {
            $path = trim($this->getPath(), '/');
            return $this->withHost('docs.' . $this->getHost())
                        ->withPath($path);
        });
        
        // Create webhook URL
        Uri::macro('webhook', function ($event) {
            return $this->withPath('webhooks/' . $event);
        });
    }
}

// Usage in your application
$baseUri = new Uri('https://example.com/users');

// https://example.com/api/v1/users
$apiUri = $baseUri->v1(); 

// https://docs.example.com/users
$docsUri = $baseUri->apiDocs(); 

// https://example.com/webhooks/user.created
$webhookUri = $baseUri->webhook('user.created'); 

Este enfoque le permite crear un lenguaje específico de dominio para la manipulación de URL que se adapta perfectamente a las necesidades de su aplicación.