\MS_Model_Relationship

Subscription model (former "Membership Relationship").

The Subscription defines which user has access to which membership and for how long. Do not confuse this with an invoice - a single subscription can have multiple invoices!

Note that all properties are declared protected but they can be access directly (e.g. $membership->type to get the type value). There are magic methods __get() and __set() that do some validation before accessing the properties.

Summary

Methods
Properties
Constants
get_post_type()
sort_by_priority()
cancel_membership()
deactivate_membership()
save()
is_trial_eligible()
is_expired()
has_trial()
set_start_date()
set_trial_expire_date()
set_expire_date()
get_current_period()
get_remaining_trial_period()
get_remaining_period()
get_member()
get_current_invoice()
get_next_invoice()
get_previous_invoice()
get_invoices()
first_unpaid_invoice()
get_membership()
is_base()
is_guest()
is_user()
is_system()
get_gateway()
set_custom_data()
delete_custom_data()
get_custom_data()
get_payment_description()
add_payment()
get_payments()
status_text()
get_status_description()
No public properties found
STATUS_PENDING
STATUS_WAITING
STATUS_ACTIVE
STATUS_TRIAL
STATUS_CANCELED
STATUS_TRIAL_EXPIRED
STATUS_EXPIRED
STATUS_DEACTIVATED
No protected methods found
$membership_id
$gateway_id
$start_date
$expire_date
$trial_expire_date
$trial_period_completed
$status
$current_invoice_number
$payments
$payment_type
N/A
No private methods found
$membership
N/A

Constants

STATUS_PENDING

STATUS_PENDING

Membership Relationship Status constants.

Pending is the first status that means the member did not confirm his intention to complete his payment/registration.

NO ACCESS.

STATUS_WAITING

STATUS_WAITING

Membership Relationship Status constants.

This status has a much higher value than PENDING, because it means that the member already made a payment, but the subscription is not yet activated because the start date was not reached.

NO ACCESS.

STATUS_ACTIVE

STATUS_ACTIVE

Membership Relationship Status constants.

FULL ACCESS TO MEMBERSHIP CONTENTS.

STATUS_TRIAL

STATUS_TRIAL

Membership Relationship Status constants.

FULL ACCESS TO MEMBERSHIP CONTENTS.

STATUS_CANCELED

STATUS_CANCELED

Membership Relationship Status constants.

User cancelled his subscription but the end date of the current payment period is not reached yet. The user has full access to the membership contents until the end date is reached.

FULL ACCESS TO MEMBERSHIP CONTENTS.

STATUS_TRIAL_EXPIRED

STATUS_TRIAL_EXPIRED

Membership Relationship Status constants.

NO ACCESS.

STATUS_EXPIRED

STATUS_EXPIRED

Membership Relationship Status constants.

End-Date reached. The subscription is available for renewal for a few more days.

NO ACCESS.

STATUS_DEACTIVATED

STATUS_DEACTIVATED

Membership Relationship Status constants.

Deactivated means, that we're completely done with this subscription. It's not displayed for renewal and the member can be set to inactive now.

NO ACCESS.

Properties

$membership_id

$membership_id : string

The Membership ID.

Type

string

$gateway_id

$gateway_id : string

The Payment Gateway ID.

Type

string

$start_date

$start_date : string

The start date of the membership relationship.

Type

string

$expire_date

$expire_date : string

The expire date of the membership relationship.

Type

string

$trial_expire_date

$trial_expire_date : string

The trial expire date of the membership relationship.

Type

string

$trial_period_completed

$trial_period_completed : string

Trial period completed flag.

Indicates if already used a trial period and can't have another trial period.

Type

string

$status

$status : string

The status of the membership relationship.

Type

string

$current_invoice_number

$current_invoice_number : 

Current invoice count.

This is NOT the public invoice-number but an counter to determine how many invoices were generated for this subscription already.

Type

$payments

$payments : array

The number of successful payments that were made for this subscription.

We use this value to determine the end of a recurring payment plan. Also this information is displayed in the member-info popup (only for admins; see MS_View_Member_Dialog)

Type

array — { A list of all payments that were made [since 1.1.0] string $date Payment date/time. number $amount Payment-Amount. string $gateway Gateway that confirmed payment. }

$payment_type

$payment_type : string

The payment type that this subscription was created with.

Since the user can change the payment_type of the membership any time we might end up with a subscription with an invalid expire date.

This flag allows us to detect changes in the parent membership payment options so we can update this membership accordingly.

Type

string

$membership

$membership : \MS_Model_Membership

The related membership model object.

Type

\MS_Model_Membership

Methods

get_post_type()

get_post_type() : string

Returns the post-type of the current object.

Returns

string —

The post-type name.

sort_by_priority()

sort_by_priority(\MS_Model_Relationship  $a, \MS_Model_Relationship  $b) : integer

Sort function used as second param by `uasort()` to sort a subscription list by membership priority.

Memberships with equal priority are sorted alphabeically.

Parameters

\MS_Model_Relationship $a
\MS_Model_Relationship $b

Returns

integer —

-1: a < b | 0: a = b | +1: a > b

cancel_membership()

cancel_membership(boolean  $generate_event = true) 

Cancel membership.

Parameters

boolean $generate_event

Optional. Defines if cancel events are generated.

deactivate_membership()

deactivate_membership() 

Deactivate membership.

Cancel membership and move to deactivated state.

save()

save() 

Save model.

Only saves if is not admin user and not a visitor. Don't save automatically assigned visitor/system memberships.

is_trial_eligible()

is_trial_eligible() : boolean

Verify if the member can use the trial period.

It returns FALSE if .. Trial Add-on is disabled .. The membership does not allow a trial period .. The current user already consumed trial period or is in trial period

Returns

boolean —

True if trial eligible.

is_expired()

is_expired() : boolean

Returns true if the current subscription is expired.

Returns

boolean

has_trial()

has_trial() : boolean

Checks if the current subscription consumes a trial period.

When the subscription either is currently in trial or was in trial before then this function returns true. If the subscription never was in trial status it returns false.

Returns

boolean

set_start_date()

set_start_date(string  $start_date = null) 

Set Membership Relationship start date.

Parameters

string $start_date

Optional. The start date to set. Default will be calculated/current date.

set_trial_expire_date()

set_trial_expire_date(string  $trial_expire_date = null) 

Set trial expire date.

Validate to a date greater than start date.

Parameters

string $trial_expire_date

Optional. The trial expire date to set. Default will be calculated based on start_date.

set_expire_date()

set_expire_date(string  $expire_date = null) 

Set trial expire date.

Validate to a date greater than start date and trial expire date.

Parameters

string $expire_date

Optional. The expire date to set. Default will be calculated based on start_date.

get_current_period()

get_current_period() : integer

Returns the number of days since the subscription started.

Example: If the start_date is 14 days ago it will return the value 14.

Returns

integer —

Remaining days.

get_remaining_trial_period()

get_remaining_trial_period() : integer

Returns the number of days until trial period ends.

Returns

integer —

Remaining days.

get_remaining_period()

get_remaining_period() : integer

Get number of days until this membership expires.

Returns

integer —

Remaining days.

get_member()

get_member() : \MS_Model_Member

Get Member model of the subscription owner.

Returns

\MS_Model_Member

The member object.

get_current_invoice()

get_current_invoice(  $create_missing = true) : \MS_Model_Invoice

Convenience function to access current invoice for this subscription.

Parameters

$create_missing

Returns

\MS_Model_Invoice

get_next_invoice()

get_next_invoice(  $create_missing = true) : \MS_Model_Invoice

Convenience function to access next invoice for this subscription.

Parameters

$create_missing

Returns

\MS_Model_Invoice

get_previous_invoice()

get_previous_invoice(  $status = null) : \MS_Model_Invoice

Convenience function to access previous invoice for this subscription.

Parameters

$status

Returns

\MS_Model_Invoice

get_invoices()

get_invoices() : array<mixed,\MS_Model_Invoice>

Get a list of all invoices linked to this relationship

Returns

array<mixed,\MS_Model_Invoice> —

List of invoices.

first_unpaid_invoice()

first_unpaid_invoice() : integer

Finds the first unpaid invoice of the current subscription and returns the invoice_id.

If the subscription has no unpaid invoices then a new invoice is created!

Returns

integer —

The first invoice that is not paid yet.

get_membership()

get_membership() : \MS_Model_Membership

Get related Membership model.

Returns

\MS_Model_Membership

The membership model.

is_base()

is_base() : boolean

Returns true if the related membership is the base-membership.

Returns

boolean

is_guest()

is_guest() : boolean

Returns true if the related membership is the guest-membership.

Returns

boolean

is_user()

is_user() : boolean

Returns true if the related membership is the user-membership.

Returns

boolean

is_system()

is_system() : boolean

Returns true if the related membership is a system membership.

Returns

boolean

get_gateway()

get_gateway() : \MS_Model_Gateway

Get related gateway model.

Returns

\MS_Model_Gateway

set_custom_data()

set_custom_data(string  $key, mixed  $value) 

Either creates or updates the value of a custom data field.

Note: Remember to prefix the $key with a unique string to prevent conflicts with other plugins that also use this function.

Parameters

string $key

The field-key.

mixed $value

The new value to assign to the field.

delete_custom_data()

delete_custom_data(string  $key) 

Removes a custom data field from this object.

Parameters

string $key

The field-key.

get_custom_data()

get_custom_data(string  $key) : mixed

Returns the value of a custom data field.

Parameters

string $key

The field-key.

Returns

mixed —

The value that was previously assigned to the custom field or false if no value was set for the field.

get_payment_description()

get_payment_description(\MS_Model_Invoice  $invoice = null, boolean  $short = false) : string

Get textual payment information description.

Parameters

\MS_Model_Invoice $invoice

Optional. Specific invoice that defines the price. Default is the price defined in the membership.

boolean $short

Optional. Default is false. If set to true then a hort sumary is returned

Returns

string —

The description.

add_payment()

add_payment(float  $amount, string  $gateway, string  $external_id = '') : boolean

Saves information on a payment that was made.

This function also extends the expire_date for one period if the membership payment-type is recurring or limited

Parameters

float $amount

The payment amount. Set to 0 for free subscriptions.

string $gateway

The payment gateway-ID.

string $external_id

A string that can identify the payment.

Returns

boolean —

True if the subscription has ACTIVE status after payment. If the amount was 0 and membership uses a trial period the status could also be TRIAL, in which case the returnv alue is false.

get_payments()

get_payments() : array

Returns a sanitized list of all payments.

Returns

array

status_text()

status_text() : string

Returns an i18n translated version of the subscription status.

Returns

string

get_status_description()

get_status_description() : string

Get a detailled status description.

Returns

string —

The status description.