{"id":13828318,"url":"https://github.com/beyondcode/laravel-vouchers","last_synced_at":"2025-05-14T05:12:30.599Z","repository":{"id":51292153,"uuid":"139901872","full_name":"beyondcode/laravel-vouchers","owner":"beyondcode","description":"Allow users to redeem vouchers that are bound to models.","archived":false,"fork":false,"pushed_at":"2025-03-07T09:54:58.000Z","size":70,"stargazers_count":706,"open_issues_count":1,"forks_count":100,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-11T11:13:44.557Z","etag":null,"topics":["hacktoberfest","laravel"],"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/beyondcode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2018-07-05T21:21:24.000Z","updated_at":"2025-05-07T17:26:14.000Z","dependencies_parsed_at":"2024-01-18T05:22:36.860Z","dependency_job_id":"4f429c99-8090-42ee-8047-c8f077bd0c57","html_url":"https://github.com/beyondcode/laravel-vouchers","commit_stats":{"total_commits":37,"total_committers":13,"mean_commits":"2.8461538461538463","dds":0.5135135135135135,"last_synced_commit":"8eb144cf8c922f55f72a6ae44aeb6aa0aa13db66"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondcode%2Flaravel-vouchers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondcode%2Flaravel-vouchers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondcode%2Flaravel-vouchers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondcode%2Flaravel-vouchers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beyondcode","download_url":"https://codeload.github.com/beyondcode/laravel-vouchers/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253554120,"owners_count":21926615,"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","laravel"],"created_at":"2024-08-04T09:02:41.129Z","updated_at":"2025-05-14T05:12:25.587Z","avatar_url":"https://github.com/beyondcode.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# Laravel Vouchers 🎟\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/beyondcode/laravel-vouchers.svg?style=flat-square)](https://packagist.org/packages/beyondcode/laravel-vouchers)\n[![Total Downloads](https://img.shields.io/packagist/dt/beyondcode/laravel-vouchers.svg?style=flat-square)](https://packagist.org/packages/beyondcode/laravel-vouchers)\n\nThis package can associate vouchers with your Eloquent models. This might come in handy, if you need to associate voucher codes with content that is stored in your Eloquent models.\n\nHere is an example of how you can create vouchers and redeem them:\n\n```php\n$videoCourse = VideoCourse::find(1);\n$voucher = $videoCourse-\u003ecreateVoucher();\n\nauth()-\u003euser()-\u003eredeemVoucher($voucher);\n```\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require beyondcode/laravel-vouchers\n```\n\nThe package will automatically register itself.\n\nYou can publish the migration with:\n\n```bash\nphp artisan vendor:publish --provider=\"BeyondCode\\Vouchers\\VouchersServiceProvider\" --tag=\"migrations\"\n```\n\nAfter the migration has been published you can create the vouchers table by running the migrations:\n\n```bash\nphp artisan migrate\n```\n\nYou can publish the config-file with:\n\n```bash\nphp artisan vendor:publish --provider=\"BeyondCode\\Vouchers\\VouchersServiceProvider\" --tag=\"config\"\n```\n\nThis is the content of the published config file:\n\n```php\n\u003c?php\n\nreturn [\n\n    /*\n     * Database table name that will be used in migration\n     */\n    'table' =\u003e 'vouchers',\n\n    /*\n     * Database pivot table name for vouchers and users relation\n     */\n    'relation_table' =\u003e 'user_voucher',\n\n    /*\n     * List of characters that will be used for voucher code generation.\n     */\n    'characters' =\u003e '23456789ABCDEFGHJKLMNPQRSTUVWXYZ',\n\n    /*\n     * Voucher code prefix.\n     *\n     * Example: foo\n     * Generated Code: foo-AGXF-1NH8\n     */\n    'prefix' =\u003e null,\n\n    /*\n     * Voucher code suffix.\n     *\n     * Example: foo\n     * Generated Code: AGXF-1NH8-foo\n     */\n    'suffix' =\u003e null,\n\n    /*\n     * Code mask.\n     * All asterisks will be removed by random characters.\n     */\n    'mask' =\u003e '****-****',\n\n    /*\n     * Separator to be used between prefix, code and suffix.\n     */\n    'separator' =\u003e '-',\n\n    /*\n     * The user model that belongs to vouchers.\n     */\n    'user_model' =\u003e \\App\\User::class,\n];\n```\n\nIf necessary, you can publish the translation files for further customization:\n\n```bash\nphp artisan vendor:publish --provider=\"BeyondCode\\Vouchers\\VouchersServiceProvider\" --tag=\"translations\"\n```\n\nYou can access the translations of the package like so: `__('vouchers::validation.code_invalid')`.\n\n## Usage\n\nThe basic concept of this package is that you can create vouchers, that are associated with a specific model. For example, you could have an application that sells online video courses and a voucher would give a user access to one specific video course.\n\nAdd the `BeyondCode\\Vouchers\\Traits\\HasVouchers` trait to all your Eloquent models, that you want to be associated with vouchers.\n\n```php\nnamespace App\\Models;\n\nuse BeyondCode\\Vouchers\\Traits\\CanRedeemVouchers;\n\nclass User extends Authenticatable\n{\n    use CanRedeemVouchers;\n    # ...\n}\n```\n\nIn addition, add the `BeyondCode\\Vouchers\\Traits\\CanRedeemVouchers` trait to your user model. This way users can easily redeem voucher codes and the package takes care of storing the voucher/user association in the database.\n\n```php\nnamespace App\\Models;\n\nuse BeyondCode\\Vouchers\\Traits\\HasVouchers;\n\nclass VideoCourse extends Model\n{\n    use HasVouchers;\n    # ...\n}\n```\n## Creating Vouchers\n\n### Using the facade\n\nYou can create one or multiple vouchers by using the `Vouchers` facade:\n\n```php\n$videoCourse = VideoCourse::find(1);\n\n// Create 5 vouchers associated to the videoCourse model.\n$vouchers = Vouchers::create($videoCourse, 5);\n```\n\nThe return value is an array containing all generated `Voucher` models.\n\nThe Voucher model has a property `code` which contains the generated voucher code.\n\n### Using the Eloquent model\n\nIn addition, you can also create vouchers by using the `createVouchers` method on the associated model:\n\n```php\n$videoCourse = VideoCourse::find(1);\n\n// Returns an array of Vouchers\n$vouchers = $videoCourse-\u003ecreateVouchers(2);\n\n// Returns a single Voucher model instance\n$vouchers = $videoCourse-\u003ecreateVoucher();\n```\n\n### Vouchers with additional data\n\nIt might be useful to associate arbitrary data to your vouchers - maybe a personal message from the person that created the voucher, etc.\nWhen creating the vouchers, you can pass an array as the second argument, which you can then retrieve later on the Voucher instance.\n\n```php\n$videoCourse = VideoCourse::find(1);\n\n$vouchers = $videoCourse-\u003ecreateVouchers(2, [\n    'from' =\u003e 'Marcel',\n    'message' =\u003e 'This one is for you. I hope you like it'\n]);\n\n$voucher = $user-\u003eredeem('ABC-DEF');\n$from = $voucher-\u003edata-\u003eget('from');\n$message = $voucher-\u003edata-\u003eget('message');\n```\n\n### Vouchers with expiry dates\n\nYou can also create vouchers that will only be available until a certain date. A user can not redeem this code afterwards.\nThe `createVouchers` method accept a Carbon instance as a third parameter.\n\n```php\n$videoCourse = VideoCourse::find(1);\n\n$videoCourse-\u003ecreateVouchers(2, [], today()-\u003eaddDays(7));\n```\n\n## Redeeming Vouchers\n\nThe easiest way to let your users redeem voucher codes is by using the `redeemCode` method on your User model:\n\n```php\n$voucher = $user-\u003eredeemCode('ABCD-EFGH');\n```\n\nIf the voucher is valid, the method will return the voucher model associated with this code.\n\nIn case you want to redeem an existing Voucher model, you can use the `redeemVoucher` method on your User model:\n\n```php\n$user-\u003eredeemVoucher($voucher);\n```\n\nAfter a user successfully redeemed a voucher, this package will fire a `BeyondCode\\Vouchers\\Events\\VoucherRedeemed` event. The event contains the user instance and the voucher instance.\nYou should listen to this event in order to perform the business logic of your application, when a user redeems a voucher.\n\n### Accessing the vouchers associated model\n\nThe `Voucher` model has a `model` relation, that will point to the associated Eloquent model:\n\n```php\n$voucher = $user-\u003eredeemCode('ABCD-EFGH');\n\n$videoCourse = $voucher-\u003emodel;\n```\n\n## Validating Vouchers \u0026 Voucher Codes\nThe `isValidCode` and `isValidVoucher` methods on the `Vouchers` facade allow you to check if a voucher code is valid or if a voucher model is valid.\n\n```php\nVouchers::isValidCode('ABCD-EFGH'); // true or false\nVouchers::isValidVoucher($voucher); // true or false\n```\n\n## Handling Errors\n\nThe `redeemCode` and `redeemVoucher` methods throw a couple of exceptions that you will want to catch and react to in your application:\n\n### Voucher invalid\n\nIf a user tries to redeem an invalid code, the package will throw the following exception: `BeyondCode\\Vouchers\\Exceptions\\VoucherIsInvalid`.\n\n### Voucher already redeemed\n\nAll generated vouchers can only be redeemed once. If a user tries to redeem a voucher for a second time, or if another user already redeemed this voucher, the package will throw the following exception: `BeyondCode\\Vouchers\\Exceptions\\VoucherAlreadyRedeemed::class`.\n\n### Voucher expired\n\nIf a user tries to redeem an expired voucher code, the package will throw the following exception: `BeyondCode\\Vouchers\\Exceptions\\VoucherExpired`.\n\n\n## Testing\n\n``` bash\ncomposer test\n```\n\n### Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n### Security\n\nIf you discover any security related issues, please email marcel@beyondco.de instead of using the issue tracker.\n\n## Credits\n\n- [Marcel Pociot](https://github.com/mpociot)\n- [All Contributors](../../contributors)\n\nThis package is heavily based on the Laravel Promocodes package from [Zura Gabievi](https://github.com/zgabievi). You can find the code on [GitHub](https://github.com/zgabievi/laravel-promocodes).\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyondcode%2Flaravel-vouchers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeyondcode%2Flaravel-vouchers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyondcode%2Flaravel-vouchers/lists"}