Download the PHP package beyondcode/laravel-vouchers without Composer

Laravel Vouchers 🎟

This 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.

Here is an example of how you can create vouchers and redeem them:

Installation

You can install the package via composer:

The package will automatically register itself.

You can publish the migration with:

After the migration has been published you can create the vouchers table by running the migrations:

You can publish the config-file with:

This is the content of the published config file:

If necessary, you can publish the translation files for further customization:

You can access the translations of the package like so: __('vouchers::validation.code_invalid').

Usage

The 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.

Add the BeyondCode\Vouchers\Traits\HasVouchers trait to all your Eloquent models, that you want to be associated with vouchers.

In 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.

Creating Vouchers

Using the facade

You can create one or multiple vouchers by using the Vouchers facade:

The return value is an array containing all generated Voucher models.

The Voucher model has a property code which contains the generated voucher code.

Using the Eloquent model

In addition, you can also create vouchers by using the createVouchers method on the associated model:

Vouchers with additional data

It might be useful to associate arbitrary data to your vouchers - maybe a personal message from the person that created the voucher, etc. When creating the vouchers, you can pass an array as the second argument, which you can then retrieve later on the Voucher instance.

Vouchers with expiry dates

You can also create vouchers that will only be available until a certain date. A user can not redeem this code afterwards. The createVouchers method accept a Carbon instance as a third parameter.

Redeeming Vouchers

The easiest way to let your users redeem voucher codes is by using the redeemCode method on your User model:

If the voucher is valid, the method will return the voucher model associated with this code.

In case you want to redeem an existing Voucher model, you can use the redeemVoucher method on your User model:

After 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. You should listen to this event in order to perform the business logic of your application, when a user redeems a voucher.

Accessing the vouchers associated model

The Voucher model has a model relation, that will point to the associated Eloquent model:

Validating Vouchers & Voucher Codes

The 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.

Handling Errors

The redeemCode and redeemVoucher methods throw a couple of exceptions that you will want to catch and react to in your application:

Voucher invalid

If a user tries to redeem an invalid code, the package will throw the following exception: BeyondCode\Vouchers\Exceptions\VoucherIsInvalid.

Voucher already redeemed

All 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.

Voucher expired

If a user tries to redeem an expired voucher code, the package will throw the following exception: BeyondCode\Vouchers\Exceptions\VoucherExpired.

Testing

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Marcel Pociot
• All Contributors

This package is heavily based on the Laravel Promocodes package from Zura Gabievi. You can find the code on GitHub.

License

The MIT License (MIT). Please see License File for more information.