Skip to main content

UrlResource

The UrlResource transforms the Url model into a structured JSON resource for API responses.

Namespace​

JobMetric\Url\Http\Resources\UrlResource

Overview​

The resource provides:

  • Structured output: Consistent JSON format
  • ISO 8601 timestamps: Standard datetime formatting
  • Version information: URL version number
  • Related model: Urlable model resource (via event)

When to Use UrlResource​

Use UrlResource when you need:

  • API responses: Return URL data in API endpoints
  • Structured output: Consistent JSON format for URLs
  • Version history: Display URL version information
  • Related model data: Include urlable model information

Example scenarios:

  • API endpoints returning URL information
  • URL history endpoints
  • Admin panels showing URL details
  • Version tracking interfaces

Resource Structure​

{
  "urlable_type": "App\\Models\\Product",
  "urlable_id": 1,
  "full_url": "/shop/laptops/macbook-pro-14",
  "collection": "products",
  "version": 1,
  "deleted_at": null,
  "created_at": "2024-01-01T00:00:00.000000Z",
  "updated_at": "2024-01-01T00:00:00.000000Z",
  "urlable": {
    // Resource from UrlableResourceEvent
  }
}

Field Details​

FieldTypeDescription
urlable_typestringModel class name (polymorphic)
urlable_idintModel ID (polymorphic)
full_urlstringComplete canonical URL (max 2000 chars)
collectionstring|nullOptional collection name
versionintVersion number (starts at 1)
deleted_atstring|nullSoft delete timestamp (ISO 8601)
created_atstringCreation timestamp (ISO 8601)
updated_atstringUpdate timestamp (ISO 8601)
urlablemixedRelated model resource (from event)

Usage​

Basic Usage​

use JobMetric\Url\Http\Resources\UrlResource;
use JobMetric\Url\Models\Url;

$url = Url::find(1);
return new UrlResource($url);

In API Responses​

namespace App\Http\Controllers;

use App\Models\Product;
use JobMetric\Url\Http\Resources\UrlResource;

class ProductController extends Controller
{
    public function urlHistory(Product $product)
    {
        $urls = $product->urlHistory();
        return UrlResource::collection($urls);
    }
}

Complete Examples​

Example 1: Single URL Resource​

$url = Url::find(1);
return new UrlResource($url);

Example 2: URL History Collection​

$product = Product::find(1);
$urls = $product->urlHistory();
return UrlResource::collection($urls);

Example 3: Active URL Only​

$product = Product::find(1);
$activeUrl = $product->urlRecord()->first();
return new UrlResource($activeUrl);
// Listen to UrlableResourceEvent to provide related model resource
Event::listen(UrlableResourceEvent::class, function (UrlableResourceEvent $event) {
    if ($event->urlable instanceof Product) {
        $event->resource = new ProductResource($event->urlable);
    }
});

$url = Url::find(1);
return new UrlResource($url);
// urlable field will contain ProductResource

Example 5: API Endpoint​

Route::get('/api/products/{product}/urls', function (Product $product) {
    $urls = $product->urlHistory();
    return UrlResource::collection($urls);
});
  • Url Model - Model that this resource transforms
  • HasUrl Trait - Trait that manages URLs
  • Events - UrlableResourceEvent for related model