README.md

Laravel Invite Codes

This package allows you to easily manage invite codes for your Laravel application.

Sponsor my work!

If you think this package helped you in any way, you can sponsor me on GitHub!

Documentation

• Installation
• Usage
  • Creating invite codes
    • Set the expiration date of your invite code
    • Restrict usage to some specific user
    • Set the maximum allowed usages for an invite code
  • Create multiple invite codes
  • Redeeming invite codes
  • Redeeming invite codes without dispatching events
• Customizing how invite codes are generated
• Extending the Invite model
• Handling invite codes exceptions
• Using artisan commands
• Tests
• Contributing
• Changelog
• License

Installation

To get started with Laravel Invite Codes, use Composer to add the package to your project's dependencies:

composer require mateusjunges/laravel-invite-codes

Or add this line in your composer.json, inside the require section:

{
    "require": {
        "mateusjunges/laravel-invite-codes": "^2.0",
    }
}

then run composer install.

All migrations required for this package are already included. If you need to customize the tables, you can publish them with:

php artisan vendor:publish --provider="Junges\InviteCodes\InviteCodesServiceProvider" --tag="invite-codes-migrations"

and set the config for custom_migrations to true, which is false by default.

'custom_migrations' => true,

After the migrations have been published you can create the tables on your database by running the migrations:

php artisan migrate

If you change the table names on migrations, please publish the config file and update the tables array. You can publish the config file with:

php artisan vendor:publish --provider="Junges\InviteCodes\InviteCodesServiceProvider" --tag="invite-codes-config"

When published, the config/invite-codes.php config file contains:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    |  Models
    |--------------------------------------------------------------------------
    |
    | When using this package, we need to know which Eloquent Model should be used
    | to retrieve your invites. Of course, it is just the basics models
    | needed, but you can use whatever you like.
    |
    */
    'models' => [
        'invite_model' => \Junges\InviteCodes\Models\Invite::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Tables
    |--------------------------------------------------------------------------
    | Specify the basics authentication tables that you are using.
    | Once you required this package, the following tables are
    | created by default when you run the command
    |
    | php artisan migrate
    |
    | If you want to change this tables, please keep the basic structure unchanged.
    |
    */
    'tables' => [
        'invites_table' => 'invites',
    ],

    /*
    |--------------------------------------------------------------------------
    | User
    |--------------------------------------------------------------------------
    | To use the ProtectedByInviteCode middleware provided by this package, you need to
    | specify the email column you use in the model you use for authentication.
    | If not specified, only invite code with no use restrictions can be used in this middleware.
    |
    */
    'user' => [
        'email_column' => 'email',
    ],

    /*
    |--------------------------------------------------------------------------
    | Custom migrations
    |--------------------------------------------------------------------------
    | If you want to publish this package migrations and edit with new custom columns, change it to true.
    */
    'custom_migrations' => false,
];

Usage

This package provides a middleware called ProtectedByInviteCodeMiddleware. If you want to use it to protect your routes, you need to register it in your $routeMiddleware array, into app/Http/Kernel.php file:

$routeMiddleware = [
    'protected_by_invite_codes' => ProtectedByInviteCodeMiddleware::class,
];

Now you can protect your routes using middleware rules:

Route::get('some-route', function() {
    //
})->middleware('protected_by_invite_codes');

You can also add it to the __construct(), in your controllers:

public function __construct()
{
    $this->middleware('protected_by_invite_codes');
}

Note This middleware expects to find an invitation code within the invite_code key of your request.

Creating invite codes

To create a new invite code, you must use the InviteCodes facade. Here is a simple example:

$invite_code = \Junges\InviteCodes\Facades\InviteCodes::create()
    ->expiresAt('2020-02-01')
    ->maxUsages(10)
    ->restrictUsageTo('[email protected]')
    ->save();

The code above will create a new invite code, which can be used 10 times only by a logged in user who has the specified email [email protected].

The methods you can use with the InviteCodes facade are listed below:

Set the expiration date of your invite code

To set the expiration date of your invite code you can use one of the following methods:

• expiresAt(): This method accept a date string in yyyy-mm-dd format or a Carbon instance, and set the expiration date to the specified date.
• expiresIn(): This method accept an integer, and set the expiration date to now plus the specified amount of days.

Restrict usage to some specific user:

To restrict the usage of an invite code you can use the restrictUsageTo() method, and pass in the email of the user who will be able to use this invite code.

Set the maximum allowed usages for an invite code:

If you want that your invite code be used a limited amount of times, you can set the max usages limit with the maxUsages() method, and pass an integer with the amount of allowed usages.

Create multiple invite codes

If you want to create more than one invite code with the same configs, you can use the make() method. This method generates the specified amount of invite codes. For example:

\Junges\InviteCodes\Facades\InviteCodes::create()
    ->maxUsages(10)
    ->expiresIn(30)
    ->make(10);

The code above will create 10 new invite codes which can be used 10 times each, and will expire in 30 days from now.

Redeeming invite codes

To redeem an invite code, you can use the redeem method:

\Junges\InviteCodes\Facades\InviteCodes::redeem('YOUR-INVITE-CODE');

When any invite is redeemed, the InviteRedeemedEvent will be dispatched.

Redeeming invite codes without dispatching events

If you want to redeem an invite codes without dispatch the InviteRedeemedEvent, you can use the withoutEvents() method:

\Junges\InviteCodes\Facades\InviteCodes::withoutEvents()->redeem('YOUR-INVITE-CODE');

Customizing how invite codes are generated

By default, this package generates a random 16 characters string that. Sometimes, you may want to customize how your invitation code is generated, for adding a prefix to the invitation code or anything you need.

If you need to customize how your invite codes are generated, you can add a call to the InviteCodes facade createInviteCodesusing method, in your service provider:

\Junges\InviteCodes\Facades\InviteCodes::createInviteCodeUsing(static function () {
    return 'THIS-IS-MY-INVITE-'.\Illuminate\Support\Str::random(); 
});

From now on, all of your invites will have the THIS-IS-MY-INVITE- prefix.

Also, the package itself will handle duplicate invites, so you don't need to take care of that yourself.

Extending the Invite model

The \Junges\InviteCodes\Models\Invite is fully extendable and replaceable. You can extend or create a new model to be used instead of the default one, and the only thing you need to do is implement the \Junges\InviteCodes\Contracts\InviteContract interface, which contains some required methods for this package to work.

After implementing the contract, you need to change the models.invite_model configuration value in config/invite-codes.php.

Handling invite codes exceptions

If you want to override the default 403 response, you can catch the exceptions using the laravel exception handler:

public function render($request, Exception $exception)
{
    if ($exception instanceof \Junges\InviteCodes\Exceptions\InviteWithRestrictedUsageException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\ExpiredInviteCodeException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\DuplicateInviteCodeException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\InvalidInviteCodeException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\UserLoggedOutException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\InviteMustBeAbleToBeRedeemedException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\SoldOutException) {
        //
    }
    if ($exception instanceof \Junges\InviteCodes\Exceptions\RouteProtectedByInviteCodeException) {
        //
    }
    
    return parent::render($request, $exception);
}

Using artisan commands

This package also provides a command to delete all expired invites from your database. You can use it like this:

\Illuminate\Support\Facades\Artisan::call('invite-codes:clear');

After all expired invites has been deleted, it will dispatch the DeletedExpiredInvitesEvent.

Tests

Run composer test to test this package.

Contributing

Thank you for considering contributing for the Laravel Invite Codes package! The contribution guide can be found here.

Changelog

Please see changelog for more information about the changes on this package.

License

The Laravel Invite Codes package is open-sourced software licenced under the MIT License. Please see the License File for more information.