zgabievi / promocodes
:package_description
Installs: 87 222
Dependents: 1
Suggesters: 0
Security: 0
Stars: 442
Watchers: 8
Forks: 96
Open Issues: 12
Requires
- php: ^8.1
- illuminate/broadcasting: ^9.0
- illuminate/console: ^9.0
- illuminate/container: ^9.0
- illuminate/database: ^9.0
- illuminate/queue: ^9.0
- illuminate/support: ^9.0
Requires (Dev)
- nunomaduro/larastan: ^2.0
- orchestra/testbench: ^7.1
- pestphp/pest: ^1.21
- pestphp/pest-plugin-laravel: ^1.2
- pestphp/pest-plugin-mock: ^1.0
- phpunit/phpunit: ^9.0
- dev-release/9.0
- dev-main
- 9.1.0
- 9.0.0
- 8.1.2
- 8.1.1
- 8.1.0
- 8.0.0
- 2.3.3
- 2.3.2
- 2.3.1
- 2.3.0
- 2.2.1
- 2.2.0
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 1.2.0
- 1.1.0
- 1.0.1
- 1.0.0
- 0.5.4
- 0.5.1
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.0
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.5
- 0.1.4
- 0.1.3
- 0.1.2
- 0.1.1
- 0.1.0
- dev-dependabot/composer/guzzlehttp/psr7-2.5.0
- dev-dependabot/composer/symfony/http-kernel-6.2.6
- dev-89-validation-promo-code
- dev-bugfix/88-typehint-causing-issues-with-custom-user-model
- dev-release/8.0
- dev-release/5.1
This package is auto-updated.
Last update: 2023-04-19 19:54:26 UTC
README
laravel-promocodes
Coupons and promotional codes generator for Laravel. Current release is only for Laravel 9.x and PHP 8.1. It's completely rewritten, and if you are using previous version, you should change your code accordingly. Code is simplified now and it should take you several minutes to completely rewrite usage.
Attention: Current version is completely rewritten. If you are missing some functionality, that was possible to achieve in previous versions, fill free to open issue. Hope this new version will be easier to use, and it will provide better functionality for your needs.
Installation
You can install the package via composer:
composer require zgabievi/laravel-promocodes
Configuration
php artisan vendor:publish --provider="Zorb\Promocodes\PromocodesServiceProvider"
Now you can change configurations as you need:
return [ 'models' => [ 'promocodes' => [ 'model' => \Zorb\Promocodes\Models\Promocode::class, 'table_name' => 'promocodes', 'foreign_id' => 'promocode_id', ], 'users' => [ 'model' => \App\Models\User::class, 'table_name' => 'users', 'foreign_id' => 'user_id', ], 'pivot' => [ 'model' => \Zorb\Promocodes\Models\PromocodeUser::class, 'table_name' => 'promocode_user', ], ], 'code_mask' => '****-****', 'allowed_symbols' => 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789', ];
After you configure this file, run migrations:
php artisan migrate
Now you will need to use AppliesPromocode on your user model.
namespace App\Models; use Illuminate\Foundation\Auth\User as Authenticatable; use Zorb\Promocodes\Traits\AppliesPromocode; class User extends Authenticatable { use AppliesPromocode; // }
Usage
It's very easy to use. Methods are combined, so that you can configure promocodes easily.
- Reference
- Creating Promocodes
- Generating Promocodes
- Applying Promocode
- Expiring Promocode
- Additional Methods
Reference
Name | Explanation |
---|---|
Mask | Astrisks will be replaced with random symbol |
Characters | Allowed symbols to use in mask replacement |
Multi use | Define if single code can be used multiple times, by the same user |
Unlimited | Generated code will have unlimited usages |
Bound to user | Define if promocode can be used only one user, if user is not assigned initially, first user will be bound to promocode |
User | Define user who will be initially bound to promocode |
Count | Amount of unique promocodes should be generated |
Usages | Define how many times can promocode be used |
Expiration | DateTime when promocode should be expired. Null means that promocode will never expire |
Details | Array of details which will be retrieved upon apply |
Creating Promocodes
Using class
Combine methods as you need. You can skip any method that you don't need, most of them already have default values.
use Zorb\Promocodes\Facades\Promocodes; Promocodes::mask('AA-***-BB') // default: config('promocodes.code_mask') ->characters('ABCDE12345') // default: config('promocodes.allowed_symbols') ->multiUse() // default: false ->unlimited() // default: false ->boundToUser() // default: false ->user(User::find(1)) // default: null ->count(5) // default: 1 ->usages(5) // default: 1 ->expiration(now()->addYear()) // default: null ->details([ 'discount' => 50 ]) // default: [] ->create();
Using helper
There is a global helper function which will do the same as promocodes class. You can use named arguments magic from php 8.1.
createPromocodes( mask: 'AA-***-BB', // default: config('promocodes.code_mask') characters: 'ABCDE12345', // default: config('promocodes.allowed_symbols') multiUse: true, // default: false unlimited: true, // default: false boundToUser: true, // default: false user: User::find(1), // default: null count: 5, // default: 1 usages: 5, // default: 1 expiration: now()->addYear(), // default: null details: [ 'discount' => 50 ] // default: [] );
Using command
There is also the command for creating promocodes. Parameters are optional here too.
php artisan promocodes:create\ --mask="AA-***-BB"\ --characters="ABCDE12345"\ --multi-use\ --unlimited\ --bound-to-user\ --user=1\ --count=5\ --usages=5\ --expiration="2022-01-01 00:00:00"
Generating Promocodes
If you want to output promocodes and not save them to database, you can call generate method instead of create.
use Zorb\Promocodes\Facades\Promocodes; Promocodes::mask('AA-***-BB') // default: config('promocodes.code_mask') ->characters('ABCDE12345') // default: config('promocodes.allowed_symbols') ->multiUse() // default: false ->unlimited() // default: false ->boundToUser() // default: false ->user(User::find(1)) // default: null ->count(5) // default: 1 ->usages(5) // default: 1 ->expiration(now()->addYear()) // default: null ->details([ 'discount' => 50 ]) // default: [] ->generate();
Applying Promocode
Using class
Combine methods as you need. You can skip any method that you don't need.
use Zorb\Promocodes\Facades\Promocodes; Promocodes::code('ABC-DEF') ->user(User::find(1)) // default: null ->apply();
Using helper
There is a global helper function which will do the same as promocodes class.
applyPomocode( 'ABC-DEF', User::find(1) // default: null );
Using command
There is also the command for applying promocode.
php artisan promocodes:apply ABC-DEF --user=1
Exceptions
While trying to apply promocode, you should be aware of exceptions. Most part of the code throws exceptions, when there is a problem:
// Zorb\Promocodes\Exceptions\* PromocodeAlreadyUsedByUserException - "The given code `ABC-DEF` is already used by user with id 1." PromocodeBoundToOtherUserException - "The given code `ABC-DEF` is bound to other user, not user with id 1." PromocodeDoesNotExistException - "The given code `ABC-DEF` doesn't exist." | "The code was not event provided." PromocodeExpiredException - "The given code `ABC-DEF` already expired." PromocodeNoUsagesLeftException - "The given code `ABC-DEF` has no usages left." UserHasNoAppliesPromocodeTrait - "The given user model doesn't have AppliesPromocode trait." UserRequiredToAcceptPromocode - "The given code `ABC-DEF` requires to be used by user, not by guest."
Events
There are two events which are fired upon applying.
// Zorb\Promocodes\Events\* GuestAppliedPromocode // Fired when guest applies promocode // It has public variable: promocode UserAppliedPromocode // Fired when user applies promocode // It has public variable: promocode // It has public variable: user
Expiring Promocode
Using helper
There is a global helper function which will expire promocode.
expirePromocode('ABC-DEF');
Using command
There is also the command for expiring promocode.
php artisan promocodes:expire ABC-DEF
Trait Methods
If you added AppliesPromocode trait to your user model, you will have some additional methods on user.
$user = User::find(1); $user->appliedPromocodes // Returns promocodes applied by user $user->boundPromocodes // Returns promocodes bound to user $user->applyPromocode('ABC-DEF') // Applies promocode to user
Additional Methods
Promocodes::all(); // To retrieve all (available/not available) promocodes Promocodes::available(); // To retrieve valid (available) promocodes Promocodes::notAvailable(); // To retrieve invalid (not available) promocodes
Testing
composer test
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.