PHPackages ashallendesign/short-url - 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. ashallendesign/short-url ActiveLibrary[Utility & Helpers](/categories/utility) ashallendesign/short-url ======================== A Laravel package for creating shortened URLs for your web apps. v8.5.0(2mo ago)1.4k1.9M—5.1%179[2 issues](https://github.com/ash-jc-allen/short-url/issues)[3 PRs](https://github.com/ash-jc-allen/short-url/pulls)4MITPHPPHP ^8.2CI failing Since Dec 30Pushed 2mo ago16 watchersCompare [ Source](https://github.com/ash-jc-allen/short-url)[ Packagist](https://packagist.org/packages/ashallendesign/short-url)[ Docs](https://github.com/ash-jc-allen/short-url)[ GitHub Sponsors](https://github.com/ash-jc-allen)[ RSS](/packages/ashallendesign-short-url/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (22)Versions (62)Used By (4) [![](https://camo.githubusercontent.com/f0a648b5b6677dd3b6b70465651c28d0515d98120df9f6459a6d3902a34a3603/68747470733a2f2f617368616c6c656e64657369676e2e636f2e756b2f696d616765732f637573746f6d2f73686f72742d75726c2d6c6f676f2e706e67)](https://camo.githubusercontent.com/f0a648b5b6677dd3b6b70465651c28d0515d98120df9f6459a6d3902a34a3603/68747470733a2f2f617368616c6c656e64657369676e2e636f2e756b2f696d616765732f637573746f6d2f73686f72742d75726c2d6c6f676f2e706e67) [![Latest Version on Packagist](https://camo.githubusercontent.com/afb14357e4b9ba1dd1bd44cebe2b5862f120521d2cc7286ecd87f8f3b4f8ab75/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f617368616c6c656e64657369676e2f73686f72742d75726c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ashallendesign/short-url)[![Total Downloads](https://camo.githubusercontent.com/acf6d134dfdf33ccea474447226f0579bf13038d2b38ec40294d0c2a18f573dc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f617368616c6c656e64657369676e2f73686f72742d75726c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ashallendesign/short-url)[![PHP from Packagist](https://camo.githubusercontent.com/3cd51f0e77b948048ba7f6fd58f0a6441c9bf82c839bf2d66d0ce31f72321f10/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f617368616c6c656e64657369676e2f73686f72742d75726c3f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ashallendesign/short-url)[![GitHub license](https://camo.githubusercontent.com/cfe5353b361b8b8cbc793ee149b736b20c678a9535e3f6ccd6a32b1868aee18a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6173682d6a632d616c6c656e2f73686f72742d75726c3f7374796c653d666c61742d737175617265)](https://github.com/ash-jc-allen/short-url/blob/master/LICENSE) Table of Contents ----------------- [](#table-of-contents) - [Overview](#overview) - [Installation](#installation) - [Requirements](#requirements) - [Install the Package](#install-the-package) - [Publish the Config and Migrations](#publish-the-config-and-migrations) - [Migrate the Database](#migrate-the-database) - [Usage](#usage) - [Building Shortened URLs](#building-shortened-urls) - [Quick Start](#quick-start) - [Custom Keys](#custom-keys) - [Tracking Visitors](#tracking-visitors) - [Enabling Tracking](#enabling-tracking) - [Tracking IP Address](#tracking-ip-address) - [Tracking Browser & Browser Version](#tracking-browser--browser-version) - [Tracking Operating System & Operating System Version](#tracking-operating-system--operating-system-version) - [Tracking Device Type](#tracking-device-type) - [Tracking Referer URL](#tracking-referer-url) - [Custom Short URL Fields](#custom-short-url-fields) - [Single Use](#single-use) - [Enforce HTTPS](#enforce-https) - [Forwarding Query Parameters](#forwarding-query-parameters) - [Redirect Status Code](#redirect-status-code) - [Activation and Deactivation Times](#activation-and-deactivation-times) - [Using a Custom Seed](#using-a-custom-seed) - [Facade](#facade) - [Conditionals](#conditionals) - [Using the Shortened URLs](#using-the-shortened-urls) - [Default Route and Controller](#default-route-and-controller) - [Custom Route](#custom-route) - [Tracking](#tracking) - [Customisation](#customisation) - [Disabling the Default Route](#disabling-the-default-route) - [Default URL Key Length](#default-url-key-length) - [Tracking Visits](#tracking-visits) - [Default Tracking](#default-tracking) - [Tracking Fields](#tracking-fields) - [Config Validation](#config-validation) - [Custom Database Connection](#custom-database-connection) - [Specifying the Key Generator](#specifying-the-key-generator) - [Specifying the User Agent Parser](#specifying-the-user-agent-parser) - [Specifying the Allowed URL Schemes](#specifying-the-allowed-url-schemes) - [Helper Methods](#helper-methods) - [Visits](#visits) - [Find by URL Key](#find-by-url-key) - [Find by Destination URL](#find-by-destination-url) - [Tracking Enabled](#tracking-enabled) - [Tracked Fields](#tracked-fields) - [Events](#events) - [Short URL Visited](#short-url-visited) - [Model Factories](#model-factories) - [Testing](#testing) - [Security](#security) - [Contribution](#contribution) - [Credits](#credits) - [Changelog](#changelog) - [Upgrading](#upgrading) - [License](#license) Overview -------- [](#overview) A Laravel package that can be used for adding shortened URLs to your existing web app. Installation ------------ [](#installation) ### Requirements [](#requirements) The package has been developed and tested to work with the following minimum requirements: - PHP 8.2 - Laravel 10.0 Short URL requires either the [BC Math](https://secure.php.net/manual/en/book.bc.php) or [GMP](https://secure.php.net/manual/en/book.gmp.php) PHP extensions in order to work. ### Install the Package [](#install-the-package) You can install the package via Composer: ``` composer require ashallendesign/short-url ``` ### Publish the Config and Migrations [](#publish-the-config-and-migrations) You can then publish the package's config file and database migrations by using the following command: ``` php artisan vendor:publish --provider="AshAllenDesign\ShortURL\Providers\ShortURLProvider" ``` ### Migrate the Database [](#migrate-the-database) This package contains two migrations that add two new tables to the database: `short_urls` and `short_url_visits`. To run these migrations, simply run the following command: ``` php artisan migrate ``` Usage ----- [](#usage) ### Building Shortened URLs [](#building-shortened-urls) #### Quick Start [](#quick-start) The quickest way to get started with creating a shortened URL is by using the snippet below. The `->make()` method returns a ShortURL model that you can grab the shortened URL from. ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->make(); $shortURL = $shortURLObject->default_short_url; ``` #### Custom Keys [](#custom-keys) By default, the shortened URL that is generated will contain a random key. The key will be of the length that you define in the config files (defaults to 5 characters). Example: if a URL is `https://webapp.com/short/abc123`, the key is `abc123`. You may wish to define a custom key yourself for that URL that is more meaningful than a randomly generated one. You can do this by using the `->urlKey()` method. Example: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->urlKey('custom-key') ->make(); $shortURL = $shortURLObject->default_short_url; // Short URL: https://webapp.com/short/custom-key ``` Note: All of the URL keys are unique, so you cannot use a key that already exists in the database for another shortened URL. #### Tracking Visitors [](#tracking-visitors) You may want to track some data about the visitors that have used the shortened URL. This can be useful for analytics. By default, tracking is enabled and all of the available tracking fields are also enabled. You can toggle the default options for the different parts of the tracking in the config file. Read further on in the [Customisation](#customisation)section to see how to customise the default tracking behaviours. Note: Even if the tracking options (such as `track_ip_address`) are enabled for a short URL, they won't be recorded unless the `track_visits` options is enabled. This can come in handy if you want to enable/disable tracking for a short URL without needing to individually set each option. ##### Enabling Tracking [](#enabling-tracking) If you want to override whether if tracking is enabled or not when creating a shortened URL, you can use the `->trackVisits()` method. This method accepts a boolean but defaults to `true` if a parameter is not passed. The example below shows how to enable tracking for the URL and override the config variable: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->trackVisits() ->make(); ``` The example below shows how to disable tracking for the URL and override the default config variable: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->trackVisits(false) ->make(); ``` ##### Tracking IP Address [](#tracking-ip-address) If you want to override whether if IP address tracking is enabled or not when creating a shortened URL, you can use the `->trackIPAddress()` method. This method accepts a boolean but defaults to `true` if a parameter is not passed. The example below shows how to enable IP address tracking for the URL and override the default config variable: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->trackVisits() ->trackIPAddress() ->make(); ``` ##### Tracking Browser & Browser Version [](#tracking-browser--browser-version) If you want to override whether if browser name and browser version tracking is enabled or not when creating a shortened URL, you can use the `->trackBrowser()` and `->trackBrowserVersion()` methods. This method accepts a boolean but defaults to `true` if a parameter is not passed. The example below shows how to enable browser name tracking for the URL and override the default config variable: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->trackVisits() ->trackBrowser() ->make(); ``` The example below shows how to enable browser version tracking for the URL and override the default config variable: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->trackVisits() ->trackBrowserVersion() ->make(); ``` ##### Tracking Operating System & Operating System Version [](#tracking-operating-system--operating-system-version) If you want to override whether if operating system name and operating system version tracking is enabled or not when creating a shortened URL, you can use the `->trackOperatingSystem()` and `->trackOperatingSystemVersion()`methods. These methods accept a boolean but default to `true` if a parameter is not passed. The example below shows how to enable operating system name tracking for the URL and override the default config variable: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->trackVisits() ->trackOperatingSystem() ->make(); ``` The example below shows how to enable operating system version tracking for the URL and override the default config variable: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->trackVisits() ->trackOperatingSystemVersion() ->make(); ``` ##### Tracking Device Type [](#tracking-device-type) If you want to override whether if device type tracking is enabled or not when creating a shortened URL, you can use the `->trackDeviceType()` method. This method accepts a boolean but defaults to `true` if a parameter is not passed. The example below shows how to enable device type tracking for the URL and override the default config variable: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->trackVisits() ->trackDeviceType() ->make(); ``` ##### Tracking Referer URL [](#tracking-referer-url) If you want to override whether if referer URL tracking is enabled or not when creating a shortened URL, you can use the `->trackRefererURL()` method. This method accepts a boolean but defaults to `true` if a parameter is not passed. The example below shows how to enable referer URL tracking for the URL and override the default config variable: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->trackVisits() ->trackRefererURL() ->make(); ``` #### Custom Short URL Fields [](#custom-short-url-fields) There may be times when you want to add your own custom fields to the ShortURL model and store them in the database. For example, you might want to associate the short URL with a tenant, organisation, user, etc. To do this you can use the `beforeCreate` method when building your short URL. This method accepts a closure that receives the `AshAllenDesign\ShortURL\Models\ShortURL` model instance before it's saved to your database. The example below shows how to add a `tenant_id` field to the `AshAllenDesign\ShortURL\Models\ShortURL` model: ``` use AshAllenDesign\ShortURL\Models\ShortURL; use AshAllenDesign\ShortURL\Facades\ShortURL as ShortUrlBuilder; $tenantId = 123; $shortURL = ShortUrlBuilder::destinationUrl($url) ->beforeCreate(function (ShortURL $model): void { $model->tenant_id = $tenantId; }) ->make(); ``` Please remember that to store custom fields in the database, you'll have to make sure those fields are added to the `short_urls` table. You can do this by creating a new migration that adds the fields to the table, or by updating the migrations that ship with this package. #### Single Use [](#single-use) By default, all of the shortened URLs can be visited for as long as you leave them available. However, you may want to only allow access to a shortened URL once. Then any visitors who visit the URL after it has already been viewed will get a HTTP 404. To create a single use shortened URL, you can use the `->singleUse()` method. The example below shows how to create a single use shortened URL: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->singleUse() ->make(); ``` #### Enforce HTTPS [](#enforce-https) When building a shortened URL, you might want to enforce that the visitor is redirected to the HTTPS version of the destination URL. This can be particularly useful if you're allowing your web app users to create their own shortened URLS. To enforce HTTPS, you can use the `->secure()` method when building the shortened URL. The example below shows how to create a secure shortened URL: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('http://destination.com') ->secure() ->make(); // Destination URL: https://destination.com ``` #### Forwarding Query Parameters [](#forwarding-query-parameters) When building a short URL, you might want to forward the query parameters sent in the request to destination URL. By default, this functionality is disabled, but can be enabled by setting the `forward_query_params` config option to `true`. Alternatively, you can also use the `->forwardQueryParams()` method when building your shortened URL, as shown in the example below: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('http://destination.com?param1=test') ->forwardQueryParams() ->make(); ``` Based on the example above, assuming that the original short URL's `destination_url` was `https://destination.com`, making a request to `https://webapp.com/short/xxx?param1=abc¶m2=def` would redirect to `https://destination.com?param1=test¶m2=def` #### Redirect Status Code [](#redirect-status-code) By default, all short URLs are redirected with a `301` HTTP status code. But, this can be overridden when building the shortened URL using the `->redirectStatusCode()` method. The example below shows how to create a shortened URL with a redirect HTTP status code of `302`: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('http://destination.com') ->redirectStatusCode(302) ->make(); ``` #### Activation and Deactivation Times [](#activation-and-deactivation-times) By default, all short URLs that you create are active until you delete them. However, you may set activation and deactivation times for your URLs when you're creating them. Doing this can be useful for marketing campaigns. For example, you may want to launch a new URL for a marketing campaign on a given date and then automatically deactivate that URL when the marketing campaign comes to an end. The example below shows how to create a shortened URL that will be active from this time tomorrow onwards: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->activateAt(\Carbon\Carbon::now()->addDay()) ->make(); ``` The example below shows how to create a shortened URL that will be active from this time tomorrow onwards and then is deactivated the day after: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->activateAt(\Carbon\Carbon::now()->addDay()) ->deactivateAt(\Carbon\Carbon::now()->addDays(2)) ->make(); ``` #### Using a Custom Seed [](#using-a-custom-seed) By default, the package will use the ID of the last inserted short URL as the seed for generating a short URL's key. In some cases, you may want to use a custom seed instead. To do this, you can pass an integer to the `generateKeyUsing` method like so: ``` use AshAllenDesign\ShortURL\Classes\Builder; $shortURLObject = app(Builder::class) ->destinationUrl('https://destination.com') ->generateKeyUsing(12345) ->make(); ``` #### Facade [](#facade) If you prefer to use facades in Laravel, you can choose to use the provided `ShortURL` facade instead of instantiating the `Builder` class manually. The example below shows an example of how you could use the facade to create a shortened URL: ```