Coupon Model

DB Table Name	{wp_db_prefix}_fct_coupons
Schema	Check Schema
Source File	fluent-cart/app/Models/Coupon.php
Name Space	FluentCart\App\Models
Class	FluentCart\App\Models\Coupon

Traits

Trait	Description
CanSearch	Provides search(), whereLike(), whereBeginsWith(), whereEndsWith(), and groupSearch() query scopes
HasActivity	Provides the activities() polymorphic relationship to the Activity model

Attributes

Attribute	Data Type	Comment
id	Integer (BIGINT UNSIGNED)	Primary Key, auto-increment

| title | String (VARCHAR 200) | Coupon title | | code | String (VARCHAR 50) | Coupon code (unique) | | status | String (VARCHAR 20) | Coupon status (active, inactive, expired) | | type | String (VARCHAR 20) | Coupon type (percentage, fixed) | | conditions | JSON | Coupon conditions (auto-encoded/decoded via mutator) | | amount | Double | Coupon amount (in cents for fixed, raw value for percentage) | | stackable | String (VARCHAR 3) | Whether coupon is stackable ('yes' or 'no', default 'no') | | priority | Integer | Coupon priority | | use_count | Integer | Number of times used (default 0) | | notes | Text (LONGTEXT) | Coupon notes | | show_on_checkout | String (VARCHAR 3) | Show on checkout page ('yes' or 'no', default 'yes') |

The fct_coupons columns are id, title, code, type, amount, conditions, priority, stackable, show_on_checkout, status, notes, use_count, start_date, end_date and the timestamps. Coupon targeting — categories, products and buy/get sets — lives inside the conditions JSON column rather than in columns of its own. | start_date | Timestamp | Start date | | end_date | Timestamp | End date | | created_at | DateTime | Creation timestamp | | updated_at | DateTime | Last update timestamp |

Fillable Attributes

protected $fillable = [
    'parent', 'title', 'code', 'status', 'type', 'conditions',
    'amount', 'stackable', 'priority', 'use_count', 'notes',
    'show_on_checkout', 'start_date', 'end_date',
];

Casts

Attribute	Cast Type
max_uses	integer

Usage

Please check Model Basic for Common methods.

Accessing Attributes

$coupon = FluentCart\App\Models\Coupon::find(1);

$coupon->id; // returns coupon ID
$coupon->code; // returns coupon code
$coupon->type; // returns coupon type
$coupon->amount; // returns coupon amount in cents
$coupon->status; // returns coupon status
$coupon->conditions; // returns decoded conditions array (via JSON mutator)
$coupon->settings; // returns decoded settings array (via JSON mutator)
$coupon->other_info; // returns decoded other info array (via JSON mutator)
$coupon->categories; // returns decoded categories array (via JSON mutator)
$coupon->products; // returns decoded products array of integers (via JSON mutator)

Relations

This model has the following relationships that you can use.

appliedCoupons

Access the applied coupons (hasMany).

• Type: hasMany
• Related Model: FluentCart\App\Models\AppliedCoupon
• Foreign Key: coupon_id
• Local Key: id
• Returns FluentCart\Framework\Database\Orm\Collection of FluentCart\App\Models\AppliedCoupon

$coupon = FluentCart\App\Models\Coupon::find(1);
$appliedCoupons = $coupon->appliedCoupons;

orders

Access the orders that used this coupon (belongsToMany through pivot table).

• Type: belongsToMany
• Related Model: FluentCart\App\Models\Order
• Pivot Table: fct_applied_coupons
• Foreign Pivot Key: coupon_id
• Related Pivot Key: order_id
• Returns FluentCart\Framework\Database\Orm\Collection of FluentCart\App\Models\Order

$coupon = FluentCart\App\Models\Coupon::find(1);
$orders = $coupon->orders;

activities

Access the activity log entries for this coupon (polymorphic, from HasActivity trait).

• Type: morphMany
• Related Model: FluentCart\App\Models\Activity
• Morph Name: module
• Default Order: created_at DESC, id DESC
• Returns FluentCart\Framework\Database\Orm\Collection of FluentCart\App\Models\Activity

$coupon = FluentCart\App\Models\Coupon::find(1);
$activities = $coupon->activities;

Scopes

This model has the following scopes that you can use.

active()

Get only active coupons that have not expired.

$coupons = FluentCart\App\Models\Coupon::active()->get();

This scope filters coupons that are:

• Status is 'active'
• End date is null, or '0000-00-00 00:00:00', or in the future (compared to DateTime::gmtNow())

Scopes from CanSearch Trait

search($params)

Search coupons using an array of filter parameters.

$coupons = FluentCart\App\Models\Coupon::search([
    'status' => 'active',
    'type'   => 'percentage',
])->get();

whereLike($column, $value)

WHERE column LIKE %value% query.

$coupons = FluentCart\App\Models\Coupon::whereLike('code', 'SAVE')->get();

whereBeginsWith($column, $value)

WHERE column LIKE value% query.

$coupons = FluentCart\App\Models\Coupon::whereBeginsWith('code', 'SAVE')->get();

whereEndsWith($column, $value)

WHERE column LIKE %value query.

$coupons = FluentCart\App\Models\Coupon::whereEndsWith('code', '10')->get();

Boot behaviour

saving returns false when the model is a converted-currency copy (CouponCurrency::isConvertedCopy()). Those copies exist in memory so a cart can price a coupon in its own currency; writing one back would store the converted amount on the real coupon.

Methods

Along with Global Model methods, this model has few helper methods.

JSON Mutators (Accessors & Mutators)

The Coupon model uses accessor/mutator pairs to automatically handle JSON encoding and decoding for several attributes. When you set these attributes with an array or object, they are automatically JSON-encoded before storage. When you read them, they are automatically JSON-decoded into arrays.

conditions (setConditionsAttribute / getConditionsAttribute)

Set and get coupon conditions with automatic JSON encoding/decoding.

• Setter: Accepts an array or object, JSON-encodes it. Falls back to '[]' if value is empty or encoding fails.
• Getter: Returns a decoded array, or [] if value is empty.

$coupon = FluentCart\App\Models\Coupon::find(1);

// Setting conditions
$coupon->conditions = [
    'min_purchase_amount' => 5000,
    'max_per_customer'    => 3,
    'max_uses'            => 100,
    'is_recurring'        => 'yes',
];

// Getting conditions
$conditions = $coupon->conditions; // returns array

settings (setSettingsAttribute / getSettingsAttribute)

Set and get coupon settings with automatic JSON encoding/decoding.

• Setter: If value is an array or object, JSON-encodes with JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES flags.
• Getter: If value is a string, JSON-decodes it. Returns the decoded array on success, or the original value if decoding fails.

$coupon = FluentCart\App\Models\Coupon::find(1);

// Setting
$coupon->settings = ['custom_field' => 'value'];

// Getting
$settings = $coupon->settings; // returns array

other_info (setOtherInfoAttribute / getOtherInfoAttribute)

Set and get additional info with automatic JSON encoding/decoding. The setter has special handling: if buy_products or get_products keys are present and are arrays, their values are cast to integers via array_map('intval', ...).

• Setter: Accepts a string (JSON-decodes it first), array, or object. Casts buy_products and get_products values to integers. Falls back to '[]' for non-array/non-object values.
• Getter: Returns a decoded array, or [] if value is empty.

$coupon = FluentCart\App\Models\Coupon::find(1);

// Setting (buy_products and get_products values auto-cast to integers)
$coupon->other_info = [
    'buy_products' => [1, 2, 3],
    'get_products' => [4, 5],
];

// Getting
$otherInfo = $coupon->other_info; // returns array

categories (setCategoriesAttribute / getCategoriesAttribute)

Set and get categories with automatic JSON encoding/decoding.

• Setter: If value is an array or object, JSON-encodes it. Falls back to '[]' otherwise.
• Getter: Returns a decoded array, or [] if value is empty.

$coupon = FluentCart\App\Models\Coupon::find(1);

// Setting
$coupon->categories = [1, 2, 3];

// Getting
$categories = $coupon->categories; // returns array

products (setProductsAttribute / getProductsAttribute)

Set and get products with automatic JSON encoding/decoding. The setter casts each product ID to an integer via array_map('intval', ...).

• Setter: If value is an array or object, casts each item to integer, then JSON-encodes. Falls back to '[]' otherwise.
• Getter: Returns a decoded array, or [] if value is empty.

$coupon = FluentCart\App\Models\Coupon::find(1);

// Setting (values are auto-cast to integers)
$coupon->products = [1, 2, 3];

// Getting
$products = $coupon->products; // returns array of integers

getEndDate()

Get the coupon's end date.

• Returns String|null - End date value

$coupon = FluentCart\App\Models\Coupon::find(1);
$endDate = $coupon->getEndDate();

getStatus()

Get the coupon's current status.

• Returns String - Status value

$coupon = FluentCart\App\Models\Coupon::find(1);
$status = $coupon->getStatus();

setStatus($value)

Set the coupon's status.

• Parameters: $value (String) - Status value (e.g., 'active', 'inactive', 'expired')

$coupon = FluentCart\App\Models\Coupon::find(1);
$coupon->setStatus('active');

getMeta($metaKey, $default = null)

Get a coupon meta value from the fct_meta table where object_type is 'coupon'.

• Parameters: $metaKey (String) - Meta key, $default (Mixed) - Default value if meta not found
• Returns Mixed - Meta value or default

$coupon = FluentCart\App\Models\Coupon::find(1);
$metaValue = $coupon->getMeta('custom_field', 'default');

updateMeta($metaKey, $metaValue)

Create or update a coupon meta value in the fct_meta table where object_type is 'coupon'. If the meta key already exists for this coupon, it updates the value. Otherwise, it creates a new meta record.

• Parameters: $metaKey (String) - Meta key, $metaValue (Mixed) - Meta value
• Returns FluentCart\App\Models\Meta - The created or updated Meta instance

$coupon = FluentCart\App\Models\Coupon::find(1);
$meta = $coupon->updateMeta('custom_field', 'new_value');

isRecurringDiscount()

Check if this coupon is configured as a recurring discount. Looks at the is_recurring key inside the conditions JSON attribute.

• Returns Boolean - true if conditions.is_recurring equals 'yes', false otherwise

$coupon = FluentCart\App\Models\Coupon::find(1);

if ($coupon->isRecurringDiscount()) {
    // This coupon applies to recurring subscription payments
}

Usage Examples

Creating a Coupon

use FluentCart\App\Models\Coupon;

$coupon = Coupon::create([
    'code'       => 'SAVE10',
    'title'      => 'Save 10%',
    'type'       => 'percentage',
    'amount'     => 10, // 10%
    'status'     => 'active',
    'stackable'  => 'no',
    'conditions' => [
        'min_purchase_amount' => 5000,
        'max_uses'            => 100,
        'max_per_customer'    => 3,
        'is_recurring'        => 'yes',
    ],
    'start_date' => now(),
    'end_date'   => now()->addDays(30),
]);

Retrieving Coupons

// Get coupon by code
$coupon = Coupon::where('code', 'SAVE10')->first();

// Get all active coupons
$coupons = Coupon::active()->get();

// Get coupon by ID
$coupon = Coupon::find(1);

// Search coupons by code pattern
$coupons = Coupon::whereLike('code', 'SAVE')->get();

// Get coupon with activities
$coupon = Coupon::with(['activities.user'])->find(1);

// Get coupon with applied coupons count
$coupon = Coupon::withCount('appliedCoupons')->find(1);

Updating a Coupon

$coupon = Coupon::find(1);
$coupon->use_count = $coupon->use_count + 1;
$coupon->save();

Checking Recurring Discount

$coupon = Coupon::find(1);
if ($coupon->isRecurringDiscount()) {
    // Handle recurring discount logic
}

Working with Meta

$coupon = Coupon::find(1);

// Set meta
$coupon->updateMeta('custom_setting', 'value');

// Get meta with default
$value = $coupon->getMeta('custom_setting', 'fallback');

Deleting a Coupon

$coupon = Coupon::find(1);
$coupon->delete();

---