Stars: 277
Forks: 13
Pull Requests: 37
Issues: 4
Watchers: 7
Last Updated: 2023-09-14 06:07:32
This package allows you to easily manage invite codes for your Laravel application.
License: MIT License
Languages: PHP
This package allows you to easily manage invite codes for your Laravel application.
If you think this package helped you in any way, you can sponsor me on GitHub!
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 of the require section:
{
"require": {
"mateusjunges/laravel-invite-codes": "^1.6",
}
}
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\Http\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,
];
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');
}
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:
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.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.
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.
Also, you can use the declarative syntax, and use the canBeUsedXTimes()
method, where X
is the amount of times your invite code will be usable.
For example:
->canBeUsed10Times()
: This invite code can be used 10 times.->canBeUsed50Times()
: This invite code can be used 50 times.You can use any integer number you want with this method.
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.
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.
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');
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);
}
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
.
Run composer test
to test this package.
Thank you for considering contributing for the Laravel Invite Codes package! The contribution guide can be found here.
Please see changelog for more information about the changes on this package.
The Laravel Invite Codes package is open-sourced software licenced under the MIT License. Please see the License File for more information.