gordi256/laravel-promocodes

优惠券和促销码生成器

维护者

详细信息

github.com/gordi256/laravel-promocodes

主页

源代码

安装: 11

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 1

dev-main 2024-04-26 05:03 UTC

Requires

MIT 760a2de9a218bc72f5384bc7ab839ff11a9366cc

  • Nageswara Rao <nag.samayam.woop@gmail.com>

laravelcouponspromocodesnagsamayam

This package is auto-updated.

Last update: 2024-09-26 05:49:14 UTC

README

为 Laravel 生成的优惠券和促销码。此包需要 Laravel 11.x 和 PHP 8.1。

安装

您可以通过 composer 安装此包

composer require gordi256/laravel-promocodes

配置

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="laravel-promocodes-config"

这是已发布配置文件的内容

return [
    'models' => [
        'promocodes' => [
            'model' => \NagSamayam\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' => \NagSamayam\Promocodes\Models\PromocodeUser::class,
            'table_name' => 'promocode_user',
        ],
    ],
    'code_mask' => '**-****-****',
    'allowed_symbols' => 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789',
];

配置此文件后，使用以下命令发布和运行迁移

php artisan vendor:publish --tag="laravel-promocodes-migrations"
php artisan migrate

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

namespace App\Models;

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

class User extends Authenticatable
{
    use AppliesPromocode;

    //
}

用法

使用非常简单。方法被组合在一起，这样您就可以轻松地配置促销码。

参考

创建促销码

使用类

根据需要组合方法。您可以跳过任何不需要的方法，大多数方法已经具有默认值。对于自定义代码生成，`create` 方法应具有参数。或者您可以使用 `createWithCustomCode` 并传递参数。这两种选项都可以。

use NagSamayam\Promocodes\Facades\Promocodes;
use NagSamayam\Promocodes\Enums\PromocodeType;
use NagSamayam\Promocodes\Enums\PromocodeStatus;

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
    ->expiration(now()->addYear()) // default: null
    ->details(['percent_off' => 50]) // default: []
    ->minOrderValue(500) // default: null
    ->maxDiscount(5) // default: null
    ->createdByAdmin(User::find(1)) // default: null
    ->type(PromocodeType::PERCENT->value) // default: PromocodeType::FLAT->value
    ->status(PromocodeStatus::ACTIVE->value); // default: 'inactive'
    ->create(); // default: null

Promocodes::multiUse() // default: false
    ->boundToUser() // default: false
    ->user(User::find(1)) // default: null
    ->usages(5) // default: 1
    ->expiration(now()->addYear()) // default: null
    ->details(['discount' => 50]) // default: []
    ->minOrderValue(500) // default: null
    ->maxDiscount(5) // default: null
    ->createdByAdmin(User::find(1)) // default: null
    ->type(PromocodeType::FLAT->value) // default: PromocodeType::FLAT->value
    ->status(PromocodeStatus::ACTIVE->value); // default: 'inactive'
    ->create('AA-A4C-B1'); // default: null // Custom promo code can be passed // Equivalent to createWithCustomCode('MO-OT2P-897P') method

Promocodes::multiUse() // default: false
    ->boundToUser() // default: false
    ->user(User::find(1)) // default: null
    ->usages(5) // default: 1
    ->expiration(now()->addYear()) // default: null
    ->details([
        'percent_off' => 50,
        'message' => 'This one is for you. I hope you like it',
    ]) // default: []
    ->minOrderValue(500) // default: null
    ->maxDiscount(5) // default: null
    ->createdByAdmin(User::find(1)) // default: null
    ->type(PromocodeType::PERCENT->value) // default: PromocodeType::FLAT->value
    ->status(); // default: 'inactive'
    ->createWithCustomCode('MO-OT2P-897P');

使用辅助函数

有一个全局辅助函数，它将执行与促销码类相同的功能。您可以从 PHP 8.1 开始使用命名参数的魔法。

use NagSamayam\Promocodes\Enums\PromocodeType;
use NagSamayam\Promocodes\Enums\PromocodeStatus;

create_promocodes(
    type: PromocodeType::PERCENT->value, // default: PromocodeType::FLAT->value
    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
    expiration: now()->addYear(), // default: null
    details: ['percent_off' => 50], // default: [],
    createdByAdmin: User::find(98), // default: null
  	maxDiscount: 101, // default: null
  	minOrderValue: 1000, // default: null
    status: PromocodeStatus::ACTIVE->value // default: PromocodeStatus::INACTIVE->value
);

create_custom_promocode(
    code: '66-OMPY-ULZU',
    type: PromocodeType::FLAT->value, // default: PromocodeType::FLAT->value
    multiUse: true, // default: false
    boundToUser: true, // default: false
    user: User::find(1), // default: null
    usages: 5, // default: 1
    expiration: now()->addYear(), // default: null
    details: ['discount' => 50], // default: [],
    createdByAdmin: User::find(98), // default: null
  	maxDiscount: 101, // default: null
  	minOrderValue: 1000 // default: null
    status: PromocodeStatus::ACTIVE->value // default: PromocodeStatus::INACTIVE->value
);

生成促销码

如果您想输出促销码而不是将它们保存到数据库中，请调用 generate 方法而不是 create。

use NagSamayam\Promocodes\Facades\Promocodes;
use NagSamayam\Promocodes\Enums\PromocodeType;
use NagSamayam\Promocodes\Enums\PromocodeStatus;

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
    ->expiration(now()->addYear()) // default: null
    ->details(['percent_off' => 50]) // default: []
    ->minOrderValue(500)
    ->maxDiscount(5)
    ->createdByAdmin(User::find(1))
    ->status(PromocodeStatus::ACTIVE->value) // default: PromocodeStatus::INACTIVE->value
    ->type(PromocodeType::PERCENT->value) // default: PromocodeType::FLAT->value
    ->generate();

应用促销码

使用类

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

use NagSamayam\Promocodes\Facades\Promocodes;

Promocodes::code('ABC-DEF')
    ->user(User::find(1)) // default: null
    ->apply(['order_id' => '405-6828433-4214765']); // default: null // Good to send unique order ID // Preferbly string format

使用辅助函数

有一个全局辅助函数，它将执行与促销码类相同的功能。

apply_promocode(
    'ABC-DEF',
    User::find(1), // default: null,
    ['order_id' => '405-6828433-4214765'] // default: null // Good to send unique order ID // Preferbly string format
);

异常

在尝试应用促销码时，您应该注意异常。大多数代码在有问题时会抛出异常。

// NagSamayam\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."
PromocodeAlreadyExistedException - "The given promocode `10s%discount` is already existed. Please try with a new one."
PromocodeAlreadyUsedForOrderException - "The given code `ABC-DEF` is already applied for the order with id 405-6828433-4214765."
PromocodeNotAcitveException - "The given promocode `ABC-DEF` is not active. Please try with a new one."

事件

有两个事件在应用时被触发。

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

过期促销码

使用辅助函数

有一个全局辅助函数，可以过期促销码。

expire_promocode('ABC-DEF');

更新促销码状态

使用类

use NagSamayam\Promocodes\Facades\Promocodes;
use NagSamayam\Promocodes\Enums\PromocodeStatus;

Promocodes::code('ABC-DEF')
    ->updatedByAdmin(User::find(6))
    ->updateStatus(PromocodeStatus::ACTIVE->value);

使用辅助函数

update_promocode_status('ABC-DEF',
    PromocodeStatus::ACTIVE->value,
    User::find(6)
);

特质方法

如果您已将 AppliesPromocode 特质添加到用户模型中，您将在用户上获得一些额外的功能。

$user = User::find(1);

$user->appliedPromocodes; // Returns promocodes applied by user
$user->boundPromocodes; // Returns promocodes bound to user
$user->applyPromocode('ABC-DEF', ['order_id' => '405-6828433-4214765']); // Applies promocode to user

获取适用折扣

有一种方法可以获取应用于总订单价值的折扣。

use NagSamayam\Promocodes\Facades\Promocodes;

Promocodes::code('ABC-DEF')
    ->orderTotal(1000) // default: 0
    ->getApplicableDiscount($forceCheck = true); // default: false // If false, it will not check for usagesLeft, status and expiry

测试

很快就会添加

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG。

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全漏洞

如果您发现任何安全相关的问题，请通过电子邮件 nag.samayam@gmail.com 而不是使用问题跟踪器。

致谢

此包在很大程度上基于 Zura Gabievi 的 Laravel Promocodes 包。您可以在 GitHub 上找到代码。

许可

MIT 许可证（MIT）。有关更多信息，请参阅 许可文件。

注意

我开发了这个包用于个人用途。我将其公开。希望它对您有帮助。请不要期望立即修复错误。希望您能理解。