PHPackages cleaniquecoders/shrinkr - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. cleaniquecoders/shrinkr ActiveLibrary[Utility & Helpers](/categories/utility) cleaniquecoders/shrinkr ======================= Shrinkr is a Laravel package for shortening URLs, with custom slugs, analytics, branded domains, and seamless API integration. 1.1.0(1y ago)142.9k↓30.8%[1 issues](https://github.com/cleaniquecoders/shrinkr/issues)MITPHPPHP ^8.2 | ^8.3 | ^8.4CI passing Since Oct 19Pushed 1mo agoCompare [ Source](https://github.com/cleaniquecoders/shrinkr)[ Packagist](https://packagist.org/packages/cleaniquecoders/shrinkr)[ Docs](https://github.com/cleaniquecoders/shrinkr)[ GitHub Sponsors]()[ RSS](/packages/cleaniquecoders-shrinkr/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (6)Dependencies (14)Versions (6)Used By (0) [![Latest Version on Packagist](https://camo.githubusercontent.com/2320a2c09b90f3483eb74aea8a3f6162cf4d6ab36ffd44b37b0c12f2b980175a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f636c65616e69717565636f646572732f736872696e6b722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cleaniquecoders/shrinkr)[![GitHub Tests Action Status](https://camo.githubusercontent.com/d39799f1cfec2960f42d21f2b7bd78f2a4845d17c5847470516c511e117d64b3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f636c65616e69717565636f646572732f736872696e6b722f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/cleaniquecoders/shrinkr/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/fc29ecf77c9a517c4df9afdfcc658f946ef980c997739ff2ea0fba77e408e314/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f636c65616e69717565636f646572732f736872696e6b722f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/cleaniquecoders/shrinkr/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/c995703a9f1c3fc51bc53192d352a3a82474a506fb44cf6a5f058a47e136f10b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f636c65616e69717565636f646572732f736872696e6b722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cleaniquecoders/shrinkr) Shrinkr ======= [](#shrinkr) **Shrinkr** is a powerful Laravel package for shortening URLs with custom slugs, comprehensive analytics, health monitoring, and seamless integration. Transform long URLs into short, shareable links with features like **custom slugs**, **click tracking**, **branded domains**, **expiry management**, and **health monitoring**. --- Features -------- [](#features) ✅ **URL Shortening** - Create short URLs with auto-generated or custom slugs ✅ **Analytics Tracking** - Track clicks, referrers, IP addresses, browsers, and devices ✅ **Branded Domains** - Use custom domains for your shortened URLs ✅ **Expiry Management** - Set expiration times for temporary links ✅ **Health Monitoring** - Automatically check if original URLs are still reachable ✅ **Event System** - React to URL access and expiry events ✅ **Flexible Logging** - Log to files or database ✅ **Rate Limiting** - Built-in middleware to prevent abuse ✅ **Artisan Commands** - Automate maintenance tasks --- Quick Start ----------- [](#quick-start) ### Installation [](#installation) ``` composer require cleaniquecoders/shrinkr php artisan vendor:publish --tag="shrinkr-migrations" php artisan migrate php artisan vendor:publish --tag="shrinkr-config" ``` ### Basic Usage [](#basic-usage) ``` use CleaniqueCoders\Shrinkr\Facades\Shrinkr; // Shorten a URL $shortUrl = Shrinkr::shorten('https://example.com/long-url', auth()->id()); // Result: https://yourdomain.com/s/abc123 // With custom slug $shortUrl = Shrinkr::shorten('https://example.com', auth()->id(), [ 'custom_slug' => 'my-link', ]); // Result: https://yourdomain.com/s/my-link // With expiry (60 minutes) $shortUrl = Shrinkr::shorten('https://example.com', auth()->id(), [ 'expiry_duration' => 60, ]); // Resolve short URL to original $originalUrl = Shrinkr::resolve('abc123'); ``` --- Documentation ------------- [](#documentation) For comprehensive documentation, see the [docs](docs/) directory: - **[Getting Started](docs/01-getting-started/)** - Installation, configuration, and quick start - **[Configuration](docs/02-configuration/)** - Complete configuration reference - **[Usage](docs/03-usage/)** - Shortening, resolving, updating, and deleting URLs - **[Features](docs/04-features/)** - Analytics, expiry, events, health monitoring - **[API Reference](docs/05-api-reference/)** - Complete API documentation - **[Development](docs/06-development/)** - Testing and contributing ### Key Documentation Pages [](#key-documentation-pages) - [Installation Guide](docs/01-getting-started/01-installation.md) - [Quick Start Guide](docs/01-getting-started/03-quick-start.md) - [Configuration Reference](docs/02-configuration/01-complete-reference.md) - [Shortening URLs](docs/03-usage/01-shortening-urls.md) - [Analytics Tracking](docs/04-features/02-analytics.md) - [URL Expiry](docs/04-features/01-url-expiry.md) - [Health Monitoring](docs/04-features/04-health-monitoring.md) --- --- **Usage** --------- [](#usage) Here’s a basic usage example using the Shrinkr facade, actions, and events. --- ### **1. Shorten a URL** [](#1-shorten-a-url) You can shorten a URL with or without a **custom slug** and **expiry duration**. ``` use CleaniqueCoders\Shrinkr\Facades\Shrinkr; // Shorten a URL with default random slug $shortUrl = Shrinkr::shorten('https://example.com/long-url', auth()->id()); echo $shortUrl; // Outputs: https://yourdomain.com/abc123 // Shorten a URL with a custom slug and expiry duration (e.g., 60 minutes) $shortUrlWithCustomSlug = Shrinkr::shorten('https://example.com/long-url', auth()->id(), [ 'custom_slug' => 'my-slug', 'expiry_duration' => 60, // Expires in 60 minutes ]); echo $shortUrlWithCustomSlug; // Outputs: https://yourdomain.com/my-slug ``` --- ### **2. Retrieve the Original URL** [](#2-retrieve-the-original-url) Use the `resolve()` method to retrieve the **original URL** from a shortened one. ``` $originalUrl = Shrinkr::resolve('abc123'); echo $originalUrl; // Outputs: https://example.com/long-url ``` When the URL is accessed, the **`UrlAccessed` event** will be dispatched automatically to track the visit. --- ### **3. Update an Existing Short URL** [](#3-update-an-existing-short-url) You can update an existing short URL with a new **custom slug** or **expiry duration**. ``` use CleaniqueCoders\Shrinkr\Models\Url; use CleaniqueCoders\Shrinkr\Facades\Shrinkr; $url = Url::find(1); // Update the short URL with a new slug and expiry duration $updatedUrl = Shrinkr::update($url, [ 'custom_slug' => 'updated-slug', 'expiry_duration' => 120, // 2 hours from now ]); echo $updatedUrl->shortened_url; // Outputs: https://yourdomain.com/updated-slug ``` --- ### **4. Event Handling** [](#4-event-handling) #### **UrlAccessed Event** [](#urlaccessed-event) The **`UrlAccessed` event** is dispatched whenever a shortened URL is accessed. You can listen for this event to **log analytics or trigger notifications**. **Example: Log URL Access in a Listener** ``` namespace CleaniqueCoders\Shrinkr\Listeners; use CleaniqueCoders\Shrinkr\Events\UrlAccessed; use Illuminate\Support\Facades\Log; class LogUrlAccess { public function handle(UrlAccessed $event) { $url = $event->url; Log::info('URL accessed', [ 'url_id' => $url->id, 'shortened_url' => $url->shortened_url, 'accessed_at' => now(), ]); } } ``` #### **UrlExpired Event** [](#urlexpired-event) The **`UrlExpired` event** is dispatched when a URL has expired, either through a scheduled check or upon access. You can listen to this event to **notify the user or perform other actions**. **Example: Notify on URL Expiry in a Listener** ``` namespace CleaniqueCoders\Shrinkr\Listeners; use CleaniqueCoders\Shrinkr\Events\UrlExpired; use Illuminate\Support\Facades\Log; class NotifyUrlExpired { public function handle(UrlExpired $event) { $url = $event->url; Log::warning('URL expired', [ 'url_id' => $url->id, 'shortened_url' => $url->shortened_url, 'expired_at' => now(), ]); // Optionally, notify the user about the expired URL. } } ``` --- ### **5. Automatically Expire URLs** [](#5-automatically-expire-urls) If you’ve set an **expiry duration**, the URL will be marked as expired once that time has passed. You can also run the **expiry command** manually or schedule it. **Run the Expiry Command Manually:** ``` php artisan shrinkr:check-expiry ``` **Schedule the Expiry Command:** In your **`app/Console/Kernel.php`**: ``` $schedule->command('shrinkr:check-expiry')->hourly(); ``` --- ### **6. Monitor URL Health** [](#6-monitor-url-health) The **Link Health Monitoring** feature allows you to **check if URLs are reachable** and mark them as **active or expired**. #### **Check Health Action** [](#check-health-action) Use the `CheckUrlHealthAction` to **manually check the health** of a specific URL. ``` use CleaniqueCoders\Shrinkr\Actions\CheckUrlHealthAction; use CleaniqueCoders\Shrinkr\Models\Url; $url = Url::find(1); // Retrieve URL instance $action = new CheckUrlHealthAction(); $isHealthy = $action->execute($url); if ($isHealthy) { echo "URL is active."; } else { echo "URL is expired."; } ``` #### **Check Health Command** [](#check-health-command) Use the Artisan command to **check the health of all URLs** in bulk. ``` php artisan shrinkr:check-health ``` This command will: 1. **Check the status** of all URLs. 2. **Mark expired URLs** and dispatch the `UrlExpired` event. 3. **Provide real-time output** on the status of each URL. Example output: ``` URL abc123 is now marked as active. URL xyz456 is now marked as expired. URL health check completed. ``` #### **Schedule the Health Check Command** [](#schedule-the-health-check-command) You can **automatically run the health check** at regular intervals using Laravel’s scheduler. In your **`app/Console/Kernel.php`**: ``` protected function schedule(Schedule $schedule) { $schedule->command('shrinkr:check-health')->hourly(); } ``` This will ensure that all URLs are **continuously monitored** and marked as expired when necessary. --- ### **7. Redirect Tracking** [](#7-redirect-tracking) The redirect feature tracks detailed information such as: - **IP address** of the visitor - **Browser and OS** (via User-Agent parsing) - **Referrer** (where the link was clicked) - **Headers and query parameters** - Optionally **store logs in a database** or log file Example database log entry: url\_idipbrowserplatformreferrercreated\_at1192.168.1.1ChromeWindowsgoogle.com2024-10-18 12:34:56--- ### **8. Routing** [](#8-routing) You can configure custom domain for the URL by configuring: ``` 'domain' => 'bite.ly', ``` You may also change the middleware or add new one by configuring: ``` 'middleware' => ['auth', 'verified', 'throttle:600,1'] ``` Testing ------- [](#testing) Run the tests using: ``` composer test ``` --- Changelog --------- [](#changelog) Refer to the [CHANGELOG](CHANGELOG.md) for the latest updates and changes. --- Contributing ------------ [](#contributing) We welcome contributions! Please see [CONTRIBUTING](CONTRIBUTING.md) for guidelines. --- Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Report security vulnerabilities by reviewing [our security policy](../../security/policy). --- Credits ------- [](#credits) - [Nasrul Hazim Bin Mohamad](https://github.com/nasrulhazim) - [All Contributors](../../contributors) --- License ------- [](#license) Shrinkr is open-sourced software licensed under the [MIT license](LICENSE.md). ### Health Score 46 — FairBetter than 93% of packages Maintenance72 Regular maintenance activity Popularity29 Limited adoption so far Community6 Small or concentrated contributor base Maturity60 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~48 days Total 5 Last Release 375d ago PHP version history (2 changes)v1.0.0PHP ^8.2 1.1.0PHP ^8.2 | ^8.3 | ^8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/b57069d0f4b634f65eccc6e5d5848990e25968d45ec2cf46d626c6a4658f944b?d=identicon)[nasrulhazim.m](/maintainers/nasrulhazim.m) --- Top Contributors [![nasrulhazim](https://avatars.githubusercontent.com/u/10341422?v=4)](https://github.com/nasrulhazim "nasrulhazim (58 commits)") --- Tags laravelphpshortenerlaravelCleanique Codersshrinkr ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/cleaniquecoders-shrinkr/health.svg) ``` [![Health](https://phpackages.com/badges/cleaniquecoders-shrinkr/health.svg)](https://phpackages.com/packages/cleaniquecoders-shrinkr) ``` ### Alternatives [spatie/laravel-data Create unified resources and data transfer objects 1.7k28.9M627](/packages/spatie-laravel-data)[hirethunk/verbs An event sourcing package that feels nice. 513162.9k6](/packages/hirethunk-verbs)[worksome/exchange Check Exchange Rates for any currency in Laravel. 123544.7k](/packages/worksome-exchange)[ralphjsmit/livewire-urls Get the previous and current url in Livewire. 82270.3k4](/packages/ralphjsmit-livewire-urls)[hydrat/filament-table-layout-toggle Filament plugin adding a toggle button to tables, allowing user to switch between Grid and Table layouts. 6292.3k1](/packages/hydrat-filament-table-layout-toggle)[ralphjsmit/laravel-helpers A package containing handy helpers for your Laravel-application. 13704.6k2](/packages/ralphjsmit-laravel-helpers) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)