Coupons extends AppModel
Coupon management
Table of Contents
Methods
| __construct() | Initialize Coupons |
| add() | Creates a new coupon |
| delete() | Permanently removes the coupon from the system |
| edit() | Updates an existing coupon |
| get() | Fetches a coupon using the given $coupon_id |
| getAmountTypes() | Retrieves a list of coupon amount types |
| getByCode() | Retrieves a coupon by its code |
| getCouponAmounts() | Fetches a list of currencies and amounts associated with a given coupon |
| getForPackages() | Fetches a coupon using the given code or coupon ID. Only returns coupons that are active and capable of being used for the current company. |
| getList() | Fetches a list of all coupons for a given company |
| getListCount() | Returns the total number of coupons returned from Coupons::getList(), useful in constructing pagination for the getList() method. |
| getRecurring() | Retrieves the given coupon and the recurring coupon amount iff it recurs and applies to the given currency at the given date |
| incrementUsage() | Increments the used quantity on the given coupon |
| validateAmountDuplicates() | Validates an array of coupon discounts to check for duplicate currencies. |
| validateAmountType() | Validates a coupon amount's 'type' field |
| validateStatus() | Validates a coupon's 'status' field |
| validateUniqueCode() | Validates whether the given coupon code is currently in use |
| getAmounts() | Retrieves all packages associated with a given coupon |
| getCoupons() | Partially constructs the query required by both Coupons::getList() and Coupons::getListCount() |
| getPackages() | Retrieves all packages associated with a given coupon |
| getRules() | Returns the rule set for adding/editing coupons |
Methods
__construct()
Initialize Coupons
public
__construct() : mixed
add()
Creates a new coupon
public
add(array<string|int, mixed> $vars) : int
Parameters
- $vars : array<string|int, mixed>
-
An array of coupon information including:
- code The coupon code
- company_id The company ID this coupon belongs to
- used_qty The number of times this coupon has been used (optional, default 0)
- max_qty The maximum number of times this coupon can be used (optional, default 0 for unlimited)
- start_date The date this coupon goes into effect (optional)
- end_date The date this coupon is no longer effective (optional)
- status The status of the coupon, 'active' or 'inactive' (optional, default 'active')
- recurring Allows the coupon to be applied every time the service renews, restrictions on start_date/end_date/used_qty/max_qty do not apply. If the coupon was applied originally, it will continue to be applied so long as status is 'active' and the package is still tied to this coupon.
- limit_recurring Allows the coupon to be used again every time a renewing service that uses it renews (1 to increase the used quantity each time a renewing service renews, 0 for renewing services to use this coupon only once. optional, default 0)
- packages A numerically indexed array containing package IDs this coupon applies to:
- amounts An array of discounts for this coupon containing (only one per currency):
- currency The ISO 4217 currency code
- amount The amount of the discount
- type The type of discount 'amount' a currency amount, 'percent' a percentage (optional, default 'percent')
Return values
int —The ID code for this coupon
delete()
Permanently removes the coupon from the system
public
delete(int $coupon_id) : mixed
Parameters
- $coupon_id : int
-
The ID of the coupon to delete
edit()
Updates an existing coupon
public
edit(int $coupon_id, array<string|int, mixed> $vars) : int
Parameters
- $coupon_id : int
-
The ID of the coupon to update
- $vars : array<string|int, mixed>
-
An array of coupon information including:
- code The coupon code
- company_id The ID of the company this coupon belongs to
- used_qty The number of times this coupon has been used (optional, default 0)
- max_qty The maximum number of times this coupon can be used (optional, default 0 for unlimited)
- start_date The date this coupon goes into effect (optional)
- end_date The date this coupon is no longer effective (optional)
- status The status of the coupon, 'active' or 'inactive' (optional, default 'active')
- recurring Allows the coupon to be applied every time the service renews, restrictions on start_date/end_date/used_qty/max_qty do not apply. If the coupon was applied originally, it will continue to be applied so long as status is 'active' and the package is still tied to this coupon.
- limit_recurring Allows the coupon to be used again every time a renewing service that uses it renews (1 to increase the used quantity each time a renewing service renews, 0 for renewing services to use this coupon only once. optional, default 0)
- packages A numerically indexed array containing package IDs this coupon applies to:
- amounts An array of discounts for this coupon containing (only one per currency):
- currency The ISO 4217 currency code
- amount The amount of the discount
- type The type of discount 'amount' a currency amount, 'percent' a percentage (optional, default 'percent')
Return values
int —The ID code for this coupon
get()
Fetches a coupon using the given $coupon_id
public
get(int $coupon_id) : mixed
Parameters
- $coupon_id : int
-
The ID of the coupon to fetch
Return values
mixed —A stdClass object representing the coupon, false if no such coupon exists
getAmountTypes()
Retrieves a list of coupon amount types
public
getAmountTypes() : array<string|int, mixed>
Return values
array<string|int, mixed> —Key=>value pairs of coupon amount types
getByCode()
Retrieves a coupon by its code
public
getByCode(string $code) : mixed
Parameters
- $code : string
-
The coupon code representing the coupon to fetch
Return values
mixed —A stdClass object representing the coupon, or false if no such coupon exists
getCouponAmounts()
Fetches a list of currencies and amounts associated with a given coupon
public
getCouponAmounts(int $coupon_id) : array<string|int, mixed>
Parameters
- $coupon_id : int
-
The ID of the coupon whose amounts to fetch
Return values
array<string|int, mixed> —An array of objects representing each coupon amount
getForPackages()
Fetches a coupon using the given code or coupon ID. Only returns coupons that are active and capable of being used for the current company.
public
getForPackages([string $code = null ][, string $coupon_id = null ][, array<string|int, mixed> $packages = null ]) : mixed
Parameters
- $code : string = null
-
The coupon code to fetch
- $coupon_id : string = null
-
The coupon ID to fetch
- $packages : array<string|int, mixed> = null
Return values
mixed —A stdClass object representing the coupon, false if no such coupon exists of the coupon is no longer valid
getList()
Fetches a list of all coupons for a given company
public
getList(int $company_id[, int $page = 1 ][, string $order_by = ['code' => 'ASC'] ][, array<string|int, mixed> $filters = [] ]) : mixed
Parameters
- $company_id : int
-
The ID of the company to fetch coupons for
- $page : int = 1
-
The page to return results for (optional, default 1)
- $order_by : string = ['code' => 'ASC']
-
The sort and order conditions (e.g. array('sort_field'=>"ASC"), optional)
- $filters : array<string|int, mixed> = []
-
A list of parameters to filter by, including:
- code The (partial) code of the coupon
- discount_type The type of discount for which to filter coupons
- currency The currency for which to filter coupons
- active Filter coupons depending on whether or not they are active
- internal Filter coupons depending on whether or not they are internal coupons
- package_group The package group on which to filter coupons
Return values
mixed —An array of stdClass objects representing coupons, false if no coupons found
getListCount()
Returns the total number of coupons returned from Coupons::getList(), useful in constructing pagination for the getList() method.
public
getListCount(int $company_id[, array<string|int, mixed> $filters = [] ]) : int
Parameters
- $company_id : int
-
The ID of the company to fetch coupons for
- $filters : array<string|int, mixed> = []
-
A list of parameters to filter by, including:
- code The (partial) code of the coupon
- discount_type The type of discount for which to filter coupons
- currency The currency for which to filter coupons
- active Filter coupons depending on whether or not they are active
- internal Filter coupons depending on whether or not they are internal coupons
- package_group The package group on which to filter coupons
Tags
Return values
int —The total number of coupons
getRecurring()
Retrieves the given coupon and the recurring coupon amount iff it recurs and applies to the given currency at the given date
public
getRecurring(int $coupon_id, string $currency, string $date) : mixed
Parameters
- $coupon_id : int
-
The ID of the coupon to fetch
- $currency : string
-
The ISO 4217 currency code
- $date : string
-
The date at which to check that the coupon will apply
Return values
mixed —An stdClass object representing the coupon and the recurring amount, or false otherwise
incrementUsage()
Increments the used quantity on the given coupon
public
incrementUsage(int $coupon_id) : mixed
Parameters
- $coupon_id : int
-
The ID of the coupon whose used quantity to increment
validateAmountDuplicates()
Validates an array of coupon discounts to check for duplicate currencies.
public
validateAmountDuplicates(array<string|int, mixed> $vars) : bool
Parameters
- $vars : array<string|int, mixed>
-
An indexed array of discount options including:
- currency The currency code as defined in ISO 4217
- type The type of discount ("amount" or "percent")
- amount The numeric amount of this discount
Return values
bool —True if each currency is unique, false otherwise
validateAmountType()
Validates a coupon amount's 'type' field
public
validateAmountType(string $type) : bool
Parameters
- $type : string
-
The type to check
Return values
bool —True if validated, false otherwise
validateStatus()
Validates a coupon's 'status' field
public
validateStatus(string $status) : bool
Parameters
- $status : string
-
The status to check
Return values
bool —True if validated, false otherwise
validateUniqueCode()
Validates whether the given coupon code is currently in use
public
validateUniqueCode(string $coupon_code[, mixed $coupon_id = null ]) : bool
Parameters
- $coupon_code : string
-
The coupon code to validate
- $coupon_id : mixed = null
-
The ID of the coupon the given coupon code must represent, or null to not require any
Return values
bool —True if the given coupon code is unique, or false otherwise
getAmounts()
Retrieves all packages associated with a given coupon
private
getAmounts(int $coupon_id) : array<string|int, mixed>
Parameters
- $coupon_id : int
-
The coupon ID
Return values
array<string|int, mixed> —An array of stdClass object representing coupon pricing
getCoupons()
Partially constructs the query required by both Coupons::getList() and Coupons::getListCount()
private
getCoupons(int $company_id[, array<string|int, mixed> $filters = [] ]) : Record
Parameters
- $company_id : int
-
The company ID to fetch coupons for
- $filters : array<string|int, mixed> = []
-
A list of parameters to filter by, including:
- code The (partial) code of the coupon
- discount_type The type of discount for which to filter coupons
- currency The currency for which to filter coupons
- active Filter coupons depending on whether or not they are active
- internal Filter coupons depending on whether or not they are internal coupons
- package_group The package group on which to filter coupons
Return values
Record —The partially constructed query Record object
getPackages()
Retrieves all packages associated with a given coupon
private
getPackages(int $coupon_id) : array<string|int, mixed>
Parameters
- $coupon_id : int
-
The coupon ID
Return values
array<string|int, mixed> —An array of stdClass object representing package IDs
getRules()
Returns the rule set for adding/editing coupons
private
getRules(array<string|int, mixed> $vars[, bool $edit = false ]) : array<string|int, mixed>
Parameters
- $vars : array<string|int, mixed>
-
A list of input vars
- $edit : bool = false
-
True to get the edit rules, false for the add rules
Return values
array<string|int, mixed> —Coupon rules