{"id":13828055,"url":"https://github.com/mateusjunges/laravel-invite-codes","last_synced_at":"2025-05-15T05:08:01.241Z","repository":{"id":44070845,"uuid":"236969945","full_name":"mateusjunges/laravel-invite-codes","owner":"mateusjunges","description":"This package allows you to easily manage invite codes for your Laravel application.","archived":false,"fork":false,"pushed_at":"2025-05-03T02:31:24.000Z","size":320,"stargazers_count":286,"open_issues_count":0,"forks_count":14,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-03T02:58:32.165Z","etag":null,"topics":["hacktoberfest","invite-code","invite-users","invites","laravel","php","php74"],"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/mateusjunges.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"mateusjunges"}},"created_at":"2020-01-29T11:46:51.000Z","updated_at":"2025-05-03T02:30:13.000Z","dependencies_parsed_at":"2024-01-18T05:11:34.999Z","dependency_job_id":"d1ca0395-9ceb-413f-99b4-966b658d8265","html_url":"https://github.com/mateusjunges/laravel-invite-codes","commit_stats":{"total_commits":116,"total_committers":11,"mean_commits":"10.545454545454545","dds":0.6551724137931034,"last_synced_commit":"77b406d6184b675939d4d1be3bea95716dbf0e6d"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateusjunges%2Flaravel-invite-codes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateusjunges%2Flaravel-invite-codes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateusjunges%2Flaravel-invite-codes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateusjunges%2Flaravel-invite-codes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mateusjunges","download_url":"https://codeload.github.com/mateusjunges/laravel-invite-codes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"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","invite-code","invite-users","invites","laravel","php","php74"],"created_at":"2024-08-04T09:02:30.319Z","updated_at":"2025-05-15T05:07:56.234Z","avatar_url":"https://github.com/mateusjunges.png","language":"PHP","funding_links":["https://github.com/sponsors/mateusjunges"],"categories":["PHP"],"sub_categories":[],"readme":"# Laravel Invite Codes\n![Readme banner](art/banner.png)\nThis package allows you to easily manage invite codes for your Laravel application.\n\n\u003ca href=\"https://packagist.org/packages/mateusjunges/laravel-invite-codes\" target=\"_blank\"\u003e\u003cimg src=\"https://poser.pugx.org/mateusjunges/laravel-invite-codes/d/total.svg\" alt=\"Total Downloads\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/mateusjunges/laravel-invite-codes\" target=\"_blank\"\u003e\u003cimg src=\"https://poser.pugx.org/mateusjunges/laravel-invite-codes/v/stable.svg\" alt=\"Latest Stable Version\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/mateusjunges/laravel-invite-codes\" target=\"_blank\"\u003e\u003cimg src=\"https://poser.pugx.org/mateusjunges/laravel-invite-codes/license.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/mateusjunges/laravel-invite-codes/actions?query=workflow%3A%22Continuous+Integration%22\"\u003e\u003cimg src=\"https://github.com/mateusjunges/laravel-invite-codes/workflows/Continuous%20Integration/badge.svg\" alt=\"Continuous integration\"\u003e\u003c/a\u003e\n\n# Sponsor my work!\nIf you think this package helped you in any way, you can sponsor me on GitHub!\n\n[![Sponsor Me](art/sponsor.png)](https://github.com/sponsors/mateusjunges)\n\n# Documentation\n- [Installation](#installation)\n- [Usage](#usage)\n    - [Creating invite codes](#creating-invite-codes)\n        - [Set the expiration date of your invite code](#set-the-expiration-date-of-your-invite-code)\n        - [Restrict usage to some specific user](#restrict-usage-to-some-specific-user)\n        - [Set the maximum allowed usages for an invite code](#set-the-maximum-allowed-usages-for-an-invite-code)\n    - [Create multiple invite codes](#create-multiple-invite-codes)\n    - [Redeeming invite codes](#redeeming-invite-codes)\n    - [Redeeming invite codes without dispatching events](#redeeming-invite-codes-without-dispatching-events)\n- [Customizing how invite codes are generated](#customizing-how-invite-codes-are-generated)\n- [Extending the `Invite` model](#extending-the-invite-model)\n- [Handling invite codes exceptions](#handling-invite-codes-exceptions)\n- [Using artisan commands](#using-artisan-commands)\n- [Tests](#tests)\n- [Contributing](#contributing)\n- [Changelog](#changelog)\n- [License](#license)\n\n## Installation\n\nTo get started with Laravel Invite Codes, use Composer to add the package to your project's dependencies:\n\n```bash\ncomposer require mateusjunges/laravel-invite-codes\n```\n\nOr add this line in your composer.json, inside the `require` section:\n```bash\n{\n    \"require\": {\n        \"mateusjunges/laravel-invite-codes\": \"^2.0\",\n    }\n}\n```\nthen run `composer install`.\n\n\nAll migrations required for this package are already included. If you need to customize the tables, you can [publish them][migrations] with:\n\n```bash\nphp artisan vendor:publish --provider=\"Junges\\InviteCodes\\InviteCodesServiceProvider\" --tag=\"invite-codes-migrations\"\n```\n\nand set the config for `custom_migrations` to `true`, which is `false` by default.\n\n```php\n'custom_migrations' =\u003e true,\n```\n\nAfter the migrations have been published you can create the tables on your database by running the migrations:\n\n```bash\nphp artisan migrate\n```\n\nIf you change the table names on migrations, please publish the config file and update the tables array. You can publish the config file with:\n\n```bash\nphp artisan vendor:publish --provider=\"Junges\\InviteCodes\\InviteCodesServiceProvider\" --tag=\"invite-codes-config\"\n```\n\nWhen published, the `config/invite-codes.php` config file contains:\n\n```php\n\u003c?php\n\nreturn [\n    /*\n    |--------------------------------------------------------------------------\n    |  Models\n    |--------------------------------------------------------------------------\n    |\n    | When using this package, we need to know which Eloquent Model should be used\n    | to retrieve your invites. Of course, it is just the basics models\n    | needed, but you can use whatever you like.\n    |\n    */\n    'models' =\u003e [\n        'invite_model' =\u003e \\Junges\\InviteCodes\\Models\\Invite::class,\n    ],\n\n    /*\n    |--------------------------------------------------------------------------\n    | Tables\n    |--------------------------------------------------------------------------\n    | Specify the basics authentication tables that you are using.\n    | Once you required this package, the following tables are\n    | created by default when you run the command\n    |\n    | php artisan migrate\n    |\n    | If you want to change this tables, please keep the basic structure unchanged.\n    |\n    */\n    'tables' =\u003e [\n        'invites_table' =\u003e 'invites',\n    ],\n\n    /*\n    |--------------------------------------------------------------------------\n    | User\n    |--------------------------------------------------------------------------\n    | To use the ProtectedByInviteCode middleware provided by this package, you need to\n    | specify the email column you use in the model you use for authentication.\n    | If not specified, only invite code with no use restrictions can be used in this middleware.\n    |\n    */\n    'user' =\u003e [\n        'email_column' =\u003e 'email',\n    ],\n\n    /*\n    |--------------------------------------------------------------------------\n    | Custom migrations\n    |--------------------------------------------------------------------------\n    | If you want to publish this package migrations and edit with new custom columns, change it to true.\n    */\n    'custom_migrations' =\u003e false,\n];\n```\n\n# Usage\n\nThis package provides a middleware called `ProtectedByInviteCodeMiddleware`. If you want to use it to protect your \nroutes, you need to register it in your `$routeMiddleware` array, into `app/Http/Kernel.php` file:\n\n\n```php\n$routeMiddleware = [\n    'protected_by_invite_codes' =\u003e ProtectedByInviteCodeMiddleware::class,\n];\n```\n\nNow you can protect your routes using middleware rules:\n\n```php\nRoute::get('some-route', function() {\n    //\n})-\u003emiddleware('protected_by_invite_codes');\n```\n\nYou can also add it to the `__construct()`, in your controllers:\n\n```php\npublic function __construct()\n{\n    $this-\u003emiddleware('protected_by_invite_codes');\n}\n```\n\u003e **Note**\nThis middleware expects to find an invitation code within the `invite_code` key of your request. \n\n## Creating invite codes\n\nTo create a new invite code, you must use the `InviteCodes` facade. Here is a simple example:\n\n```php\n$invite_code = \\Junges\\InviteCodes\\Facades\\InviteCodes::create()\n    -\u003eexpiresAt('2020-02-01')\n    -\u003emaxUsages(10)\n    -\u003erestrictUsageTo('contato@mateusjunges.com')\n    -\u003esave();\n```\n\nThe 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 `contato@mateusjunges.com`.\n\nThe methods you can use with the `InviteCodes` facade are listed below:\n\n### Set the expiration date of your invite code\n\nTo set the expiration date of your invite code you can use one of the following methods:\n\n- `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.\n- `expiresIn()`: This method accept an integer, and set the expiration date to now plus the specified amount of days.\n\n### Restrict usage to some specific user:\n\nTo 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.\n\n### Set the maximum allowed usages for an invite code:\n\nIf 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\nof allowed usages.\n\n## Create multiple invite codes\n\nIf you want to create more than one invite code with the same configs, you can use the `make()` method.\nThis method generates the specified amount of invite codes. For example:\n\n```php\n\\Junges\\InviteCodes\\Facades\\InviteCodes::create()\n    -\u003emaxUsages(10)\n    -\u003eexpiresIn(30)\n    -\u003emake(10);\n```\n\nThe code above will create 10 new invite codes which can be used 10 times each, and will expire in 30 days from now.\n\n## Redeeming invite codes\nTo redeem an invite code, you can use the `redeem` method:\n\n```php\n\\Junges\\InviteCodes\\Facades\\InviteCodes::redeem('YOUR-INVITE-CODE');\n```\n\nWhen any invite is redeemed, the `InviteRedeemedEvent` will be dispatched.\n\n## Redeeming invite codes without dispatching events\n\nIf you want to redeem an invite codes without dispatch the `InviteRedeemedEvent`, \nyou can use the `withoutEvents()` method:\n\n```php\n\\Junges\\InviteCodes\\Facades\\InviteCodes::withoutEvents()-\u003eredeem('YOUR-INVITE-CODE');\n```\n\n# Customizing how invite codes are generated\nBy default, this package generates a random 16 characters string that. Sometimes, you may want to customize how your invitation code is generated,\nfor adding a prefix to the invitation code or anything you need.\n\nIf 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:\n\n```php\n\\Junges\\InviteCodes\\Facades\\InviteCodes::createInviteCodeUsing(static function () {\n    return 'THIS-IS-MY-INVITE-'.\\Illuminate\\Support\\Str::random(); \n});\n```\n\nFrom now on, all of your invites will have the `THIS-IS-MY-INVITE-` prefix.\n\nAlso, the package itself will handle duplicate invites, so you don't need to take care of that yourself.\n\n# Extending the `Invite` model\nThe `\\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,\nand 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.\n\nAfter implementing the contract, you need to change the `models.invite_model` configuration value in `config/invite-codes.php`.\n\n# Handling invite codes exceptions\n\nIf you want to override the default `403` response, you can catch the exceptions using the laravel exception handler:\n\n```php\npublic function render($request, Exception $exception)\n{\n    if ($exception instanceof \\Junges\\InviteCodes\\Exceptions\\InviteWithRestrictedUsageException) {\n        //\n    }\n    if ($exception instanceof \\Junges\\InviteCodes\\Exceptions\\ExpiredInviteCodeException) {\n        //\n    }\n    if ($exception instanceof \\Junges\\InviteCodes\\Exceptions\\DuplicateInviteCodeException) {\n        //\n    }\n    if ($exception instanceof \\Junges\\InviteCodes\\Exceptions\\InvalidInviteCodeException) {\n        //\n    }\n    if ($exception instanceof \\Junges\\InviteCodes\\Exceptions\\UserLoggedOutException) {\n        //\n    }\n    if ($exception instanceof \\Junges\\InviteCodes\\Exceptions\\InviteMustBeAbleToBeRedeemedException) {\n        //\n    }\n    if ($exception instanceof \\Junges\\InviteCodes\\Exceptions\\SoldOutException) {\n        //\n    }\n    if ($exception instanceof \\Junges\\InviteCodes\\Exceptions\\RouteProtectedByInviteCodeException) {\n        //\n    }\n    \n    return parent::render($request, $exception);\n}\n```\n\n# Using artisan commands\n\nThis package also provides a command to delete all expired invites from your database. You can use it like this:\n\n```php\n\\Illuminate\\Support\\Facades\\Artisan::call('invite-codes:clear');\n```\n\nAfter all expired invites has been deleted, it will dispatch the `DeletedExpiredInvitesEvent`.\n\n# Tests\n\nRun `composer test` to test this package.\n\n# Contributing\n\nThank you for considering contributing for the Laravel Invite Codes package! The contribution guide can be found [here](https://github.com/mateusjunges/laravel-invite-codes/blob/master/CONTRIBUTING.md).\n\n# Changelog\n\nPlease see [changelog](https://github.com/mateusjunges/laravel-invite-codes/blob/master/CHANGELOG.md) for more information about the changes on this package.\n\n# License\n\nThe Laravel Invite Codes package is open-sourced software licenced under the [MIT License](https://opensource.org/licenses/MIT). \nPlease see the [License File](https://github.com/mateusjunges/laravel-invite-codes/blob/master/LICENSE) for more information.\n\n[migrations]: https://github.com/mateusjunges/laravel-invite-codes/tree/master/database/migrations\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateusjunges%2Flaravel-invite-codes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmateusjunges%2Flaravel-invite-codes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateusjunges%2Flaravel-invite-codes/lists"}