A Laravel URL Shortener package that provides URL redirects with optionally protected URL password, URL expiration, open limits before expiration

Overview


Laravel URL Shortener

GitHub license GitHub stars GitHub issues GitHub forks Packagist Downloads PHPUnit

A Laravel URL Shortener package that provides URL redirects with optionally protected URL password, URL expiration, open limits before expiration, ability to set feature activation dates, and click tracking out of the box for your Laravel applications.

Installation

install the package via composer:

composer require yorcreative/laravel-urlshortener

Publish the packages assets.

php artisan vendor:publish --provider="YorCreative\UrlShortener\UrlShortenerServiceProvider"

Run migrations.

php artisan migrate

Upgrade Guides

Upgrading to v2.x from v1.x

Usage

Building Short Urls

/**
* Basic
 */
$url = UrlService::shorten('something-extremely-long.com/even/longer?ref=with&some=thingelselonger')
        ->build(); 
// http(s)://host/prefix/identifier;

/**
* Advanced
 */
$url = UrlService::shorten('something-extremely-long.com/even/longer?ref=with&some=thingelselonger')
        ->withActivation(Carbon::now()->addHour()->timestamp)
        ->withExpiration(Carbon::now()->addDay()->timestamp)
        ->withOpenLimit(2)
        ->withOwnership(Model::find(1))
        ->withPassword('password')
        ->withTracing([
            'utm_id' => 't123',
            'utm_campaign' => 'campaign_name',
            'utm_source' => 'linkedin',
            'utm_medium' => 'social',      
        ])
        ->build();
// http(s)://host/prefix/identifier;

Finding Existing Short Urls

/**
 * Find a Short URL by its identifier 
 */
$shortUrl = UrlService::findByIdentifier('identifier');
// returns instance of ShortUrl Model.


/**
 * Find a Short URL by its hashed signature
 */
$shortUrl = UrlService::findByHash(md5('long_url'));
// returns instance of ShortUrl Model.


/**
 * Find a Short URL by its plain text long url string 
 */
$shortUrl = UrlService::findByPlainText('long_url');
// returns instance of ShortUrl Model. 

/**
 * Find shortUrls by UTM combinations.
 * 
 * Note* This method only accepts the following array fields:
 *  - utm_id
 *  - utm_campaign
 *  - utm_source
 *  - utm_medium
 *  - utm_content
 *  - utm_term
 */
$shortUrlCollection = UrlService::findByUtmCombination([
    'utm_campaign' => 'alpha',
    'utm_source' => 'bravo',
    'utm_medium' => 'testing'
])
// returns an instance of Eloquent Collection of ShortUrl Models.

Getting Click Information

$clicks = ClickService::get()->toArray();

dd($clicks);
[
    'results' => [
        [
            'id' => ...,
            'created_at' => ...,
            'short_url' => [
                'id' => ...,
                'identifier' => ...,
                'hashed' => ...,
                'plain_text' => ...,
                'limit' => ...,
                'tracing' => [
                    'id' => ...,
                    'utm_id' => ...,
                    'utm_source' => ...,
                    'utm_medium' => ...,
                    'utm_campaign' => ...,
                    'utm_content' => ...,
                    'utm_term' => ...,
                ]
                'created_at' => ...,
                'updated_at' => ...
            ],
            'location' => [
                'id' => ...,
                'ip' => ...,
                'countryName' => ...,
                'countryCode' => ...,
                'regionCode' => ...,
                'regionName' => ...,
                'cityName' => ...,
                'zipCode' => ...,
                'isoCode' => ...,
                'postalCode' => ...,
                'latitude' => ...,
                'longitude' => ...,
                'metroCode' => ...,
                'areaCode' => ...,
                'timezone' => ...,
                'created_at' => ...,
                'updated_at' => ...
            ],
            'outcome' => [
                'id' => ...,
                'name' => ...,
                'alias' => ...,
            ],
        ]  
    ],
    'total' => 1
];

Getting Click Information and Filtering on Ownership

$clicks = ClickService::get([
    'ownership' =>  [
        Model::find(1),
        Model::find(2)
    ]        
]);

Filter on Outcome

$clicks = ClickService::get([
    'outcome' => [
        1, // successful_routed
        2, // successful_protected
        3, // failure_password
        4, // failure_expiration
        5  // failure_limit
    ]        
]);

Filter on the Click's YorShortUrl Status

$clicks = ClickService::get([
    'status' => [
        'active',
        'expired',
        'expiring' // within 30 minutes of expiring
    ]        
]);

Filtered on YorShortUrl Identifier(s)

$clicks = ClickService::get([
    'identifier' => [
         'xyz',
         'yxz'
    ]
]);

Filtered Clicks by UTM parameter(s). These Can be filtered together or individually.

$clicks = ClickService::get([
    'utm_id' => [
         'xyz',
         'yxz'
    ],
    'utm_source' => [
         'linkedin',
         'facebook'
    ],
    'utm_medium' => [
         'social'
    ],
    'utm_campaign' => [
         'sponsored',
         'affiliate'
    ],
    'utm_content' => [
         'xyz',
         'yxz'
    ],
    'utm_term' => [
         'marketing+software',
         'short+url'
    ],
]);

Iterate Through Results With Batches

$clicks = ClickService::get([
    'limit' => 500
    'offset' => 1500
]); 
  
$clicks->get('results');
$clicks->get('total');

Putting it all Together

/**
 * Get the successfully routed clicks for all active short urls that are owned by Model IDs 1,2,3 and 4.
 * Set the offset of results by 1500 clicks and limit by the results by 500.
 */
$clicks = ClickService::get([
    'ownership' => Model::whereIn('id', [1,2,3,4])->get()->toArray(),
    'outcome' => [
        3 // successful_routed
    ],
    'status' => [
        'active'
    ],    
    'utm_campaign' => [
        'awareness'
    ],      
    'utm_source' => [
        'github'
    ],
    'limit' => 500
    'offset' => 1500
]);

UTM Support

When creating a Short URL, the following UTM parameters are available to attach to the Short URL for advanced tracking of your Short Urls.

  • utm_id
  • utm_campaign
  • utm_source
  • utm_medium
  • utm_content
  • utm_term

UTM information is hidden in the Short URL identifier and clicks are filterable by UTM parameters.

Testing

composer test

Credits

You might also like...
Laravel User Activity Log - a package for Laravel 8.x that provides easy to use features to log the activities of the users of your Laravel app
Laravel User Activity Log - a package for Laravel 8.x that provides easy to use features to log the activities of the users of your Laravel app

Laravel User Activity Log - a package for Laravel 8.x that provides easy to use features to log the activities of the users of your Laravel app

Laravel Backup Panel provides a dashboard for spatie/laravel-backup package.
Laravel Backup Panel provides a dashboard for spatie/laravel-backup package.

Laravel Backup Panel Laravel Backup Panel provides a dashboard for spatie/laravel-backup package. It lets you: create a backup (full | only database |

This package provides an integration with FFmpeg for Laravel. Laravel's Filesystem handles the storage of the files.

Laravel FFMpeg This package provides an integration with FFmpeg for Laravel 6.0 and higher. Laravel's Filesystem handles the storage of the files. Lau

27Laracurl Laravel wrapper package for PHP cURL class that provides OOP interface to cURL. [10/27/2015] View Details

Laracurl Laravel cURL Wrapper for Andreas Lutro's OOP cURL Class Installation To install the package, simply add the following to your Laravel install

An opinionated support package for Laravel, that provides flexible and reusable helper methods and traits for commonly used functionality.

Support An opinionated support package for Laravel, that provides flexible and reusable helper methods and traits for commonly used functionality. Ins

Laravel Package for TMDB ( The Movie Database ) API. Provides easy access to the wtfzdotnet/php-tmdb-api library.

Laravel Package for TMDB API Wrapper A Laravel package that provides easy access to the php-tmdb/api TMDB (The Movie Database) API wrapper. This packa

This package provides a Logs page that allows you to view your Laravel log files in a simple UI
This package provides a Logs page that allows you to view your Laravel log files in a simple UI

A simplistics log viewer for your Filament apps. This package provides a Logs page that allows you to view your Laravel log files in a simple UI. Inst

Laravel Soulbscription - This package provides a straightforward interface to handle subscriptions and features consumption.

About This package provides a straightforward interface to handle subscriptions and features consumption. Installation You can

This package provides a Filament resource to view all Laravel sent emails.
This package provides a Filament resource to view all Laravel sent emails.

This package provides a Filament resource to view all Laravel outgoing emails. It also provides a Model for the database stored emails. Installation Y

Comments
  • UTM_ Tracking on Clicks

    UTM_ Tracking on Clicks

    • Added ShortUrlTracing Model/Migration/Factory.
    • Added withTracing() option to UrlService builder
    • Added ability to filter clicks based on UTM parameters.
    • Updated Test Coverage.
    • Updated Readme with UTM Support Information
    enhancement 
    opened by yordadev 1
  • Short URL Paywall

    Short URL Paywall

    Summary:

    Provide ability to build short URLs that are protected behind a paywall.

    Expectations:

    • Single use access paywall

      • User or Guest pays fee per access
      • Long URL is proxied and is masked for single use
    • Persistent use paywall

      • User or Guest pays once and has perm access.
      • Long URL is proxied and is masked for single use
    enhancement 
    opened by yordadev 0
Releases(v2.0.0)
  • v2.0.0(Sep 7, 2022)

  • v1.0.3(Aug 31, 2022)

  • v1.0.2(Aug 26, 2022)

  • v1.0.1(Aug 14, 2022)

  • v1.0.0(Aug 13, 2022)

    First Release of Laravel-UrlShortener Package.

    Functionality includes:

    • Creating Short Urls
      • With Passwords
      • With Activation Dates
      • With Expiration Dates
      • With Ownership Ability
      • With Open Limits
    • Ability to Fetch Clicks
      • Filtering on Outcome
      • Filtering on Ownership
      • Filtering on Short Url Status
      • Filtering on Short Url Identifier
      • Batching Click Fetching
    • Click Tracking
    • Customizable Configuration File
    • Solid Foundation of Test Coverage
    Source code(tar.gz)
    Source code(zip)
Owner
YorCreative
YorCreative focuses on package development for the Laravel community.
YorCreative
Laravel package to normalize your data before saving into the database.

This package helps you normalize your data in order to save them into the database. The Goal is to having separate classes that handle the data normalization, and thus can be tested independently.

Nicolas Widart 11 Apr 21, 2021
User authentication REST API with Laravel (Register, Email verification, Login, Logout, Logged user data, Change password, Reset password)

User Authentication API with Laravel This project is a user authentication REST API application that I developed by using Laravel and MySql. Setup Fir

Yusuf Ziya YILDIRIM 3 Aug 23, 2022
A simple way to add 301/302 redirects within CraftCMS.

Redirector plugin for Craft CMS 3.x A simple way to add 301/302 redirects within CraftCMS. This is the first CraftCMS plugin written by myself so plea

Jae Toole 1 Nov 25, 2021
Laravel breeze is a PHP Laravel library that provides Authentication features such as Login page , Register, Reset Password and creating all Sessions Required.

About Laravel breeze To give you a head start building your new Laravel application, we are happy to offer authentication and application starter kits

null 3 Jul 30, 2022
A package for Laravel One Time Password (OTP) generator and validation without Eloquent Model, since it done by Cache.

Laravel OTP Introduction A package for Laravel One Time Password (OTP) generator and validation without Eloquent Model, since it done by Cache. The ca

Lim Teck Wei 52 Sep 6, 2022
Laravel package for giving admin-created accounts to users via 'set-password' email.

Invytr When making a website where users are created instead of registering themselves, you are faced with the challenge of safely giving users the ac

GlaivePro 64 Jul 17, 2022
This package provides extended support for our spatie/enum package in Laravel.

Laravel support for spatie/enum This package provides extended support for our spatie/enum package in Laravel. Installation You can install the packag

Spatie 256 Sep 19, 2022
Laravel Common Password Validator

laravel-common-password-validator Laravel Common Password Validator An optimized and secure validator to check if a given password is too common. By d

WedgeHR 1 Nov 6, 2021
Get the thumbnail of youtube and vimeo videos from the url. The returned information is ID and URL of the thumbnail

Video Thumbnail URL Get the thumbnail of youtube and vimeo videos from the url. The returned information is ID and URL of the thumbnail Installation I

Fernando Valler 2 Jan 22, 2022
The Ultimate Password Locker

THIS REPO DOES NOT CONTAIN ALL THE CODE FOR SAFETY REASONS Padlock Your Personal Information is Safe and sound. With the power of PHP and MySQL, I was

null 1 Dec 13, 2021