{"id":15039647,"url":"https://github.com/ash-jc-allen/short-url","last_synced_at":"2025-05-13T17:07:03.662Z","repository":{"id":37735868,"uuid":"229502199","full_name":"ash-jc-allen/short-url","owner":"ash-jc-allen","description":"A Laravel package for creating shortened URLs for your web apps.","archived":false,"fork":false,"pushed_at":"2025-02-24T21:34:08.000Z","size":483,"stargazers_count":1321,"open_issues_count":4,"forks_count":166,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-24T01:52:15.627Z","etag":null,"topics":["hacktoberfest","laravel"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ash-jc-allen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ash-jc-allen"}},"created_at":"2019-12-22T01:04:21.000Z","updated_at":"2025-04-23T07:00:19.000Z","dependencies_parsed_at":"2023-11-11T01:25:53.957Z","dependency_job_id":"2209455a-aae6-4a99-a183-556d77d01259","html_url":"https://github.com/ash-jc-allen/short-url","commit_stats":{"total_commits":310,"total_committers":23,"mean_commits":"13.478260869565217","dds":"0.17419354838709677","last_synced_commit":"664ee84d9df81de7617aec30643e71f69ce79ea3"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ash-jc-allen%2Fshort-url","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ash-jc-allen%2Fshort-url/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ash-jc-allen%2Fshort-url/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ash-jc-allen%2Fshort-url/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ash-jc-allen","download_url":"https://codeload.github.com/ash-jc-allen/short-url/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253990466,"owners_count":21995774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","laravel"],"created_at":"2024-09-24T20:43:31.326Z","updated_at":"2025-05-13T17:07:03.613Z","avatar_url":"https://github.com/ash-jc-allen.png","language":"PHP","funding_links":["https://github.com/sponsors/ash-jc-allen"],"categories":["Popular Packages","PHP"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://ashallendesign.co.uk/images/custom/short-url-logo.png\" width=\"400\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://packagist.org/packages/ashallendesign/short-url\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/ashallendesign/short-url.svg?style=flat-square\" alt=\"Latest Version on Packagist\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/ashallendesign/short-url\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/ashallendesign/short-url.svg?style=flat-square\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/ashallendesign/short-url\"\u003e\u003cimg src=\"https://img.shields.io/packagist/php-v/ashallendesign/short-url?style=flat-square\" alt=\"PHP from Packagist\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/ash-jc-allen/short-url/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/ash-jc-allen/short-url?style=flat-square\" alt=\"GitHub license\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Installation](#installation)\n    - [Requirements](#requirements)\n    - [Install the Package](#install-the-package)\n    - [Publish the Config and Migrations](#publish-the-config-and-migrations)\n    - [Migrate the Database](#migrate-the-database)\n- [Usage](#usage)\n    - [Building Shortened URLs](#building-shortened-urls)\n        - [Quick Start](#quick-start)\n        - [Custom Keys](#custom-keys)\n        - [Tracking Visitors](#tracking-visitors)\n            - [Enabling Tracking](#enabling-tracking)\n            - [Tracking IP Address](#tracking-ip-address)\n            - [Tracking Browser \u0026 Browser Version](#tracking-browser--browser-version)\n            - [Tracking Operating System \u0026 Operating System Version](#tracking-operating-system--operating-system-version)\n            - [Tracking Device Type](#tracking-device-type)\n            - [Tracking Referer URL](#tracking-referer-url)\n        - [Custom Short URL Fields](#custom-short-url-fields)\n        - [Single Use](#single-use)\n        - [Enforce HTTPS](#enforce-https)\n        - [Forwarding Query Parameters](#forwarding-query-parameters)\n        - [Redirect Status Code](#redirect-status-code)\n        - [Activation and Deactivation Times](#activation-and-deactivation-times)\n        - [Using a Custom Seed](#using-a-custom-seed)\n        - [Facade](#facade)\n        - [Conditionals](#conditionals)\n    - [Using the Shortened URLs](#using-the-shortened-urls)\n        - [Default Route and Controller](#default-route-and-controller)\n        - [Custom Route](#custom-route)\n    - [Tracking](#tracking)\n    - [Customisation](#customisation)\n        - [Disabling the Default Route](#disabling-the-default-route)\n        - [Default URL Key Length](#default-url-key-length)\n        - [Tracking Visits](#tracking-visits)\n            - [Default Tracking](#default-tracking)\n            - [Tracking Fields](#tracking-fields)\n        - [Config Validation](#config-validation)\n        - [Custom Database Connection](#custom-database-connection)\n        - [Specifying the Key Generator](#specifying-the-key-generator)\n        - [Specifying the User Agent Parser](#specifying-the-user-agent-parser)\n        - [Specifying the Allowed URL Schemes](#specifying-the-allowed-url-schemes)\n    - [Helper Methods](#helper-methods)\n        - [Visits](#visits)\n        - [Find by URL Key](#find-by-url-key)\n        - [Find by Destination URL](#find-by-destination-url)\n        - [Tracking Enabled](#tracking-enabled)\n        - [Tracked Fields](#tracked-fields)\n    - [Events](#events)\n        - [Short URL Visited](#short-url-visited)\n    - [Model Factories](#model-factories)\n- [Testing](#testing)\n- [Security](#security)\n- [Contribution](#contribution)\n- [Credits](#credits)\n- [Changelog](#changelog)\n- [Upgrading](#upgrading)\n- [License](#license)\n    \n## Overview\n\nA Laravel package that can be used for adding shortened URLs to your existing web app.\n\n## Installation\n\n### Requirements\nThe package has been developed and tested to work with the following minimum requirements:\n\n- PHP 8.0\n- Laravel 8.0\n\nShort 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.\n\n### Install the Package\nYou can install the package via Composer:\n\n```bash\ncomposer require ashallendesign/short-url\n```\n\n### Publish the Config and Migrations\nYou can then publish the package's config file and database migrations by using the following command:\n```bash\nphp artisan vendor:publish --provider=\"AshAllenDesign\\ShortURL\\Providers\\ShortURLProvider\"\n```\n\n### Migrate the Database\nThis 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:\n```bash\nphp artisan migrate\n```\n\n## Usage\n\n### Building Shortened URLs\n\n#### Quick Start\n\nThe quickest way to get started with creating a shortened URL is by using the snippet below. The `-\u003emake()` method\n returns a ShortURL model that you can grab the shortened URL from.\n\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003emake();\n\n$shortURL = $shortURLObject-\u003edefault_short_url;\n```\n\n#### Custom Keys\nBy default, the shortened URL that is generated will contain a random key. The key will be of the length that you define\nin the config files (defaults to 5 characters). Example: if a URL is ``` https://webapp.com/short/abc123 ```, the key is\n``` abc123 ```.\n\nYou may wish to define a custom key yourself for that URL that is more meaningful than a randomly generated one. You can\ndo this by using the ``` -\u003eurlKey() ``` method. Example:\n\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003eurlKey('custom-key')\n    -\u003emake();\n\n$shortURL = $shortURLObject-\u003edefault_short_url;\n\n// Short URL: https://webapp.com/short/custom-key\n```\n\nNote: All of the URL keys are unique, so you cannot use a key that already exists in the database for another shortened\nURL.\n\n#### Tracking Visitors\nYou may want to track some data about the visitors that have used the shortened URL. This can be useful for analytics.\nBy default, tracking is enabled and all of the available tracking fields are also enabled. You can toggle the default\noptions for the different parts of the tracking in the config file. Read further on in the [Customisation](#customisation)\nsection to see how to customise the default tracking behaviours.\n\nNote: Even if the tracking options (such as ``` track_ip_address ```) are enabled for a short URL, they won't be recorded\nunless the ``` track_visits ``` options is enabled. This can come in handy if you want to enable/disable tracking for a\nshort URL without needing to individually set each option.\n\n##### Enabling Tracking\n\nIf you want to override whether if tracking is enabled or not when creating a shortened URL, you can use the ``` -\u003etrackVisits() ``` method.\nThis method accepts a boolean but defaults to ``` true ``` if a parameter is not passed.\n\nThe example below shows how to enable tracking for the URL and override the config variable:\n\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003etrackVisits()\n    -\u003emake();\n```\n\nThe example below shows how to disable tracking for the URL and override the default config variable:\n\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003etrackVisits(false)\n    -\u003emake();\n```\n\n##### Tracking IP Address\n\nIf you want to override whether if IP address tracking is enabled or not when creating a shortened URL, you can use the\n``` -\u003etrackIPAddress() ``` method. This method accepts a boolean but defaults to ``` true ``` if a parameter is not passed.\n\nThe example below shows how to enable IP address tracking for the URL and override the default config variable:\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003etrackVisits()\n    -\u003etrackIPAddress()\n    -\u003emake();\n```\n\n##### Tracking Browser \u0026 Browser Version\n\nIf you want to override whether if browser name and browser version tracking is enabled or not when creating a shortened\nURL, you can use the ``` -\u003etrackBrowser() ``` and ``` -\u003etrackBrowserVersion() ``` methods. This method accepts a boolean\nbut defaults to ``` true ``` if a parameter is not passed.\n\nThe example below shows how to enable browser name tracking for the URL and override the default config variable:\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003etrackVisits()\n    -\u003etrackBrowser()\n    -\u003emake();\n```\n\nThe example below shows how to enable browser version tracking for the URL and override the default config variable:\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003etrackVisits()\n    -\u003etrackBrowserVersion()\n    -\u003emake();\n```\n\n##### Tracking Operating System \u0026 Operating System Version\n\nIf you want to override whether if operating system name and operating system version tracking is enabled or not when\ncreating a shortened URL, you can use the ``` -\u003etrackOperatingSystem() ``` and ``` -\u003etrackOperatingSystemVersion() ```\nmethods. These methods accept a boolean but default to ``` true ``` if a parameter is not passed.\n\nThe example below shows how to enable operating system name tracking for the URL and override the default config variable:\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003etrackVisits()\n    -\u003etrackOperatingSystem()\n    -\u003emake();\n```\n\nThe example below shows how to enable operating system version tracking for the URL and override the default config variable:\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003etrackVisits()\n    -\u003etrackOperatingSystemVersion()\n    -\u003emake();\n```\n\n##### Tracking Device Type\n\nIf you want to override whether if device type tracking is enabled or not when creating a shortened URL, you can use the\n``` -\u003etrackDeviceType() ``` method. This method accepts a boolean but defaults to ``` true ``` if a parameter is not passed.\n\nThe example below shows how to enable device type tracking for the URL and override the default config variable:\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003etrackVisits()\n    -\u003etrackDeviceType()\n    -\u003emake();\n```\n\n##### Tracking Referer URL\n\nIf you want to override whether if referer URL tracking is enabled or not when creating a shortened URL, you can use the\n``` -\u003etrackRefererURL() ``` method. This method accepts a boolean but defaults to ``` true ``` if a parameter is not passed.\n\nThe example below shows how to enable referer URL tracking for the URL and override the default config variable:\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003etrackVisits()\n    -\u003etrackRefererURL()\n    -\u003emake();\n```\n\n#### Custom Short URL Fields\n\nThere 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.\n\nTo 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.\n\nThe example below shows how to add a `tenant_id` field to the `AshAllenDesign\\ShortURL\\Models\\ShortURL` model:\n\n```php\nuse AshAllenDesign\\ShortURL\\Models\\ShortURL;\nuse AshAllenDesign\\ShortURL\\Facades\\ShortURL as ShortUrlBuilder;\n\n$tenantId = 123;\n\n$shortURL = ShortUrlBuilder::destinationUrl($url)\n    -\u003ebeforeCreate(function (ShortURL $model): void {\n        $model-\u003etenant_id = $tenantId;\n    })\n    -\u003emake();\n```\n\nPlease 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.\n\n#### Single Use\nBy default, all of the shortened URLs can be visited for as long as you leave them available. However, you may want to\nonly allow access to a shortened URL once. Then any visitors who visit the URL after it has already been viewed will\nget a HTTP 404.\n\nTo create a single use shortened URL, you can use the ``` -\u003esingleUse() ``` method.\n\nThe example below shows how to create a single use shortened URL:\n ```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003esingleUse()\n    -\u003emake();\n ```\n\n#### Enforce HTTPS\nWhen building a shortened URL, you might want to enforce that the visitor is redirected to the HTTPS version\nof the destination URL. This can be particularly useful if you're allowing your web app users to create their own shortened\nURLS.\n\nTo enforce HTTPS, you can use the ``` -\u003esecure() ``` method when building the shortened URL.\n\nThe example below shows how to create a secure shortened URL:\n ```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('http://destination.com')\n    -\u003esecure()\n    -\u003emake();\n\n// Destination URL: https://destination.com\n ```\n\n#### Forwarding Query Parameters\nWhen 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`.\n\nAlternatively, you can also use the `-\u003eforwardQueryParams()` method when building your shortened URL, as shown in the example below:\n\n ```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('http://destination.com?param1=test')\n    -\u003eforwardQueryParams()\n    -\u003emake();\n ```\n\nBased 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\u0026param2=def` would redirect to `https://destination.com?param1=test\u0026param2=def`\n\n#### Redirect Status Code\n\nBy default, all short URLs are redirected with a ``` 301 ``` HTTP status code. But, this can be overridden when building\nthe shortened URL using the ``` -\u003eredirectStatusCode() ``` method.\n\nThe example below shows how to create a shortened URL with a redirect HTTP status code of ``` 302 ```:\n\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('http://destination.com')\n    -\u003eredirectStatusCode(302)\n    -\u003emake();\n```\n\n#### Activation and Deactivation Times\n\nBy default, all short URLs that you create are active until you delete them. However, you may set activation and deactivation\ntimes for your URLs when you're creating them.\n\nDoing this can be useful for marketing campaigns. For example, you may want to launch a new URL for a marketing campaign on\na given date and then automatically deactivate that URL when the marketing campaign comes to an end.\n\nThe example below shows how to create a shortened URL that will be active from this time tomorrow onwards:\n\n ```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003eactivateAt(\\Carbon\\Carbon::now()-\u003eaddDay())\n    -\u003emake();\n ```\n\nThe example below shows how to create a shortened URL that will be active from this time tomorrow onwards and then is\ndeactivated the day after:\n\n ```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003eactivateAt(\\Carbon\\Carbon::now()-\u003eaddDay())\n    -\u003edeactivateAt(\\Carbon\\Carbon::now()-\u003eaddDays(2))\n    -\u003emake();\n ```\n\n#### Using a Custom Seed\n\nBy 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:\n\n ```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n\n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003egenerateKeyUsing(12345)\n    -\u003emake();\n ```\n\n#### Facade\nIf you prefer to use facades in Laravel, you can choose to use the provided ``` ShortURL ``` facade instead of instantiating\nthe ``` Builder ``` class manually.\n\nThe example below shows an example of how you could use the facade to create a shortened URL:\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse ShortURL;\n\nclass Controller\n{\n    public function index()\n    {\n        $shortURLObject = ShortURL::destinationUrl('https://destination.com')-\u003emake();\n        ...\n    }\n}\n```\n\n#### Conditionals\n\nThe `Builder` class uses the `Illuminate\\Support\\Traits\\Conditionable` trait, so you can use the `when` and `unless` methods when building your short URLs.\n\nFor example, let's take this block of code that uses `if` when building the short URL:\n\n```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\n \n$builder = app(Builder::class)-\u003edestinationUrl('https://destination.com');\n\nif ($request-\u003edate('activation')) {\n    $builder = $builder-\u003eactivateAt($request-\u003edate('activation'));\n};\n\n$shortURLObject = $builder-\u003emake();\n```\n\nThis could be rewritten using `when` like so:\n\n ```php\nuse AshAllenDesign\\ShortURL\\Classes\\Builder;\nuse Carbon\\Carbon;\n \n$shortURLObject = app(Builder::class)\n    -\u003edestinationUrl('https://destination.com')\n    -\u003ewhen(\n        $request-\u003edate('activation'),\n        function (Builder $builder, Carbon $activateDate): Builder  {\n            return $builder-\u003eactivateAt($activateDate);\n        },\n    )\n    -\u003emake();\n ```\n\n### Using the Shortened URLs\n#### Default Route and Controller\nBy default, the shortened URLs that are created use the package's route and controller. The routes use the following structure:\n``` https://webapp.com/short/{urlKey} ```. This route uses the single-use controller that is found at \n``` \\AshAllenDesign\\ShortURL\\Controllers\\ShortURLController ```.\n\n#### Custom Route\nYou may wish to use a different routing structure for your shortened URLs other than the default URLs that are created.\nFor example, you might want to use ``` https://webapp.com/s/{urlKey} ``` or ``` https://webapp.com/{urlKey} ```. You can\ncustomise this to suit the needs of your project.\n\nTo use the custom routing all you need to do is add a web route to your project that points to the ShortURLController and\nuses the ``` {shortURLKey} ``` field.\n\nThe example below shows how you could add a custom route to your ``` web.php ``` file to use the shortened URLs:\n```php\nRoute::get('/custom/{shortURLKey}', '\\AshAllenDesign\\ShortURL\\Controllers\\ShortURLController');\n```\n\nNote: If you use your own custom routing, you might want to disable the default route that the app provides. Details are\nprovided for this in the [Customisation](#customisation) section below.\n\n### Tracking\nIf tracking is enabled for a shortened URL, each time the link is visited, a new ShortURLVisit row in the database will\nbe created. By default, the package is set to record the following fields of a visitor:\n\n- IP Address\n- Browser Name\n- Browser Version\n- Operating System Name\n- Operating System Version\n- Referer URL (the URL that the visitor originally came from)\n- Device Type (can be: ```desktop```/```mobile```/```tablet```/```robot```)\n\nEach of these fields can be toggled in the config files so that you only record the fields you need. Details on how to \ndo this are provided for this in the [Customisation](#customisation) section below.\n\n### Customisation\n\n#### Customising the Default Route\n\n#### Customising the Default URL\n\nThe package comes with a route that you can use for your short URLs. By default, this route uses your Laravel app's `app.url` config field to build the URL.\n\nHowever, you might want to override this and use a different URL for your short URLs. For instance, you might want to use a different domain name for your short URLs.\n\nTo override the base URL, you can set the `default_url` config field. For example, to set the base URL to `https://example.com`, you can set the `default_url` in your `config/short-url.php` file like so:\n\n```php\n'default_url' =\u003e 'https://example.com',\n```\n\nTo use the your application's `app.url` config field, you can set the `short_url.default_url` field to `null`.\n\n##### Customising the Prefix\n\nThe package comes with a route that you can use for your short URLs. By default, this route is `/short/{shortURLKey}`.\n\nYou might want to keep using this default route but change the `/short/` prefix to something else. To do this, you can change the `prefix` field in the config.\n\nFor example, to change the default short URL to `/s`, you could change the config value like so:\n\n```\n'prefix' =\u003e 's',\n```\n\n##### Removing the Prefix\n\nYou may also remove the prefix from the default route completely. For example, if you want your short URL to be accessible via `/{shortUrlKey}`, then you can update the `prefix` config value to `null` like so:\n\n```\n'prefix' =\u003e null,\n```\n\n##### Defining Middleware\n\nYou may wish to run the default short URL through some middleware in your application. To do this, you can define the middleware that the route should use via the `middleware` config value.\n\nFor example, if you have a `MyAwesomeMiddleware` class, you could update your `short-url` config like so:\n\n```\n'middleware' =\u003e [\n    MyAwesomeMiddleware::class,\n],\n```\n\nYou can also use this same approach to define middleware groups rather than individual middleware classes. For example, if you want your default short URL route to use the `web` middleware group, you could update your config like so:\n\n```\n'middleware' =\u003e [\n    'web',\n],\n```\n\nIt's important to note that this middleware will only be automatically applied to the default short URL route that ships with the package. If you are defining your own route, you'll need to apply this middleware to your route yourself.\n\n#### Disabling the Default Route\nIf you have added your own custom route to your project, you may want to block the default route that the package provides.\nYou can do this by setting the following value in the config:\n\n```\n'disable_default_route' =\u003e true,\n```\nIf the default route is disabled, any visitors who go to the ```/short/{shortURLKey}``` route will receive a HTTP 404.\n\nYou may want to manually prevent the route from being automatically registered and manually register it yourself in your own routes file. To do this you can add the following code to your routes file (e.g. `web.php`):\n\n```php\n\\AshAllenDesign\\ShortURL\\Facades\\ShortURL::routes();\n```\n\n#### Default URL Key Length \nWhen building a shortened URL, you have the option to define your own URL key or to randomly generate one. If one is\nrandomly generated, the minimum length of it is determined from the config.\n\nA minimum key length of 3 has been enforced for performance reasons. \n\nFor example, to create a shortened URL with a key length of 10 characters, you could set the following in the config:\n\n```\n'key_length' =\u003e 10,\n``` \n\nBy default, the shortened URLs that are created have a key length of 5.\n\nPlease be aware that the key length that you specify in the config is only a desirable length. It acts as a minimum length\nrather than a fixed length. For example, if the ``` key_length ``` is set to 3 in the config and there is a unique 3 character\nlong key that hasn't been used yet, the key created will be 3 characters long. However, if all of the possible 3 character long\nkeys are taken, a 4 character key will be created.\n\nThe [Hashids](https://github.com/vinkla/hashids) library is used to assist with creating the URL keys.\n\n#### Tracking Visits\nBy default, the package enables tracking of all the available fields on each URL built. However, this can be toggled in\nthe config file.\n\n##### Default Tracking\nTo disable tracking by default on all future short URLs that are generated, set the following in the config:\n```\n'tracking'   =\u003e [\n        'default_enabled' =\u003e true,\n        ...\n]\n```\nNote: Disabling tracking by default won't disable tracking for any shortened URLs that already exist. It will only apply\nto all shortened URLs that are created after the config update.\n\n##### Tracking Fields\nYou can toggle the default options for each of fields that can be tracked by changing them in the config. These options\ncan then be overridden for each short URL at the point of creation, as shown in the [Tracking Visitors](#tracking-visitors) section.\n\nFor example, the snippet below shows how we could record all of the fields apart from the IP address of the visitor:\n\n```\n'tracking'   =\u003e [\n        ...\n        'fields' =\u003e [\n            'ip_address' =\u003e false,\n            'operating_system' =\u003e true,\n            'operating_system_version' =\u003e true,\n            'browser' =\u003e true,\n            'browser_version' =\u003e true,\n            'referer_url' =\u003e true,\n            'device_type' =\u003e true,\n        ],\n    ],\n```\n\n#### Config Validation\nBy default, the values defined in the ``` short-url.php ``` config file are not validated. However, the library contains\na validator that can be used to ensure that your values are safe to use. To enable the config validation, you can set the\nfollowing option in the config:\n\n```\n'validate_config' =\u003e true,\n``` \n\n#### Custom Database Connection\n\nBy default, Short URL will use your application's default database connection. But there may be times that you'd like to use a different connection. For example, you might be building a multi-tenant application that uses a separate connection for each tenant, and you may want to store the short URLs in a central database.\n\nTo do this, you can set the connection name using the `connection` config value in the `config/short-url.php` file like so:\n\n```\n'connection' =\u003e 'custom_database_connection_name',\n```\n\n#### Specifying the Key Generator\n\nBy default, Short URL uses the `AshAllenDesign\\ShortURL\\Classes\\KeyGenerator` class to generate the keys for the short URL. However, you may want to use your own custom key generator class.\n\nTo do this, you can define the class to be used in the `short-url.php` config file like so:\n\n```php\n'url_key_generator' =\u003e \\AshAllenDesign\\ShortURL\\Classes\\KeyGenerator::class,\n```\n\nYou'll just need to ensure that your custom key generator class implements the `AshAllenDesign\\ShortURL\\Interfaces\\KeyGenerator` interface.\n\n#### Specifying the User Agent Parser\n\nBy default, Short URL uses `whichbrowser/parser` package to parse the user agent header of the visitor when tracking visits. However, you may want to use your own custom user agent parser.\n\nTo do this, you can define the class to be used in the `short-url.php` config file like so:\n\n```php\n'user_agent_driver' =\u003e \\AshAllenDesign\\ShortURL\\Classes\\UserAgent\\ParserPhpDriver::class,\n```\n\nYou'll just need to ensure that your custom user agent parser class implements the `AshAllenDesign\\ShortURL\\Interfaces\\UserAgentDriver` interface.\n\n#### Specifying the Allowed URL Schemes\n\nBy default, Short URL will allow you to create a shortened URL for any URLs beginning with `http://` or `https://`.\n\nHowever, you may want to change this list of allowed URL schemes. For example, this may be to restrict the creation to only `https://` URLs. Or, it may be to allow URLs to be created using other schemes such as `mailto://` or even custom schemes for your own applications.\n\nTo change the list of allowed URL schemes, you can define the list using the `allowed_url_schemes` field in your `short-url.php` config file like so:\n\n```php\n'allowed_url_schemes' =\u003e [\n    'http://',\n    'https://',\n    'mailto://',\n    'myapp://',\n],\n```\n\n### Helper Methods\n#### Visits\nThe ShortURL model includes a relationship (that you can use just like any other Laravel model relation) for getting the\nvisits for a shortened URL.\n\nTo get the visits using the relationship, use ``` -\u003evisits ``` or ``` -\u003evisits() ```. The example snippet belows shows how:\n\n```php\n$shortURL = \\AshAllenDesign\\ShortURL\\Models\\ShortURL::find(1);\n$visits = $shortURL-\u003evisits;\n``` \n#### Find by URL Key\nTo find the ShortURL model that corresponds to a given shortened URL key, you can use the ``` -\u003efindByKey() ``` method.\n\nFor example, to find the ShortURL model of a shortened URL that has the key ``` abc123 ```, you could use the following:\n```php\n$shortURL = \\AshAllenDesign\\ShortURL\\Models\\ShortURL::findByKey('abc123');\n``` \n\n#### Find by Destination URL\nTo find the ShortURL models that redirect to a given destination URL, you can use the ``` -\u003efindByDestinationURL() ``` method.\n\nFor example, to find all of the ShortURL models of shortened URLs that redirect to ``` https://destination.com ```, you could use\nthe following:\n\n```php\n$shortURLs = \\AshAllenDesign\\ShortURL\\Models\\ShortURL::findByDestinationURL('https://destination.com');\n```\n\n#### Tracking Enabled\nTo check if tracking is enabled for a short URL, you can use the ``` -\u003etrackingEnabled() ``` method. It will return ``` true ```\nif tracking is enabled, and ``` false ``` if not.\n\nThe following example shows how to check if a short URL has tracking enabled:\n\n```php\n$shortURL = \\AshAllenDesign\\ShortURL\\Models\\ShortURL::first();\n$shortURL-\u003etrackingEnabled();\n``` \n\n#### Tracked Fields\nTo check which fields are enabled for tracking for a short URL, you can use the ``` -\u003etrackingFields() ``` method. It\nwill return an array with the names of each field that is currently enabled for tracking.\n\nNote: Even if the tracking options (such as ``` track_ip_address ```) are enabled for a short URL and returned, they\nwon't be recorded unless the ``` track_visits ``` options is enabled. This can come in handy if you want to enable/disable\ntracking for a short URL without needing to individually set each option.\n\nThe following example shows how to get an array of all tracking-enabled fields for a short URL:\n\n```php\n$shortURL = \\AshAllenDesign\\ShortURL\\Models\\ShortURL::first();\n$shortURL-\u003etrackingFields();\n```\n\n### Model Factories\n\nThe package comes with model factories included for testing purposes which come in handy when generating polymorphic relationships. The `ShortURL` model factory also comes with extra states that you may use when necessary, such as `deactivated` and `inactive`:\n\n```php\nuse AshAllenDesign\\ShortURL\\Models\\ShortURL;\n\n$shortUrl = ShortURL::factory()-\u003ecreate();\n\n// URL is deactivated\n$deactivatedShortUrl = ShortURL::factory()-\u003edeactivated()-\u003ecreate();\n\n// URL is neither activated nor deactivated\n$inactiveShortURL = ShortURL::factory()-\u003einactive()-\u003ecreate();\n```\n\nIf you are using your own custom model factory, you can define the factories that the `ShortURL` and `ShortURLVisit` models should use by updating the `factories` config field:\n\n```php\n'factories' =\u003e [\n    \\AshAllenDesign\\ShortURL\\Models\\ShortURL::class =\u003e \\AshAllenDesign\\ShortURL\\Models\\Factories\\ShortURLFactory::class,\n    \\AshAllenDesign\\ShortURL\\Models\\ShortURLVisit::class =\u003e \\AshAllenDesign\\ShortURL\\Models\\Factories\\ShortURLVisitFactory::class\n],\n```\n\n### Events\n\n#### Short URL Visited\n \nEach time a short URL is visited, the following event is fired that can be listened on:\n\n```\nAshAllenDesign\\ShortURL\\Events\\ShortURLVisited\n```\n\nIf you are redirecting users with a `301` HTTP status code, it's possible that this event will NOT be fired\nif a visitor has already visited this short URL before. This is due to the fact that most browsers will cache the\nintended destination URL as a 'permanent redirect' and won't actually visit the short URL first.\n\nFor better results, use the `302` HTTP status code as most browsers will treat the short URL as a 'temporary redirect'.\nThis means that the short URL will be visited in the browser and the event will be dispatched as expected before redirecting\nto the destination URL.\n\n## Testing\n\nTo run the package's unit tests, run the following command:\n\n``` bash\nvendor/bin/phpunit\n```\n\n## Security\n\nIf you find any security related issues, please contact me directly at [mail@ashallendesign.co.uk](mailto:mail@ashallendesign.co.uk) to report it.\n\n## Contribution\n\nIf you wish to make any changes or improvements to the package, feel free to make a pull request.\n\nNote: A contribution guide will be added soon.\n\n## Credits\n\n- [Ash Allen](https://ashallendesign.co.uk)\n- [Jess Pickup](https://jesspickup.co.uk) (Logo)\n- [Nathan Giesbrecht](https://github.com/NathanGiesbrecht)\n- [Carlos A. Escobar](https://github.com/carlosjs23)\n- [Victor-Emil Rossil Andersen](https://github.com/Victor-emil)\n- [Julien Arcin](https://github.com/julienarcin)\n- [Ryan Chandler](https://github.com/ryangjchandler)\n- [All Contributors](https://github.com/ash-jc-allen/short-url/graphs/contributors)\n\n## Changelog\n\nCheck the [CHANGELOG](CHANGELOG.md) to get more information about the latest changes.\n\n## Upgrading\n\nCheck the [UPGRADE](UPGRADE.md) guide to get more information on how to update this library to newer versions.\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n## Support Me\n\nIf you've found this package useful, please consider buying a copy of [Battle Ready Laravel](https://battle-ready-laravel.com) to support me and my work.\n\nEvery sale makes a huge difference to me and allows me to spend more time working on open-source projects and tutorials.\n\nTo say a huge thanks, you can use the code **BATTLE20** to get a 20% discount on the book.\n\n[👉 Get Your Copy!](https://battle-ready-laravel.com)\n\n[![Battle Ready Laravel](https://ashallendesign.co.uk/images/custom/sponsors/battle-ready-laravel-horizontal-banner.png)](https://battle-ready-laravel.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fash-jc-allen%2Fshort-url","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fash-jc-allen%2Fshort-url","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fash-jc-allen%2Fshort-url/lists"}