zgabievi/promocodes

此包已被废弃且不再维护。作者建议使用zgabievi/laravel-promocodes包。

:package_description


README

#StandWithUkraine laravel-promocodes

laravel-promocodes

Packagist Packagist license

Laravel的优惠券和促销代码生成器。当前版本仅适用于Laravel 9.x和PHP 8.1。它已被完全重写,如果您使用的是旧版本,则需要相应地更改代码。代码现在已简化,重写使用可能只需几分钟。

注意:当前版本已完全重写。如果您缺少在旧版本中可以实现的功能,请随时创建问题。希望这个新版本使用起来更简单,并且能够满足您的需求。

安装

您可以通过composer安装此包。

composer require zgabievi/laravel-promocodes

配置

php artisan vendor:publish --provider="Zorb\Promocodes\PromocodesServiceProvider"

现在您可以根据需要更改配置。

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',
];

配置此文件后,运行迁移。

php artisan migrate

现在您需要在用户模型上使用AppliesPromocode。

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Zorb\Promocodes\Traits\AppliesPromocode;

class User extends Authenticatable {
    use AppliesPromocode;

    //
}

使用

使用非常简单。方法已组合,因此您可以轻松配置优惠券。

参考

名称 说明
掩码 星号将被替换为随机符号
字符 用于掩码替换的允许符号
多次使用 定义单个代码是否可以由同一用户多次使用
无限 生成的代码将具有无限使用次数
绑定到用户 定义优惠券是否只能由一个用户使用,如果用户最初未分配,则第一个用户将被绑定到优惠券
用户 定义最初将被绑定到优惠券的用户
数量 应生成的独特优惠券数量
使用次数 定义优惠券可以使用多少次
过期时间 优惠券应过期的日期时间。空值表示优惠券将永不过期
详细信息 在应用时检索的详细信息数组

创建优惠券

使用类

根据需要组合方法。您可以跳过不需要的方法,其中大多数已具有默认值。

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();

使用辅助函数

还有一个全局辅助函数,它将执行与优惠券类相同的功能。您可以使用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: []
);

使用命令

还有创建优惠券的命令。这里参数也是可选的。

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"

生成优惠码

如果您想输出优惠码而不是将它们保存到数据库中,您应调用 generate 方法而不是 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();

应用优惠码

使用类

根据需要组合方法。您可以跳过任何不需要的方法。

use Zorb\Promocodes\Facades\Promocodes;

Promocodes::code('ABC-DEF')
          ->user(User::find(1)) // default: null
          ->apply();

使用助手

有一个全局助手函数,它将执行与 promocodes 类相同的功能。

applyPomocode(
    'ABC-DEF',
    User::find(1) // default: null
);

使用命令

还有一个用于应用优惠码的命令。

php artisan promocodes:apply ABC-DEF --user=1

异常

在尝试应用优惠码时,您应了解异常。大部分代码在出现问题时都会抛出异常。

// 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."

事件

有两个事件会在应用优惠码时触发。

// 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

即将到期的优惠码

使用助手

有一个全局助手函数,可以将优惠码设置为过期。

expirePromocode('ABC-DEF');

使用命令

还有一个用于过期优惠码的命令。

php artisan promocodes:expire ABC-DEF

特性方法

如果您将 AppliesPromocode 特性添加到您的用户模型中,您将在用户上获得一些附加方法。

$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

附加方法

Promocodes::all(); // To retrieve all (available/not available) promocodes
Promocodes::available(); // To retrieve valid (available) promocodes
Promocodes::notAvailable(); // To retrieve invalid (not available) promocodes

测试

composer test

贡献

有关详细信息,请参阅 CONTRIBUTING

致谢

许可证

MIT 许可证 (MIT)。有关更多信息,请参阅 许可证文件