devaspid / laravel-url-preview

1.0.0 2026-09-22 00:39 UTC

Requires

• php: ^8.1|^8.2|^8.3
• ext-dom: *
• ext-libxml: *
• illuminate/http: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• pestphp/pest: ^2.0|^3.0
• pestphp/pest-plugin-laravel: ^2.0|^3.0

MIT

• Aldi Setia Pambudi

Published on Packagist.org on 2026-09-22 00:40 UTC

README

A lightweight, secure, and customizable Open Graph URL preview scraper for Laravel. Designed with strict domain whitelist protection to prevent SSRF vulnerabilities, built-in caching, and a responsive Blade component supporting dark and light modes.

Developed and maintained by devASPid.

Requirements

• PHP: ^8.1, ^8.2, or ^8.3
• Extensions: ext-dom, ext-libxml
• Laravel: ^10.0, ^11.0, ^12.0, or ^13.0

Installation

You can install the package via Composer:

composer require devaspid/laravel-url-preview

Configuration & Publishing

Publish the configuration file using the vendor:publish Artisan command:

php artisan vendor:publish --tag="url-preview-config"

This will create a config/url-preview.php file in your project:

return [
    /*
    |--------------------------------------------------------------------------
    | Allowed Domains Whitelist
    |--------------------------------------------------------------------------
    |
    | Only domain names listed below will be processed for preview scraping.
    | This acts as a security safeguard against Server-Side Request Forgery (SSRF).
    |
    */
    'allowed_domains' => [
        'asp.web.id',
        'blog.asp.web.id',
        'youtube.com',
        'youtu.be',
        'instagram.com',
    ],

    /*
    |--------------------------------------------------------------------------
    | Cache TTL (Hours)
    |--------------------------------------------------------------------------
    */
    'cache_ttl' => 24,

    /*
    |--------------------------------------------------------------------------
    | HTTP Request Timeout (Seconds)
    |--------------------------------------------------------------------------
    */
    'timeout' => 3,

    /*
    |--------------------------------------------------------------------------
    | Watermark / Credit Badge Text
    |--------------------------------------------------------------------------
    */
    'powered_by' => 'devASPid',
];

Optionally, you can also publish the Blade views if you wish to customize the preview card layout:

php artisan vendor:publish --tag="url-preview-views"

Usage

1. Fetching Metadata in Controller / Livewire You can use the UrlPreview facade to fetch metadata for any URL. If the domain is not whitelisted or fails to respond, it returns null:

namespace App\Http\Controllers;

use Devaspid\UrlPreview\UrlPreviewFacade as UrlPreview;
use Illuminate\Http\Request;

class CampaignUpdateController extends Controller
{
    public function show($id)
    {
        $update = CampaignUpdate::findOrFail($id);
        
        // Extract URL from a long text/description using regex
        preg_match('/https?:\/\/[^\s"\'<>]+/i', $update->description, $matches);
        $url = $matches[0] ?? null;

        // Fetch Open Graph metadata (returns null if domain is not whitelisted)
        $previewData = $url ? UrlPreview::fetch($url) : null;

        return view('campaign.show', compact('update', 'previewData'));
    }
}

1. Rendering the Preview Card in Blade Render the preview card using the included Blade Component or @include. It automatically adapts to Tailwind CSS Light Mode and Dark Mode with cross-version inline line-clamp styling:

Using Blade Component Syntax:

<x-url-preview-card :data="$previewData" />

Using @include Syntax:

@include('url-preview::preview-card', ['data' => $previewData])

Data Structure When UrlPreview::fetch($url) succeeds, it returns an array formatted like this:

{
  "title": "About Us - Inside devASPid",
  "description": "Inside devASPid tech blog and updates",
  "image": "[https://blog.asp.web.id/wp-content/uploads/2025/09/blog.asp_.web_.id_.small_.webp](https://blog.asp.web.id/wp-content/uploads/2025/09/blog.asp_.web_.id_.small_.webp)",
  "site_name": "blog.asp.web.id",
  "icon": "[https://www.google.com/s2/favicons?domain=blog.asp.web.id&sz=64](https://www.google.com/s2/favicons?domain=blog.asp.web.id&sz=64)",
  "url": "[https://blog.asp.web.id/about-us/](https://blog.asp.web.id/about-us/)",
  "powered_by": "devASPid"
}

Testing

Run the test suite using Pest PHP:

composer test

License

This package is open-sourced software licensed under the MIT license.

Support the Project

If you find this project useful, consider giving it a ⭐ on GitHub.

Maintained with ❤️ by devASPId.

🌐 https://asp.web.id

🤝 https://asp.web.id/volunteer