{"id":14975024,"url":"https://github.com/yorcreative/laravel-urlshortener","last_synced_at":"2025-10-27T07:11:08.734Z","repository":{"id":56745183,"uuid":"524261144","full_name":"YorCreative/Laravel-UrlShortener","owner":"YorCreative","description":"A Laravel URL Shortener package that provides URL redirects with optionally protected URL password, Hidden UTM parameter tracing, URL expiration, open limits before expiration, ability to set feature activation dates, and click tracking out of the box for your Laravel applications.","archived":false,"fork":false,"pushed_at":"2025-01-09T18:27:07.000Z","size":232,"stargazers_count":115,"open_issues_count":4,"forks_count":15,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-16T15:09:27.155Z","etag":null,"topics":["hacktoberfest","hacktoberfest2022","laravel","laravel-package","laravel10","laravel9","lumen-framework","package","php","shorten-urls","shortener-service","shortener-url","shorturl","shorturl-package","shorturl-services","url-shortener","urls"],"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/YorCreative.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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}},"created_at":"2022-08-13T00:46:03.000Z","updated_at":"2025-04-21T19:38:38.000Z","dependencies_parsed_at":"2024-06-08T22:43:41.875Z","dependency_job_id":"7c46da91-4e36-410c-9e41-059725951c64","html_url":"https://github.com/YorCreative/Laravel-UrlShortener","commit_stats":{"total_commits":21,"total_committers":4,"mean_commits":5.25,"dds":0.1428571428571429,"last_synced_commit":"36d685a4d664e7faaaf45b1724d744c582424f96"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YorCreative%2FLaravel-UrlShortener","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YorCreative%2FLaravel-UrlShortener/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YorCreative%2FLaravel-UrlShortener/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YorCreative%2FLaravel-UrlShortener/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YorCreative","download_url":"https://codeload.github.com/YorCreative/Laravel-UrlShortener/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553958,"owners_count":22090417,"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","hacktoberfest2022","laravel","laravel-package","laravel10","laravel9","lumen-framework","package","php","shorten-urls","shortener-service","shortener-url","shorturl","shorturl-package","shorturl-services","url-shortener","urls"],"created_at":"2024-09-24T13:51:24.697Z","updated_at":"2025-10-27T07:11:08.643Z","avatar_url":"https://github.com/YorCreative.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cbr /\u003e\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/YorCreative\"\u003e\n    \u003cimg src=\"content/logo.png\" alt=\"Logo\" width=\"128\" height=\"128\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003ch3 align=\"center\"\u003eLaravel URL Shortener\u003c/h3\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://github.com/YorCreative/Laravel-UrlShortener/blob/main/LICENSE.md\"\u003e\u003cimg alt=\"GitHub license\" src=\"https://img.shields.io/github/license/YorCreative/Laravel-UrlShortener\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/YorCreative/Laravel-UrlShortener/stargazers\"\u003e\u003cimg alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/YorCreative/Laravel-UrlShortener\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/YorCreative/Laravel-UrlShortener/issues\"\u003e\u003cimg alt=\"GitHub issues\" src=\"https://img.shields.io/github/issues/YorCreative/Laravel-UrlShortener\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/YorCreative/Laravel-UrlShortener/network\"\u003e\u003cimg alt=\"GitHub forks\" src=\"https://img.shields.io/github/forks/YorCreative/Laravel-UrlShortener\"\u003e\u003c/a\u003e\n\u003cimg alt=\"Packagist Downloads\" src=\"https://img.shields.io/packagist/dt/YorCreative/Laravel-UrlShortener?color=green\"\u003e\n\u003ca href=\"https://github.com/YorCreative/Laravel-UrlShortener/actions/workflows/phpunit.yml\"\u003e\u003cimg alt=\"PHPUnit\" src=\"https://github.com/YorCreative/Laravel-UrlShortener/actions/workflows/phpunit.yml/badge.svg\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\nA Laravel URL Shortener package that provides URL redirects with optionally protected URL password, URL expiration, open\nlimits before expiration, ability to set feature activation dates, and click tracking out of the box for your Laravel\napplications.\n\n## Installation\n\ninstall the package via composer:\n\n```bash\ncomposer require yorcreative/laravel-urlshortener\n```\n\nPublish the packages assets.\n```bash\nphp artisan vendor:publish --provider=\"YorCreative\\UrlShortener\\UrlShortenerServiceProvider\"\n```\n\nRun migrations.\n```bash\nphp artisan migrate\n```\n\n## Upgrade Guides\n\n[Upgrading to v2.x from v1.x](https://github.com/YorCreative/Laravel-UrlShortener/wiki/Upgrading-to-2.x-from-1.x)\n\n## Usage\n\nBuilding Short Urls\n\n```php\n/**\n* Basic\n */\n$url = UrlService::shorten('something-extremely-long.com/even/longer?ref=with\u0026some=thingelselonger')\n        -\u003ebuild(); \n// http(s)://host/prefix/identifier;\n\n/**\n* Advanced\n */\n$url = UrlService::shorten('something-extremely-long.com/even/longer?ref=with\u0026some=thingelselonger')\n        -\u003ewithActivation(Carbon::now()-\u003eaddHour()-\u003etimestamp)\n        -\u003ewithExpiration(Carbon::now()-\u003eaddDay()-\u003etimestamp)\n        -\u003ewithOpenLimit(2)\n        -\u003ewithOwnership(Model::find(1))\n        -\u003ewithPassword('password')\n        -\u003ewithTracing([\n            'utm_id' =\u003e 't123',\n            'utm_campaign' =\u003e 'campaign_name',\n            'utm_source' =\u003e 'linkedin',\n            'utm_medium' =\u003e 'social',      \n        ])\n        -\u003ebuild();\n// http(s)://host/prefix/identifier;\n```\n\nFinding Existing Short Urls\n\n```php\n/**\n * Find a Short URL by its identifier \n */\n$shortUrl = UrlService::findByIdentifier('identifier');\n// returns instance of ShortUrl Model.\n\n\n/**\n * Find a Short URL by its hashed signature\n */\n$shortUrl = UrlService::findByHash(md5('long_url'));\n// returns instance of ShortUrl Model.\n\n\n/**\n * Find a Short URL by its plain text long url string \n */\n$shortUrl = UrlService::findByPlainText('long_url');\n// returns instance of ShortUrl Model. \n\n/**\n * Find shortUrls by UTM combinations.\n * \n * Note* This method only accepts the following array fields:\n *  - utm_id\n *  - utm_campaign\n *  - utm_source\n *  - utm_medium\n *  - utm_content\n *  - utm_term\n */\n$shortUrlCollection = UrlService::findByUtmCombination([\n    'utm_campaign' =\u003e 'alpha',\n    'utm_source' =\u003e 'bravo',\n    'utm_medium' =\u003e 'testing'\n])\n// returns an instance of Eloquent Collection of ShortUrl Models.\n```\n\nGetting Click Information\n\n```php\n$clicks = ClickService::get()-\u003etoArray();\n\ndd($clicks);\n[\n    'results' =\u003e [\n        [\n            'id' =\u003e ...,\n            'created_at' =\u003e ...,\n            'short_url' =\u003e [\n                'id' =\u003e ...,\n                'identifier' =\u003e ...,\n                'hashed' =\u003e ...,\n                'plain_text' =\u003e ...,\n                'limit' =\u003e ...,\n                'tracing' =\u003e [\n                    'id' =\u003e ...,\n                    'utm_id' =\u003e ...,\n                    'utm_source' =\u003e ...,\n                    'utm_medium' =\u003e ...,\n                    'utm_campaign' =\u003e ...,\n                    'utm_content' =\u003e ...,\n                    'utm_term' =\u003e ...,\n                ]\n                'created_at' =\u003e ...,\n                'updated_at' =\u003e ...\n            ],\n            'location' =\u003e [\n                'id' =\u003e ...,\n                'ip' =\u003e ...,\n                'countryName' =\u003e ...,\n                'countryCode' =\u003e ...,\n                'regionCode' =\u003e ...,\n                'regionName' =\u003e ...,\n                'cityName' =\u003e ...,\n                'zipCode' =\u003e ...,\n                'isoCode' =\u003e ...,\n                'postalCode' =\u003e ...,\n                'latitude' =\u003e ...,\n                'longitude' =\u003e ...,\n                'metroCode' =\u003e ...,\n                'areaCode' =\u003e ...,\n                'timezone' =\u003e ...,\n                'created_at' =\u003e ...,\n                'updated_at' =\u003e ...\n            ],\n            'outcome' =\u003e [\n                'id' =\u003e ...,\n                'name' =\u003e ...,\n                'alias' =\u003e ...,\n            ],\n        ]  \n    ],\n    'total' =\u003e 1\n];\n```\n\nGetting Click Information and Filtering on Ownership\n\n```php\n$clicks = ClickService::get([\n    'ownership' =\u003e  [\n        Model::find(1),\n        Model::find(2)\n    ]        \n]);\n```\n\n\nFilter on Outcome\n\n```php\n$clicks = ClickService::get([\n    'outcome' =\u003e [\n        1, // successful_routed\n        2, // successful_protected\n        3, // failure_password\n        4, // failure_expiration\n        5  // failure_limit\n    ]        \n]);\n```\nFilter on the Click's YorShortUrl Status\n\n```php\n$clicks = ClickService::get([\n    'status' =\u003e [\n        'active',\n        'expired',\n        'expiring' // within 30 minutes of expiring\n    ]        \n]);\n```\n\nFiltered on YorShortUrl Identifier(s)\n\n```php\n$clicks = ClickService::get([\n    'identifier' =\u003e [\n         'xyz',\n         'yxz'\n    ]\n]);\n```\n\nFiltered Clicks by UTM parameter(s). These Can be filtered together or individually.\n```php\n$clicks = ClickService::get([\n    'utm_id' =\u003e [\n         'xyz',\n         'yxz'\n    ],\n    'utm_source' =\u003e [\n         'linkedin',\n         'facebook'\n    ],\n    'utm_medium' =\u003e [\n         'social'\n    ],\n    'utm_campaign' =\u003e [\n         'sponsored',\n         'affiliate'\n    ],\n    'utm_content' =\u003e [\n         'xyz',\n         'yxz'\n    ],\n    'utm_term' =\u003e [\n         'marketing+software',\n         'short+url'\n    ],\n]);\n```\n\nIterate Through Results With Batches\n\n```php\n$clicks = ClickService::get([\n    'limit' =\u003e 500\n    'offset' =\u003e 1500\n]); \n  \n$clicks-\u003eget('results');\n$clicks-\u003eget('total');\n```\n\nPutting it all Together\n\n```php\n/**\n * Get the successfully routed clicks for all active short urls that are owned by Model IDs 1,2,3 and 4.\n * Set the offset of results by 1500 clicks and limit by the results by 500.\n */\n$clicks = ClickService::get([\n    'ownership' =\u003e Model::whereIn('id', [1,2,3,4])-\u003eget()-\u003etoArray(),\n    'outcome' =\u003e [\n        3 // successful_routed\n    ],\n    'status' =\u003e [\n        'active'\n    ],    \n    'utm_campaign' =\u003e [\n        'awareness'\n    ],      \n    'utm_source' =\u003e [\n        'github'\n    ],\n    'limit' =\u003e 500\n    'offset' =\u003e 1500\n]);\n```\n\n## UTM Support\n\nWhen creating a Short URL, the following UTM parameters are available to attach to the Short URL for advanced tracking of your Short Urls.\n\n- utm_id\n- utm_campaign\n- utm_source\n- utm_medium\n- utm_content\n- utm_term\n\nUTM information is hidden in the Short URL identifier and clicks are filterable by UTM parameters.\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Credits\n\n- [Yorda](https://github.com/yordadev)\n- [All Contributors](../../contributors)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyorcreative%2Flaravel-urlshortener","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyorcreative%2Flaravel-urlshortener","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyorcreative%2Flaravel-urlshortener/lists"}