Documentation

Coupon
in package

cloudrexx

module

shop

Coupon

Manages and processes coupon codes for various kinds of discounts

Constants

USES_UNLIMITED = 10000000000.0

Properties

$code : string: The Coupon code
$customer_id : int: The Customer ID for which the Coupon is valid
$discount_amount : float: The discount amount
$discount_rate : float: The discount rate
$end_time : int: The validity period end time in time() format
$global : bool: If true, the Coupon is globally valid for any registered or non-registered Customer
$hasMessage : array<string|int, mixed>: This ensures that only one error message per type is shown
$minimum_amount : float: The minimum amount for which this Coupon is applicable
$payment_id : int: The Payment ID to which this Coupon applies
$product_id : int: The Product ID to which this Coupon applies
$start_time : int: The validity period start time in time() format
$used : int: The number of times the code has been used with an Order
$uses : int: The number of uses available

Methods

available() : Coupon: Verifies the coupon code and returns the first matching one
code() : string: Get or set the Coupon code
codeExists() : bool: Returns true if the given code does not exist in the database
count_available() : int: Returns the number of Coupons defined
customer_id() : int: Get or set the Customer ID
discount_amount() : float: Get or set the discount amount
discount_rate() : float: Get or set the discount rate
edit() : mixed: Edit coupons
end_time() : int: Get or set the end time
errorHandler() : bool: Tries to fix any database related problems
get() : Coupon: Returns the Coupon for the given code
getArray() : array<string|int, mixed>: Get coupon information from the database
getByOrderId() : Coupon: Returns the Coupon that was used with the Order with the given ID
getDiscountAmount() : string: Returns the discount amount resulting from applying this Coupon
getIndex() : string: Returns the index for this Coupon
getNewCode() : string: Returns a unique Coupon code with eight characters
getString() : string: Returns a textual representation for the discount provided by this Coupon
getTotalAmountString() : sting: Returns a formatted string indicating the given amount as discounted due to the use of coupon codes
getUsedAmount() : mixed: Returns the discount amount used with this Coupon
is_global() : bool: Get or set the global flag
minimum_amount() : float: Get or set the minimum amount
payment_id() : int: Get or set the Payment ID
product_id() : int: Get or set the Product ID
recordExists() : bool: Returns true if the Coupon with the given index does not exist in the database
redeem() : Coupon: Redeem the given coupon code
start_time() : int: Get or set the start time
storeCode() : bool: Stores a coupon code in the database
used() : int: Get the number of times the code has been used
uses() : int: Get or set the uses available
hasMessage() : bool: This ensures that for every message type, only the first one is shown
delete() : bool: Deletes the Coupon with the given code from the database
getUsedCount() : mixed: Returns the count of the uses for the given code

USES_UNLIMITED


    public
        mixed
    USES_UNLIMITED
    = 10000000000.0

$code

The Coupon code


        protected
            string
    $code
     = ''

$customer_id

The Customer ID for which the Coupon is valid


        protected
            int
    $customer_id
     = 0

If empty, it is valid for all Customers

$discount_amount

The discount amount


        protected
            float
    $discount_amount
     = 0

If this is non-empty, the discount rate MUST be zero.

$discount_rate

The discount rate


        protected
            float
    $discount_rate
     = 0

If this is non-empty, the discount amount MUST be zero.

$end_time

The validity period end time in time() format


        protected
            int
    $end_time
     = 0

$global

If true, the Coupon is globally valid for any registered or non-registered Customer


        protected
            bool
    $global
     = true

$hasMessage

This ensures that only one error message per type is shown


        protected
        static    array<string|int, mixed>
    $hasMessage
     = array()

$minimum_amount

The minimum amount for which this Coupon is applicable


        protected
            float
    $minimum_amount
     = 0

Includes the Product prices only, possibly already discounted

$payment_id

The Payment ID to which this Coupon applies


        protected
            int
    $payment_id
     = 0

If non-empty, it only applies when the corresponding Payment is selected

$product_id

The Product ID to which this Coupon applies


        protected
            int
    $product_id
     = 0

If empty, it does not apply to any Product in particular, but to any Product in the order.

$start_time

The validity period start time in time() format


        protected
            int
    $start_time
     = 0

$used

The number of times the code has been used with an Order


        protected
            int
    $used
     = null

This is always initialized to the correct value for the customer, if applicable.

$uses

The number of uses available


        protected
            int
    $uses
     = 1

This is always initialized to the correct value for any customer, if applicable. Notes:

For general per-customer Coupons, this value never changes. You have to subtract the number of times it has been used by each Customer.
For personal Customer Coupons and global Coupons, it is decremented on each use.

available()

Verifies the coupon code and returns the first matching one


    public
            static        available(string $code, float $order_amount[, int $customer_id = null ][, int $product_id = null ][, int $payment_id = null ]) : Coupon

If the code is valid, returns the Coupon. If the code is unknown, or limited and already exhausted, returns false. Also note that no counter is changed upon verification; to update a coupon after use see redeem(). Use getByOrderId() to get a (used) Coupon that was used in conjunction with any partivcular Order, without any verification.

Parameters

$code : string: The coupon code
$order_amount : float: The order amount
$customer_id : int = null: The Customer ID
$product_id : int = null: The Product ID
$payment_id : int = null: The Payment ID

Return values

Coupon —

The matching Coupon on success, false on error, or null otherwise

code()

Get or set the Coupon code


    public
                    code([string $code = null ]) : string

Parameters

$code : string = null: The optional new Coupon code

Return values

string —

The Coupon code

codeExists()

Returns true if the given code does not exist in the database


    public
            static        codeExists(string $code) : bool

Upon failure, true is returned in order to prevent overwriting the potentially existing record.

Parameters

$code : string: The code

Return values

bool —

True if the record exists or on failure, false otherwise

count_available()

Returns the number of Coupons defined


    public
            static        count_available() : int

Return values

int —

The number of Coupons

customer_id()

Get or set the Customer ID


    public
                    customer_id([int $customer_id = null ]) : int

Parameters

$customer_id : int = null: The optional Customer ID

Return values

int —

The Customer ID

discount_amount()

Get or set the discount amount


    public
                    discount_amount([float $discount_amount = null ]) : float

Parameters

$discount_amount : float = null: The optional discount amount

Return values

float —

The discount amount

discount_rate()

Get or set the discount rate


    public
                    discount_rate([float $discount_rate = null ]) : float

Parameters

$discount_rate : float = null: The optional discount rate

Return values

float —

The discount rate

edit()

Edit coupons


    public
            static        edit(Sigma $objTemplate) : mixed

Parameters

$objTemplate : Sigma: The Template

end_time()

Get or set the end time


    public
                    end_time([int $end_time = null ]) : int

Parameters

$end_time : int = null: The optional end time

Return values

int —

The end time

errorHandler()

Tries to fix any database related problems


    public
            static        errorHandler() : bool

Return values

bool —

false Always!

get()

Returns the Coupon for the given code


    public
            static        get(string $code) : Coupon

If the code is unknown, returns null. On failure returns false. Does not deduct any counts or amounts already used. Use available() to see whether a Customer may still use a given code. Use getByOrderId() to get a Coupon that was used in conjunction with any particular Order ID.

Parameters

$code : string: The coupon code

Return values

Coupon —

The matching Coupon on success, false on error, or null otherwise

getArray()

Get coupon information from the database


    public
            static        getArray([int $offset = 0 ][, int $limit = 0 ][, int &$count = 0 ][, string $order = '' ]) : array<string|int, mixed>

The array returned looks like array( 'code-payment_id' => array( code => The Coupon code, minimum_amount => The minimum amount for which the coupon is valid, discount_rate => The discount rate, discount_amount => The discount amount, start_time => The validity period start time, end_time => The validity period end time, uses => The available number of uses, global => Flag for globally available coupons, customer_id => The Customer ID, product_id => The Product ID, payment_id => The Payment ID, ), ... more ... )

Parameters

$offset : int = 0: The offset. Defaults to zero
$limit : int = 0: The limit. Defaults to 30.
$count : int = 0: By reference. Contains the actual number of total records on successful return
$order : string = '': The sorting order. Defaults to 'end_time DESC'

Return values

array<string|int, mixed> —

The array of coupon data

getByOrderId()

Returns the Coupon that was used with the Order with the given ID


    public
            static        getByOrderId(int $order_id) : Coupon

If a Coupon was used for that Order, returns it. Returns false on error, null otherwise (if there is none). Fails if either the Order or the Customer cannot be found, or if a query fails.

Parameters

$order_id : int: The Order ID

Return values

Coupon —

The matching Coupon on success, false on error, or null otherwise

getDiscountAmount()

Returns the discount amount resulting from applying this Coupon


    public
                    getDiscountAmount(float $amount[, int $customer_id = NULL ]) : string

This Coupon may contain either a discount rate or amount. The rate has precedence and is thus applied in case both are set (although this should never happen). If neither is greater than zero, returns 0 (zero). This also should never happen. If the Coupon has an amount, the sum of all previous redemptions is subtracted first, and the remainder is returned. Note that the value returned is never greater than $amount.

Parameters

$amount : float: The amount
$customer_id : int = NULL: The Customer ID

Return values

string —

The applicable discount amount

getIndex()

Returns the index for this Coupon


    public
                    getIndex() : string

Returns NULL iff the code is empty

Return values

string —

The Coupon index

getNewCode()

Returns a unique Coupon code with eight characters


    public
            static        getNewCode() : string

Return values

string —

The Coupon code

getString()

Returns a textual representation for the discount provided by this Coupon


    public
                    getString([float $discount_amount = 0 ]) : string

Set the $discount_amount if it is different from the value returned by discount_amount(), i.e. when the total discount amount reaches the amount available for this Coupon

Parameters

$discount_amount : float = 0: The optional discount amount

Return values

string

getTotalAmountString()

Returns a formatted string indicating the given amount as discounted due to the use of coupon codes


    public
            static        getTotalAmountString(float $amount) : sting

Parameters

$amount : float: The amount

Return values

sting —

The formatted string

getUsedAmount()

Returns the discount amount used with this Coupon


    public
                    getUsedAmount([int $customer_id = NULL ][, int $order_id = NULL ]) : mixed

The optional $customer_id and $order_id limit the result to the uses of that Customer and Order. Returns 0 (zero) for Coupons that have not been used with the given parameters, and thus are not present in the relation.

Parameters

$customer_id : int = NULL: The optional Customer ID
$order_id : int = NULL: The optional Order ID

Return values

mixed —

The amount used with this Coupon on success, false otherwise

is_global()

Get or set the global flag


    public
                    is_global([bool $global = null ]) : bool

Parameters

$global : bool = null: The optional global flag

Return values

bool —

The global flag

minimum_amount()

Get or set the minimum amount


    public
                    minimum_amount([float $minimum_amount = null ]) : float

Parameters

$minimum_amount : float = null: The optional minimum amount

Return values

float —

The minimum amount

payment_id()

Get or set the Payment ID


    public
                    payment_id([int $payment_id = null ]) : int

Parameters

$payment_id : int = null: The optional Payment ID

Return values

int —

The Payment ID

product_id()

Get or set the Product ID


    public
                    product_id([int $product_id = null ]) : int

Parameters

$product_id : int = null: The optional Product ID

Return values

int —

The Product ID

recordExists()

Returns true if the Coupon with the given index does not exist in the database


    public
            static        recordExists(string $index) : bool

Upon failure, true is returned in order to prevent overwriting the potentially existing record.

Parameters

$index : string: The Coupon index

Return values

bool —

True if the record exists or on failure, false otherwise

redeem()

Redeem the given coupon code


    public
                    redeem(int $order_id, int $customer_id, float $amount[, int $uses = 1 ]) : Coupon

Updates the database, if applicable. Mind that you MUST decide which amount (Order or Product) to provide:

the Product amount if the Coupon has a non-empty Product ID, or
the Order amount otherwise Provide a zero $uses count (but not null!) when you are storing the Order. Omit it, or set it to 1 (one) when the Order is complete. The latter is usually the case on the success page, after the Customer has returned to the Shop after paying. Mind that the amount cannot be changed once the record has been created, so only the use count will ever be updated. $uses is never interpreted as anything other than 0 or 1!

Parameters

$order_id : int: The Order ID
$customer_id : int: The Customer ID
$amount : float: The Order- or the Product amount (if $this->product_id is non-empty)
$uses : int = 1: The redeem count. Set to 0 (zero) when storing the Order, omit or set to 1 (one) when redeeming Defaults to 1.

Return values

Coupon —

The Coupon on success, false otherwise

start_time()

Get or set the start time


    public
                    start_time([int $start_time = null ]) : int

Parameters

$start_time : int = null: The optional start time

Return values

int —

The start time

storeCode()

Stores a coupon code in the database


    public
            static        storeCode(string $code[, mixed $payment_id = 0 ][, mixed $minimum_amount = 0 ][, float $discount_rate = 0 ][, float $discount_amount = 0 ][, int $start_time = 0 ][, int $end_time = 0 ][, int $uses = 0 ][, bool $global = true ][, int $customer_id = 0 ][, mixed $product_id = 0 ][, string $index = NULL ]) : bool

Returns true on success. The code must be unique; existing records are updated. Either $discount_rate or $discount_amount must be non-empty, but not both. Any empty, non-integer, or non-positive values for $start_time, $end_time, and $customer_id are ignored, and the corresponding field is set to zero. Adding a code with $uses zero is pointless, as it can never be used.

Parameters

$code : string: The code
$payment_id : mixed = 0
$minimum_amount : mixed = 0
$discount_rate : float = 0: The discount rate in percent
$discount_amount : float = 0: The discount amount in default Currency
$start_time : int = 0: The optional start time in time() format
$end_time : int = 0: The optional end time in time() format
$uses : int = 0: The available number of uses
$global : bool = true: If false, the code is valid on a per customer basis. Defaults to true
$customer_id : int = 0: The optional customer ID
$product_id : mixed = 0
$index : string = NULL: The optional Coupon index

Return values

bool —

True on success, false otherwise

used()

Get the number of times the code has been used


    public
                    used() : int

Return values

int —

The number of uses made

uses()

Get or set the uses available


    public
                    uses([int $uses = null ]) : int

Parameters

$uses : int = null: The optional uses available

Return values

int —

The uses available

hasMessage()

This ensures that for every message type, only the first one is shown


    protected
            static        hasMessage(string $type) : bool

Parameters

$type : string: Type name

Return values

bool —

Whether we already had such a message or not

delete()

Deletes the Coupon with the given code from the database


    private
            static        delete(int $code[, mixed $customer_id = NULL ]) : bool

When set, limits deleting to the given Customer ID. On failure, adds an error message and returns false.

Parameters

$code : int: The optional Customer ID
$customer_id : mixed = NULL

Return values

bool —

True on success, false otherwise

getUsedCount()

Returns the count of the uses for the given code


    private
                    getUsedCount([int $customer_id = 0 ]) : mixed

The optional $customer_id limits the result to the uses of that Customer. Returns 0 (zero) for codes not present in the relation (yet).

Parameters

$customer_id : int = 0: The optional Customer ID

Return values

mixed —

The number of uses of the code on success, false otherwise

Coupon in package cloudrexx module shop

Tags

Table of Contents

Constants

Properties

Methods

Constants

USES_UNLIMITED

Properties

$code

$customer_id

$discount_amount

$discount_rate

$end_time

$global

$hasMessage

$minimum_amount

$payment_id

$product_id

$start_time

$used

$uses

Methods

available()

Parameters

Tags

Return values

code()

Parameters

Return values

codeExists()

Parameters

Return values

count_available()

Tags

Return values

customer_id()

Parameters

Return values

discount_amount()

Parameters

Return values

discount_rate()

Parameters

Return values

edit()

Parameters

end_time()

Parameters

Return values

errorHandler()

Tags

Return values

get()

Parameters

Tags

Return values

getArray()

Parameters

Tags

Return values

getByOrderId()

Parameters

Tags

Return values

getDiscountAmount()

Parameters

Return values

getIndex()

Return values

getNewCode()

Tags

Return values

getString()

Parameters

Return values

getTotalAmountString()

Parameters

Return values

getUsedAmount()

Coupon
in package

cloudrexx

module

shop