# \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()
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()
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

File
  model/class-ms-model-relationship.php
Package
  Membership2\Model
Class hierarchy
  \MS_Model_CustomPostType
  \MS_Model_Relationship

## Tags

since |

## 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.

#

See also
  $status property.

## Tags

since |

### 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.

#

See also
  $status property.

## Tags

since |

### STATUS_ACTIVE

    STATUS_ACTIVE

Membership Relationship Status constants.

FULL ACCESS TO MEMBERSHIP CONTENTS.

#

See also
  $status property.

## Tags

since |

### STATUS_TRIAL

    STATUS_TRIAL

Membership Relationship Status constants.

FULL ACCESS TO MEMBERSHIP CONTENTS.

#

See also
  $status property.

## Tags

since |

### 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.

#

See also
  $status property.

## Tags

since |

### STATUS_TRIAL_EXPIRED

    STATUS_TRIAL_EXPIRED

Membership Relationship Status constants.

NO ACCESS.

#

See also
  $status property.

## Tags

since |

### STATUS_EXPIRED

    STATUS_EXPIRED

Membership Relationship Status constants.

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

NO ACCESS.

#

See also
  $status property.

## Tags

since |

### 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.

#

See also
  $status property.

## Tags

since |

## Properties

### $membership_id

    $membership_id : string

The Membership ID.

#### Type

string

#

## Tags

since |

### $gateway_id

    $gateway_id : string

The Payment Gateway ID.

#### Type

string

#

## Tags

since |

### $start_date

    $start_date : string

The start date of the membership relationship.

#### Type

string

#

## Tags

since |

### $expire_date

    $expire_date : string

The expire date of the membership relationship.

#### Type

string

#

## Tags

since |

### $trial_expire_date

    $trial_expire_date : string

The trial expire date of the membership relationship.

#### Type

string

#

## Tags

since |

### $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

#

## Tags

since |

### $status

    $status : string

The status of the membership relationship.

#### Type

string

#

## Tags

since |

### $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

#

## Tags

since |

### $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. }

#

## Tags

since |

### $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

#

## Tags

since |

### $membership

    $membership : \MS_Model_Membership

The related membership model object.

#### Type

\MS_Model_Membership

#

## Tags

since |

## Methods

### get_post_type()

    get_post_type() : string

Returns the post-type of the current object.

#### Returns

string —

The post-type name.

#

static

## Tags

since | 1.0.0
api |

### 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

#

static

## Tags

since | 1.0.1.0

### cancel_membership()

    cancel_membership(boolean  $generate_event = true)

Cancel membership.

#### Parameters

boolean | $generate_event | Optional. Defines if cancel events are generated.

#

## Tags

since | 1.0.0
api |

### deactivate_membership()

    deactivate_membership()

Deactivate membership.

Cancel membership and move to deactivated state.

#

## Tags

since | 1.0.0
api |

### save()

    save()

Save model.

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

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### is_expired()

    is_expired() : boolean

Returns true if the current subscription is expired.

#### Returns

boolean

#

## Tags

since | 1.0.1.0

### 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

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### get_remaining_trial_period()

    get_remaining_trial_period() : integer

Returns the number of days until trial period ends.

#### Returns

integer —

Remaining days.

#

## Tags

since | 1.0.0
api |

### get_remaining_period()

    get_remaining_period() : integer

Get number of days until this membership expires.

#### Returns

integer —

Remaining days.

#

## Tags

since | 1.0.0
api |

### get_member()

    get_member() : \MS_Model_Member

Get Member model of the subscription owner.

#### Returns

\MS_Model_Member —

The member object.

#

## Tags

since | 1.0.0
api |

### 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

#

## Tags

since | 1.0.0
api |

### 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

#

## Tags

since | 1.0.0
api |

### 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

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### get_membership()

    get_membership() : \MS_Model_Membership

Get related Membership model.

#### Returns

\MS_Model_Membership —

The membership model.

#

## Tags

since | 1.0.0
api |

### is_base()

    is_base() : boolean

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

#### Returns

boolean

#

## Tags

since | 1.0.0
api |

### is_guest()

    is_guest() : boolean

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

#### Returns

boolean

#

## Tags

since | 1.0.0
api |

### is_user()

    is_user() : boolean

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

#### Returns

boolean

#

## Tags

since | 1.0.0
api |

### is_system()

    is_system() : boolean

Returns true if the related membership is a system membership.

#### Returns

boolean

#

## Tags

since | 1.0.0
api |

### get_gateway()

    get_gateway() : \MS_Model_Gateway

Get related gateway model.

#### Returns

\MS_Model_Gateway

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### delete_custom_data()

    delete_custom_data(string  $key)

Removes a custom data field from this object.

#### Parameters

string | $key | The field-key.

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### 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.

#

## Tags

since | 1.0.0
api |

### add_payment()

    add_payment(float  $amount, string  $gateway) : 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.

#### 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.

#

## Tags

since | 1.0.0
api |

### status_text()

    status_text() : string

Returns an i18n translated version of the subscription status.

#### Returns

string

#

## Tags

since | 1.0.0
api |

### get_status_description()

    get_status_description() : string

Get a detailled status description.

#### Returns

string —

The status description.

#

## Tags

since | 1.0.0
api |

### class-ms-model-relationship.php