Blesta Source Documentation

Services extends AppModel

Service management

Table of Contents

Methods

__construct() Initialize Services
add() Adds a new service to the system
addField() Adds a service field for a particular service
buildServiceCouponLineItems() Retrieves a list of coupons to be applied to an invoice for services, assuming the services given are for a single client only
cancel() Schedule a service for cancellation. All cancellations requests are processed by the cron.
canSyncToParent() Determines if a service should be prorated to match its parent
decrementQuantity() Decrements the package quantity if $check_only is false, otherwise only validates the quantity could be decremented.
delete() Permanently deletes a pending service from the system
edit() Edits a service. Only one module action may be performend at a time. For example, you can't change the pricing_id and edit the module service fields in a single request.
editField() Edit a service field for a particular service
get() Fetch a single service, including service field data
getActions() Returns all action options that can be performed for a service.
getAll() Returns a list of services for the given client and status
getAllByClient() Returns a list of services for the given client and status unpaged
getAllChildren() Retrieves a list of all services that are child of the given parent service ID
getAllChildrenCount() Retrieves the total number of add-on/children services for the given parent service ID
getAllPaidPending() Retrieves a list of paid pending services
getAllPendingCancelation() Retrieves a list of services ready to be canceled
getAllPendingSuspension() Retrieves a list of services ready to be suspended
getAllPendingUnsuspension() Retrieves a list of paid suspended services ready to be unsuspended. Will only return services that were automatically suspended (not manually suspended by a staff member).
getAllRenewablePaid() Retrieves all renewable paid services
getAllRenewableUnpaid() Retrieves all renewable paid services
getAllRenewing() Retrieves a list of services ready to be renewed for this client group
getChildRenewDate() Determines the date a service should be prorated to so it matches its parent
getDataPresenter() Retrieves a presenter representing a set of items, discounts, and taxes for service data
getFieldRules() Retrieves the rule set for adding/editing service fields
getList() Returns a list of services for the given client and status
getListCount() Returns the total number of services for a client, useful in constructing pagination for the getList() method.
getNextInvoiceDate() Retrieves the date on which the next invoice is expected to be generated for a service
getNextRenewDate() Calculates the next renew date using a given date, term, and period
getOptions() Returns the configurable options for the service
getPackagePricing() Get package pricing
getPendingCancelationCount() Retrieves a count of pending cancelation services
getPendingCancelationList() Retrieves a list of pending cancelation services
getPendingCancelationQuery() Retrieves a list of services ready to be canceled
getPendingPaidCount() Retrieves a count of pending paid services
getPendingPaidList() Retrieves a list of pending paid services
getPendingPaidQuery() Retrieves a list of paid pending services
getPendingSuspensionCount() Retrieves a count of pending suspension services
getPendingSuspensionList() Retrieves a list of pending suspension services
getPendingSuspensionQuery() Retrieves a query of services ready to be suspended
getPendingUnsuspensionCount() Retrieves a count of pending unsuspension services
getPendingUnsuspensionList() Retrieves a list of pending unsuspension services
getPendingUnsuspensionQuery() Retrieves a list of paid suspended services ready to be unsuspended. Will only return services that were automatically suspended (not manually suspended by a staff member).
getPresenter() Retrieves a presenter representing a set of items, discounts, and taxes for the service
getPricingInfo() Fetches the pricing information for a service
getRenewablePaidCount() Retrieves a count of renewable paid services
getRenewablePaidList() Retrieves a list of renewable paid services
getRenewablePaidQuery() Retrieves a query for renewable paid services
getRenewableUnpaidCount() Retrieves a count of renewable paid services
getRenewableUnpaidList() Retrieves a list of renewable paid services
getRenewableUnpaidQuery() Retrieves a query for renewable paid services
getRenewalPrice() Retrieves the next expected renewal price of a service based on its current configuration, options, and pricing
getSearchCount() Return the total number of services returned from Services::search(), useful in constructing pagination
getServiceItems() Gets a list of items based on the service data given and updates line totals accordingly
getSimpleList() Retrieves a list of all services in the system
getStatusCount() Returns the number of results available for the given status
getStatusTypes() Retrieves a list of service status types
getType() Gets the type of the given service
getWelcomeEmailTags() Returns all default welcome email tags, which are set into the email that is delivered when a service is provisioned.
hasChildren() Determines whether a service has any child services of the given status
hasParent() Determines whether a service has a parent services of the given status
incrementServiceAttempt() Increments the attempts to perform an action for a given service
isInstanceOf() Checks if the given $field is a reference of $class
isServiceOptionValueInUse() Determines whether the given option value is currently in use by any non-cancelled service
move() Moves a service to a different client
renew() Processes the renewal for the given service by contacting the module (if supported by the module), to let it know that the service should be renewed. Note: This method does not affect the renew date of the service in Blesta, it merely notifies the module; this action takes place after a service has been paid not when its renew date is bumped.
search() Search services
searchServiceFields() Searches services of the given module that contains the given service field key/value pair.
setFields() Updates the field data for the given service, removing all existing data and replacing it with the given data
suspend() Suspends a service
unCancel() Recreates a previously cancelled service.
unsuspend() Unsuspends a service
validate() Performs all validation necessary before adding a service
validateAllowed() Verifies that the client has access to the package for the given pricing ID
validateConfigOptions() Verifies that the given package options are valid
validateCoupon() Verifies if the given coupon ID can be applied to the requested packages
validateDateCanceled() Verifies that the given date value is valid for a cancel date
validateDateRenews() Verifies that the given renew date is greater than the last renew date (if available)
validateEncrypted() Validates a service field's 'encrypted' field
validateHasChildren() Validates whether the given service has children NOT of the given status
validateOverrideFields() Verifies that the given price and currency fields have been set together
validatePriceOverride() Verifies that the given price override is in a valid format
validatePricingWithOverrides() Verifies that the given service and pricing ID are valid with price overrides
validateService() Validates service info, including module options, for creating a service. An alternative to Services::validate() Sets Input errors on failure
validateServiceEdit() Performs all validation necessary for updating a service. Sets Input errors on failure
validateStatus() Validates a service's 'status' field
validateUseModule() Validates whether to use a module when adding/editing a service
getFields() Return all field data for the given service, decrypting fields where neccessary
addCancelInvoice() Creates an invoice for a client based on the given service being canceled i.e. service cancellation fee
appendServiceInfo() Adds more information to the given service
cancelOnModule() Cancels the given service using its module. Sets Input errors on failure
formatConfigOptions() Formats given config options by removing options with 0 quantity
getConfigurableModuleFields() Returns an array containing the module row and module group from the configurable options
getModuleClassByPricingId() Returns info regarding the module belonging to the given $package_pricing_id
getOptionsAvailable() Fetches all of the package options available for a given pricing
getRelations() Fetches all relations (e.g. packages and services) for the given service ID
getRules() Retrieves the rule set for adding/editing services
getServiceLineItemAmounts() Retrieves a list of line item amounts from the given line items
getServiceOptions() Retrieves a list of package option IDs that can be added/updated to the given service
getServiceOptionsTotal() Retrieves the full total service options cost for the given service
getServices() Partially constructs the query required by Services::getList() and others
getSuspensionAndCancellationTags() Gets a list of tags for the serice suspension and cancellation email
searchServices() Partially constructs the query for searching services
sendCancellationNoticeEmail() Sends the service cancellation email
sendNotificationEmail() Sends a service confirmation email
sendScheduledCancellationNoticeEmail() Sends the service scheduled cancellation email
sendSuspensionNoticeEmail() Sends the service (un)suspension email
setServiceOptions() Updates the service to set all of its service config options
validateEdit() Performs all validation necessary before updating a service
voidInvoices() Any open invoices that contain line items related to the given service will be removed from the invoice, and all payments to it unapplied.
Methods

__construct()

Initialize Services

public __construct() : mixed

add()

Adds a new service to the system

public add(array<string|int, mixed> $vars[, array<string|int, mixed> $packages = null ][, bool $notify = false ]) : int
Parameters
$vars : array<string|int, mixed>

An array of service info including:

  • parent_service_id The ID of the service this service is a child of (optional)
  • package_group_id The ID of the package group this service was added from (optional)
  • pricing_id The package pricing schedule ID for this service
  • client_id The ID of the client to add the service under
  • staff_id The ID of the staff member that added the service
  • module_row_id The module row to add the service under (optional, default module will decide)
  • coupon_id The ID of the coupon used for this service (optional)
  • qty The quantity consumed by this service (optional, default 1)
  • override_price The price to set for this service, overriding the package pricing value for the selected term (optional, default null)
  • override_currency The currency to set for this service, overriding the package pricing value for the selected term (optional, default null)
  • status The status of this service (optional, default 'pending'):
    • active
    • canceled
    • pending
    • suspended
    • in_review
  • suspension_reason The reason a service is being suspended
  • date_added The date this service is added (default to today's date UTC)
  • date_renews The date the service renews (optional, default calculated by package term)
  • date_last_renewed The date the service last renewed (optional)
  • date_paid_through The date the service is paid through (optional)
  • date_suspended The date the service was last suspended (optional)
  • date_canceled The date the service was last canceled (optional)
  • use_module Whether or not to use the module when creating the service ('true','false', default 'true', forced 'false' if status is 'pending' or 'in_review')
  • configoptions An array of key/value pairs of package options where the key is the package option ID and the value is the option value (optional)
    • Any other service field data to pass to the module
$packages : array<string|int, mixed> = null

An array of packages ordered along with this service to determine if the given coupon may be applied given in one of the following formats:

  • A numerically indexed array of package IDs
  • An array of package IDs and pricing IDs [packageID => pricingID]
$notify : bool = false

True to notify the client by email regarding this service creation, false to not send any notification (optional, default false)

Return values
int —

The ID of this service, void if error

addField()

Adds a service field for a particular service

public addField(int $service_id, array<string|int, mixed> $vars) : mixed
Parameters
$service_id : int

The ID of the service to add to

$vars : array<string|int, mixed>

An array of service field info including:

  • key The name of the value to add
  • value The value to add
  • encrypted Whether or not to encrypt the value when storing ('true', 'false', default 'false')

buildServiceCouponLineItems()

Retrieves a list of coupons to be applied to an invoice for services, assuming the services given are for a single client only

public buildServiceCouponLineItems(array<string|int, mixed> $services, string $default_currency, array<string|int, mixed> &$coupons[, bool $services_renew = false ][, array<string|int, mixed> $line_items = [] ]) : array<string|int, mixed>
Parameters
$services : array<string|int, mixed>

An array of stdClass objects, each representing a service

$default_currency : string

The ISO 4217 currency code for the client

$coupons : array<string|int, mixed>

A reference to coupons that will need to be incremented

$services_renew : bool = false

True if all of the given $services are renewing services, or false if all $services are new services (optional, default false)

$line_items : array<string|int, mixed> = []

An array of line items that the coupon will be applying toward (optional but highly recommended):

  • service_id The ID of the service, matching one of the given $services
  • description The line item description
  • qty The line item quantity
  • amount The line item amount
  • tax Whether or not the line item is taxable
  • service_option_id The ID of the service option the line item represents, if any
  • setup_fee Whether or not the line item is a setup fee
  • after_cutoff Whether or not the line item is after the cutoff date
Return values
array<string|int, mixed> —

An array of coupon line items to append to an invoice

cancel()

Schedule a service for cancellation. All cancellations requests are processed by the cron.

public cancel(int $service_id, array<string|int, mixed> $vars) : mixed
Parameters
$service_id : int

The ID of the service to schedule cancellation

$vars : array<string|int, mixed>

An array of service info including:

  • date_canceled The date the service is to be canceled. Possible values:
    • 'end_of_term' Will schedule the service to be canceled at the end of the current term
    • date greater than now will schedule the service to be canceled on that date
    • date less than now will immediately cancel the service
  • use_module Whether or not to use the module when canceling the service, if canceling now ('true','false', default 'true')
  • reapply_payments True or false, default true. When the service is canceled, line items may be removed from related invoice(s). Any payments already applied to these invoices will be unapplied and then reapplied to cover the cost of the remaining line items.
  • notify_cancel 'true' to notify the client by email regarding this service cancellation, 'false' to not send any notification
  • cancellation_reason The reason for the service cancellation

canSyncToParent()

Determines if a service should be prorated to match its parent

public canSyncToParent(stdClass $pricing, stdClass $parent_pricing, int $client_group_id) : bool
Parameters
$pricing : stdClass

The new service pricing

$parent_pricing : stdClass

The parent service pricing

$client_group_id : int

The ID of the client group this service is under

Return values
bool —

Whether to synchronize a service with its parent

decrementQuantity()

Decrements the package quantity if $check_only is false, otherwise only validates the quantity could be decremented.

public decrementQuantity(int $quantity, int $pricing_id[, bool $check_only = true ][, mixed $current_qty = null ]) : bool
Parameters
$quantity : int

The quantity requested

$pricing_id : int

The pricing ID

$check_only : bool = true

True to only verify the quantity could be decremented, false otherwise

$current_qty : mixed = null

The currenty quantity being consumed by the service

Return values
bool —

true if the quantity could be (not necessarily has been) consumed, false otherwise

delete()

Permanently deletes a pending service from the system

public delete(int $service_id[, int $validate = true ]) : mixed
Parameters
$service_id : int

The ID of the pending service to delete

$validate : int = true

True to validate whether the service is capable of being deleted, or false to permanently delete its record regardless (optional, default true)

edit()

Edits a service. Only one module action may be performend at a time. For example, you can't change the pricing_id and edit the module service fields in a single request.

public edit(int $service_id, array<string|int, mixed> $vars[, bool $bypass_module = false ][, bool $notify = false ]) : int
Parameters
$service_id : int

The ID of the service to edit

$vars : array<string|int, mixed>

An array of service info:

  • parent_service_id The ID of the service this service is a child of
  • package_group_id The ID of the package group this service was added from
  • pricing_id The package pricing schedule ID for this service
  • client_id The ID of the client this service belongs to
  • staff_id The ID of the staff member that added the service
  • module_row_id The module row to add the service under
  • coupon_id The ID of the coupon used for this service
  • qty The quanity consumed by this service
  • override_price The price to set for this service, overriding the package pricing value for the selected term (optional, default null)
  • override_currency The currency to set for this service, overriding the package pricing value for the selected term (optional, default null)
  • status The status of this service:
    • active
    • canceled
    • pending
    • suspended
    • in_review
  • suspension_reason The reason a service is being suspended
  • date_added The date this service is added
  • date_renews The date the service renews
  • date_last_renewed The date the service last renewed
  • date_paid_through The date the service is paid through (optional)
  • date_advance_renewal The date the service will be renewed in advance
  • date_suspended The date the service was last suspended
  • date_canceled The date the service was last canceled
  • use_module Whether or not to use the module for this request ('true','false', default 'true')
  • configoptions An array of key/value pairs of package options where the key is the package option ID and the value is the option value. Defining the 'configoptions' key will update all config options. Always include all config options if setting any, or changing the pricing_id. (optional)
    • Any other service field data to pass to the module
$bypass_module : bool = false

$vars['use_module'] notifies the module of whether or not it should internally use its module connection to process the request, however in some instances it may be necessary to prevent the module from being notified of the request altogether. If true, this will prevent the module from being notified of the request.

$notify : bool = false

If true and the service is set to active will send the service activation notification

Return values
int —

The ID of this service, void if error

editField()

Edit a service field for a particular service

public editField(int $service_id, array<string|int, mixed> $vars) : mixed
Parameters
$service_id : int

The ID of the service to edit

$vars : array<string|int, mixed>

An array of service field info including:

  • key The name of the value to edit
  • value The value to update with
  • encrypted Whether or not to encrypt the value when storing ('true', 'false', default 'false')

get()

Fetch a single service, including service field data

public get(int $service_id) : mixed
Parameters
$service_id : int

The ID of the service to fetch

Return values
mixed —

A stdClass object representing the service, false if no such service exists

getActions()

Returns all action options that can be performed for a service.

public getActions([string $current_status = null ]) : array<string|int, mixed>
Parameters
$current_status : string = null

Set to filter actions that may be performed if the service is in the given state options include:

  • active
  • suspended
  • canceled
Return values
array<string|int, mixed> —

An array of key/value pairs where each key is the action that may be performed and the value is the friendly name for the action

getAll()

Returns a list of services for the given client and status

public getAll([array<string|int, mixed> $order_by = ['date_added' => 'DESC'] ][, bool $children = true ][, array<string|int, mixed> $filters = [] ][, array<string|int, mixed> $formatted_filters = [] ]) : array<string|int, mixed>
Parameters
$order_by : array<string|int, mixed> = ['date_added' => 'DESC']

The sort and order conditions (e.g. array('sort_field'=>"ASC"), optional)

$children : bool = true

True to fetch all services, including child services, or false to fetch only services without a parent (optional, default true)

$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • client_id The client ID (optional)
  • package_id The package ID (optional)
  • module_id The module ID on which to filter packages (optional)
  • package_name The (partial) name of the packages for which to fetch services (optional)
  • service_meta The (partial) value of meta data on which to filter services (optional)
  • status The status type of the services to fetch (optional, default 'active'):
    • active All active services
    • canceled All canceled services
    • pending All pending services
    • suspended All suspended services
    • in_review All services that require manual review before they may become pending
    • scheduled_cancellation All services scheduled to be canceled
    • all All active/canceled/pending/suspended/in_review
  • type The type of the services, it can be 'services', 'domains' or null for all (optional, default null)
$formatted_filters : array<string|int, mixed> = []

The filter to apply with items in one or more of the following formats:

  • table.column => value
  • ['column' => column, 'operator' => operator, 'value' => value]
  • table => [column1 => value, column2 => value]
  • table => [['column1' => column, 'operator' => operator, 'value' => value], column2 => value]
Return values
array<string|int, mixed> —

An array of stdClass objects representing services

getAllByClient()

Returns a list of services for the given client and status unpaged

public getAllByClient(int $client_id[, string $status = 'active' ][, array<string|int, mixed> $order_by = ['date_added' => 'DESC'] ][, bool $children = true ][, int $package_id = null ]) : array<string|int, mixed>
Parameters
$client_id : int

The ID of the client to select services for

$status : string = 'active'

The status to filter by (optional, default "active"), one of:

  • active All active services
  • canceled All canceled services
  • pending All pending services
  • suspended All suspended services
  • in_review All services that require manual review before they may become pending
  • scheduled_cancellation All services scheduled to be canceled
  • all All active/canceled/pending/suspended/in_review
  • type The type of the services, it can be 'services', 'domains' or null for all (optional, default null)
$order_by : array<string|int, mixed> = ['date_added' => 'DESC']

The sort and order conditions (e.g. array('sort_field'=>"ASC"), optional)

$children : bool = true

True to fetch all services, including child services, or false to fetch only services without a parent (optional, default true)

$package_id : int = null

The ID of the package for which to select services (optional)

Return values
array<string|int, mixed> —

An array of stdClass objects representing services

getAllChildren()

Retrieves a list of all services that are child of the given parent service ID

public getAllChildren(int $parent_service_id[, string $status = 'all' ]) : array<string|int, mixed>
Parameters
$parent_service_id : int

The ID of the parent service whose child services to fetch

$status : string = 'all'

The status type of the services to fetch (optional, default 'all'):

  • active All active services
  • canceled All canceled services
  • pending All pending services
  • suspended All suspended services
  • in_review All services that require manual review before they may become pending
  • scheduled_cancellation All services scheduled to be canceled
  • all All active/canceled/pending/suspended/in_review
Return values
array<string|int, mixed> —

A list of stdClass objects representing each child service

getAllChildrenCount()

Retrieves the total number of add-on/children services for the given parent service ID

public getAllChildrenCount(int $parent_service_id[, string $status = 'all' ]) : int
Parameters
$parent_service_id : int

The ID of the parent service whose add-on-children services to count

$status : string = 'all'

The status type of the services to fetch (optional, default 'all'):

  • active All active services
  • canceled All canceled services
  • pending All pending services
  • suspended All suspended services
  • in_review All services that require manual review before they may become pending
  • scheduled_cancellation All services scheduled to be canceled
  • all All active/canceled/pending/suspended/in_review
Return values
int —

The total number of child services

getAllPaidPending()

Retrieves a list of paid pending services

public getAllPaidPending(int $client_group_id) : array<string|int, mixed>
Parameters
$client_group_id : int

The ID of the client group whose paid pending invoices to fetch

Return values
array<string|int, mixed> —

A list of services that have been paid and are still pending

getAllPendingCancelation()

Retrieves a list of services ready to be canceled

public getAllPendingCancelation() : array<string|int, mixed>
Return values
array<string|int, mixed> —

A list of stdClass objects representing services pending cancelation

getAllPendingSuspension()

Retrieves a list of services ready to be suspended

public getAllPendingSuspension(int $client_group_id, string $suspension_date) : array<string|int, mixed>
Parameters
$client_group_id : int

The ID of the client group

$suspension_date : string

The date before which service would be considered suspended

Return values
array<string|int, mixed> —

A list of stdClass objects representing services pending suspension

getAllPendingUnsuspension()

Retrieves a list of paid suspended services ready to be unsuspended. Will only return services that were automatically suspended (not manually suspended by a staff member).

public getAllPendingUnsuspension(int $client_group_id) : array<string|int, mixed>
Parameters
$client_group_id : int

The ID of the client group

Return values
array<string|int, mixed> —

A list of stdClass objects representing services pending unsuspension

getAllRenewablePaid()

Retrieves all renewable paid services

public getAllRenewablePaid([string $date = null ]) : array<string|int, mixed>
Parameters
$date : string = null

The date after which to fetch paid renewable services (deprecated)

Return values
array<string|int, mixed> —

A list of services that have been paid and may be processed

getAllRenewableUnpaid()

Retrieves all renewable paid services

public getAllRenewableUnpaid([string $date = null ]) : array<string|int, mixed>
Parameters
$date : string = null

The date after which to fetch paid renewable services (deprecated)

Return values
array<string|int, mixed> —

A list of services that have been paid and may be processed

getAllRenewing()

Retrieves a list of services ready to be renewed for this client group

public getAllRenewing([int $client_group_id = null ]) : array<string|int, mixed>
Parameters
$client_group_id : int = null

The client group ID to fetch renewing services from

Return values
array<string|int, mixed> —

A list of stdClass objects representing services set ready to be renewed

getChildRenewDate()

Determines the date a service should be prorated to so it matches its parent

public getChildRenewDate(stdClass $pricing, stdClass $parent_pricing, int $client_group_id) : string
Parameters
$pricing : stdClass

The new service pricing

$parent_pricing : stdClass

The parent service pricing

$client_group_id : int

The ID of the client group this service is under

Return values
string —

The expected renew date of the new service, or false if not being synchronized

getDataPresenter()

Retrieves a presenter representing a set of items, discounts, and taxes for service data

public getDataPresenter(int $client_id, array<string|int, mixed> $vars, array<string|int, mixed> $options) : bool|ServiceDataPresenter
Parameters
$client_id : int

The ID of the client the service data is for

$vars : array<string|int, mixed>

An array of input representing the new service data:

  • configoptions An array of key/value pairs where each key is an option ID and each value is the selected value
  • pricing_id The ID of the new pricing selected
  • qty The service quantity
  • coupon_code A new coupon code to use
  • parent_service_id The ID of this service's parent
$options : array<string|int, mixed>

An array of options used to construct the presenter

Return values
bool|ServiceDataPresenter —

The presenter, otherwise false

getFieldRules()

Retrieves the rule set for adding/editing service fields

public getFieldRules() : array<string|int, mixed>
Return values
array<string|int, mixed> —

The rules

getList()

Returns a list of services for the given client and status

public getList([int $client_id = null ][, string $status = 'active' ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_added' => 'DESC'] ][, bool $children = true ][, array<string|int, mixed> $filters = [] ][, array<string|int, mixed> $formatted_filters = [] ]) : array<string|int, mixed>
Parameters
$client_id : int = null

The ID of the client to select services for

$status : string = 'active'

The status to filter by (optional, default "active"), one of:

  • active All active services
  • canceled All canceled services
  • pending All pending services
  • suspended All suspended services
  • in_review All services that require manual review before they may become pending
  • scheduled_cancellation All services scheduled to be canceled
  • all All active/canceled/pending/suspended/in_review
$page : int = 1

The page to return results for (optional, default 1)

$order_by : array<string|int, mixed> = ['date_added' => 'DESC']

The sort and order conditions (e.g. array('sort_field'=>"ASC"), optional)

$children : bool = true

True to fetch all services, including child services, or false to fetch only services without a parent (optional, default true)

$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • client_id The client ID (optional)
  • excluded_pricing_term The pricing term by which to exclude results (optional)
  • module_id The module ID on which to filter packages, cannot be used along module (optional)
  • module The class name (in snake_case) ID on which to filter packages, cannot be used along module_id (optional)
  • pricing_period The pricing period for which to fetch services (optional)
  • package_id The package ID (optional)
  • package_name The (partial) name of the packages for which to fetch services (optional)
  • service_meta The (partial) value of meta data on which to filter services (optional)
  • status The status type of the services to fetch (optional, default 'active'):
    • active All active services
    • canceled All canceled services
    • pending All pending services
    • suspended All suspended services
    • in_review All services that require manual review before they may become pending
    • scheduled_cancellation All services scheduled to be canceled
    • all All active/canceled/pending/suspended/in_review
  • type The type of the services, it can be 'services', 'domains' or null for all (optional, default null)
$formatted_filters : array<string|int, mixed> = []

The filter to apply with items in one or more of the following formats:

  • table.column => value
  • ['column' => column, 'operator' => operator, 'value' => value]
  • table => [column1 => value, column2 => value]
  • table => [['column1' => column, 'operator' => operator, 'value' => value], column2 => value]
Return values
array<string|int, mixed> —

An array of stdClass objects representing services

getListCount()

Returns the total number of services for a client, useful in constructing pagination for the getList() method.

public getListCount([int $client_id = null ][, string $status = 'active' ][, bool $children = true ][, int $package_id = null ][, array<string|int, mixed> $filters = [] ][, array<string|int, mixed> $formatted_filters = [] ]) : int
Parameters
$client_id : int = null

The client ID

$status : string = 'active'

The status type of the services to fetch (optional, default 'active'), one of:

  • active All active services
  • canceled All canceled services
  • pending All pending services
  • suspended All suspended services
  • in_review All services that require manual review before they may become pending
  • scheduled_cancellation All services scheduled to be canceled
  • all All active/canceled/pending/suspended/in_review
$children : bool = true

True to fetch all services, including child services, or false to fetch only services without a parent (optional, default true)

$package_id : int = null

The ID of the package for which to select services (optional)

$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • client_id The client ID (optional)
  • excluded_pricing_term The pricing term by which to exclude results (optional)
  • module_id The module ID on which to filter packages, cannot be used along module (optional)
  • module The class name (in snake_case) ID on which to filter packages, cannot be used along module_id (optional)
  • pricing_period The pricing period for which to fetch services (optional)
  • package_id The package ID (optional)
  • package_name The (partial) name of the packages for which to fetch services (optional)
  • service_meta The (partial) value of meta data on which to filter services (optional)
  • status The status type of the services to fetch (optional, default 'active'):
    • active All active services
    • canceled All canceled services
    • pending All pending services
    • suspended All suspended services
    • in_review All services that require manual review before they may become pending
    • scheduled_cancellation All services scheduled to be canceled
    • all All active/canceled/pending/suspended/in_review
  • type The type of the services, it can be 'services', 'domains' or null for all (optional, default null)
$formatted_filters : array<string|int, mixed> = []

The filter to apply with items in one or more of the following formats:

  • table.column => value
  • ['column' => column, 'operator' => operator, 'value' => value]
  • table => [column1 => value, column2 => value]
  • table => [['column1' => column, 'operator' => operator, 'value' => value], column2 => value]
Tags
see
Services::getList()
Return values
int —

The total number of services

getNextInvoiceDate()

Retrieves the date on which the next invoice is expected to be generated for a service

public getNextInvoiceDate(int $service_id[, string $format = 'Y-m-d H:i:s' ]) : mixed
Parameters
$service_id : int

The ID of the service whose next invoice date to fetch

$format : string = 'Y-m-d H:i:s'

The date format to return the date in (optional, default 'Y-m-d H:i:s')

Return values
mixed —

The next expected invoice date in UTC, or null if no further invoices are expected to be generated

getNextRenewDate()

Calculates the next renew date using a given date, term, and period

public getNextRenewDate(string $last_renew_date, int $term, string $period[, string $format = 'Y-m-d H:i:s' ][, int $pro_rata_day = null ]) : string
Parameters
$last_renew_date : string

The date the service last renewed. If never renewed this should be the service add date

$term : int

The term value relating to the given period

$period : string

The period (day, week, month, year, onetime)

$format : string = 'Y-m-d H:i:s'

The date format to return the date in (optional, default 'Y-m-d H:i:s')

$pro_rata_day : int = null

The day of the month to prorate to. Only set this value to fetch the prorated renew date. Only used for month/year periods. Ignored if the $last_renew_date is on the $pro_rata_day. (optional, default null)

Return values
string —

The date the service renews in UTC. In the event that the service does not renew or the renew date can not be calculated null is returned

getOptions()

Returns the configurable options for the service

public getOptions(int $service_id) : array<string|int, mixed>
Parameters
$service_id : int
Return values
array<string|int, mixed> —

An array of stdClass objects, each representing a service option

getPackagePricing()

Get package pricing

public getPackagePricing(int $pricing_id) : mixed
Parameters
$pricing_id : int
Return values
mixed —

stdClass object representing the package pricing, false otherwise

getPendingCancelationCount()

Retrieves a count of pending cancelation services

public getPendingCancelationCount([bool $include_failed = false ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed provisioning the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of unsuspend, false by default

Return values
array<string|int, mixed> —

A list of services that have been paid and may be provisioned

getPendingCancelationList()

Retrieves a list of pending cancelation services

public getPendingCancelationList([bool $include_failed = false ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_next_attempt' => 'DESC'] ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed provisioning the maximum number of times

$page : int = 1

The page to return results for (optional, default 1)

$order_by : array<string|int, mixed> = ['date_next_attempt' => 'DESC']

The sort and order conditions (e.g. array('sort_field' => "ASC"), optional)

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

Return values
array<string|int, mixed> —

A paginated list of services that have been paid and may be provisioned

getPendingCancelationQuery()

Retrieves a list of services ready to be canceled

public getPendingCancelationQuery([bool $include_failed = false ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed provisioning the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

Return values
array<string|int, mixed> —

A list of stdClass objects representing services pending cancelation

getPendingPaidCount()

Retrieves a count of pending paid services

public getPendingPaidCount([bool $include_failed = false ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Whether to include services that have already failed provisioning the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

Return values
array<string|int, mixed> —

A list of services that have been paid and may be provisioned

getPendingPaidList()

Retrieves a list of pending paid services

public getPendingPaidList([bool $include_failed = false ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_next_attempt' => 'DESC'] ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Whether to include services that have already failed provisioning the maximum number of times

$page : int = 1

The page to return results for (optional, default 1)

$order_by : array<string|int, mixed> = ['date_next_attempt' => 'DESC']

The sort and order conditions (e.g. array('sort_field' => "ASC"), optional)

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

Return values
array<string|int, mixed> —

A paginated list of services that have been paid and may be provisioned

getPendingPaidQuery()

Retrieves a list of paid pending services

public getPendingPaidQuery([bool $include_failed = false ][, bool $future_attempts = false ][, int $client_group_id = null ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed provisioning the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

$client_group_id : int = null

The ID of the client group whose paid pending invoices to fetch

Return values
array<string|int, mixed> —

A list of services that have been paid and are still pending

getPendingSuspensionCount()

Retrieves a count of pending suspension services

public getPendingSuspensionCount([bool $include_failed = false ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed provisioning the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

Return values
array<string|int, mixed> —

A list of services that have been paid and may be provisioned

getPendingSuspensionList()

Retrieves a list of pending suspension services

public getPendingSuspensionList([bool $include_failed = false ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_next_attempt' => 'DESC'] ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed provisioning the maximum number of times

$page : int = 1

The page to return results for (optional, default 1)

$order_by : array<string|int, mixed> = ['date_next_attempt' => 'DESC']

The sort and order conditions (e.g. array('sort_field' => "ASC"), optional)

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

Return values
array<string|int, mixed> —

A paginated list of services that have been paid and may be provisioned

getPendingSuspensionQuery()

Retrieves a query of services ready to be suspended

public getPendingSuspensionQuery([bool $include_failed = false ][, bool $future_attempts = false ][, int $client_group_id = null ][, string $suspension_date = null ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Whether to include services that have already failed provisioning the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

$client_group_id : int = null

The ID of the client group

$suspension_date : string = null

The date before which service would be considered suspended

Return values
array<string|int, mixed> —

A list of stdClass objects representing services pending suspension

getPendingUnsuspensionCount()

Retrieves a count of pending unsuspension services

public getPendingUnsuspensionCount([bool $include_failed = false ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed provisioning the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of unsuspend, false by default

Return values
array<string|int, mixed> —

A list of services that have been paid and may be provisioned

getPendingUnsuspensionList()

Retrieves a list of pending unsuspension services

public getPendingUnsuspensionList([bool $include_failed = false ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_next_attempt' => 'DESC'] ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed provisioning the maximum number of times

$page : int = 1

The page to return results for (optional, default 1)

$order_by : array<string|int, mixed> = ['date_next_attempt' => 'DESC']

The sort and order conditions (e.g. array('sort_field' => "ASC"), optional)

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

Return values
array<string|int, mixed> —

A paginated list of services that have been paid and may be provisioned

getPendingUnsuspensionQuery()

Retrieves a list of paid suspended services ready to be unsuspended. Will only return services that were automatically suspended (not manually suspended by a staff member).

public getPendingUnsuspensionQuery([bool $include_failed = false ][, bool $future_attempts = false ][, int $client_group_id = null ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed provisioning the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of provisioning, false by default

$client_group_id : int = null

The ID of the client group

Return values
array<string|int, mixed> —

A list of stdClass objects representing services pending unsuspension

getPresenter()

Retrieves a presenter representing a set of items, discounts, and taxes for the service

public getPresenter(int $service_id, array<string|int, mixed> $options) : bool|ServicePresenter
Parameters
$service_id : int

The ID of the service whose renewal pricing to fetch

$options : array<string|int, mixed>

An array of options used to construct the presenter

Return values
bool|ServicePresenter —

The presenter, otherwise false

getPricingInfo()

Fetches the pricing information for a service

public getPricingInfo(int $service_id[, string $currency_code = null ]) : mixed
Parameters
$service_id : int

The ID of the service whose pricing info te fetch

$currency_code : string = null

The ISO 4217 currency code to convert pricing to (optional, defaults to service's currency)

Return values
mixed —

An stdClass object representing service pricing fields, or false if none exist

getRenewablePaidCount()

Retrieves a count of renewable paid services

public getRenewablePaidCount([bool $include_failed = false ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Whether to include services that have already failed renewal the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of renewal, false by default

Return values
array<string|int, mixed> —

A list of services that have been paid and may be processed

getRenewablePaidList()

Retrieves a list of renewable paid services

public getRenewablePaidList([bool $include_failed = false ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_next_attempt' => 'DESC'] ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed renewal the maximum number of times

$page : int = 1

The page to return results for (optional, default 1)

$order_by : array<string|int, mixed> = ['date_next_attempt' => 'DESC']

The sort and order conditions (e.g. array('sort_field' => "ASC"), optional)

$future_attempts : bool = false

True to include the services with future attempts of renewal, false by default

Return values
array<string|int, mixed> —

A paginated list of services that have been paid and may be processed

getRenewablePaidQuery()

Retrieves a query for renewable paid services

public getRenewablePaidQuery([bool $include_failed = false ][, bool $future_attempts = false ]) : PDOStatement
Parameters
$include_failed : bool = false

Whether to include services that have already failed renewal the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of renewal, false by default

Return values
PDOStatement —

A query for services that have been paid and may be processed

getRenewableUnpaidCount()

Retrieves a count of renewable paid services

public getRenewableUnpaidCount([bool $include_failed = false ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Whether to include services that have already failed renewal the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of renewal, false by default

Return values
array<string|int, mixed> —

A list of services that have been paid and may be processed

getRenewableUnpaidList()

Retrieves a list of renewable paid services

public getRenewableUnpaidList([bool $include_failed = false ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_next_attempt' => 'DESC'] ][, bool $future_attempts = false ]) : array<string|int, mixed>
Parameters
$include_failed : bool = false

Wether to include services that have already failed renewal the maximum number of times

$page : int = 1

The page to return results for (optional, default 1)

$order_by : array<string|int, mixed> = ['date_next_attempt' => 'DESC']

The sort and order conditions (e.g. array('sort_field' => "ASC"), optional)

$future_attempts : bool = false

True to include the services with future attempts of renewal, false by default

Return values
array<string|int, mixed> —

A paginated list of services that have been paid and may be processed

getRenewableUnpaidQuery()

Retrieves a query for renewable paid services

public getRenewableUnpaidQuery([bool $include_failed = false ][, bool $future_attempts = false ]) : PDOStatement
Parameters
$include_failed : bool = false

Whether to include services that have already failed renewal the maximum number of times

$future_attempts : bool = false

True to include the services with future attempts of renewal, false by default

Return values
PDOStatement —

A query for services that have been paid and may be processed

getRenewalPrice()

Retrieves the next expected renewal price of a service based on its current configuration, options, and pricing

public getRenewalPrice(int $service_id[, string $currency = null ]) : float
Parameters
$service_id : int

The ID of the service whose renewal pricing to fetch

$currency : string = null

The ISO 4217 3-character currency code to convert the total to

Return values
float —

The next expected renewal price

getSearchCount()

Return the total number of services returned from Services::search(), useful in constructing pagination

public getSearchCount(string $query[, bool $search_fields = false ]) : int
Parameters
$query : string

The value to search services for

$search_fields : bool = false

True to search service fields for the given $query value, or false to not search them

Tags
see
Transactions::search()
Return values
int —

The number of results

getServiceItems()

Gets a list of items based on the service data given and updates line totals accordingly

public getServiceItems(array<string|int, mixed> $vars, array<string|int, mixed> $options, array<string|int, mixed> &$line_totals[, string $currency = null ][, string $from_currency = null ]) : array<string|int, mixed>
Parameters
$vars : array<string|int, mixed>

A list of service data:

  • client_id The ID of the client this service is for
  • configoptions An array of key/value pairs where each key is an option ID and each value is the selected value
  • pricing_id The ID of the new pricing selected
  • qty The service quantity
  • coupon_code A new coupon code to use
  • parent_service_id The ID of this service's parent
$options : array<string|int, mixed>

A list of options for the pricing presenter:

  • recur Boolean true/false. Whether the pricing items are recurring, or if they are being added for the first time (default false)
  • transfer Boolean true/false. Whether to use the transfer price or not, i.e., the service is a domain being transferred. May affect coupon discounts. Default false.
  • includeSetupFees Whether to include applicable setup fees
  • prorateStartDate Will prorate the service from this date to the prorateEndDate
  • prorateEndDate Will override the otherwise calculated prorate end date
$line_totals : array<string|int, mixed>

A list of totals to be updated:

  • subtotal
  • total
  • total_without_exclusive_tax
  • tax A list of applicable tax totals
  • discount
$currency : string = null

The currency to convert the total to

$from_currency : string = null

The currency to convert the total from

Return values
array<string|int, mixed> —

A list of invoice items for the service

getSimpleList()

Retrieves a list of all services in the system

public getSimpleList([int $client_id = null ][, int $page = 1 ]) : array<string|int, mixed>
Parameters
$client_id : int = null

The ID of the client whose services to retrieve (optional)

$page : int = 1

The page to return results for (optional, default 1)

Return values
array<string|int, mixed> —

An array of stdClass objects representing each service

getStatusCount()

Returns the number of results available for the given status

public getStatusCount(int $client_id[, string $status = 'active' ][, bool $children = true ][, array<string|int, mixed> $filters = [] ][, array<string|int, mixed> $formatted_filters = [] ]) : int
Parameters
$client_id : int

The ID of the client to select status count values for

$status : string = 'active'

The status value to select a count of ('active', 'canceled', 'pending', 'suspended')

$children : bool = true

True to fetch all services, including child services, or false to fetch only services without a parent (optional, default true)

$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • client_id The client ID (optional)
  • excluded_pricing_term The pricing term by which to exclude results (optional)
  • module_id The module ID on which to filter packages (optional)
  • pricing_period The pricing period for which to fetch services (optional)
  • package_id The package ID (optional)
  • package_name The (partial) name of the packages for which to fetch services (optional)
  • service_meta The (partial) value of meta data on which to filter services (optional)
  • status The status type of the services to fetch (optional, default 'active'):
    • active All active services
    • canceled All canceled services
    • pending All pending services
    • suspended All suspended services
    • in_review All services that require manual review before they may become pending
    • scheduled_cancellation All services scheduled to be canceled
    • all All active/canceled/pending/suspended/in_review
  • type The type of the services, it can be 'services', 'domains' or null for all (optional, default null)
$formatted_filters : array<string|int, mixed> = []

The filter to apply with items in one or more of the following formats:

  • table.column => value
  • ['column' => column, 'operator' => operator, 'value' => value]
  • table => [column1 => value, column2 => value]
  • table => [['column1' => column, 'operator' => operator, 'value' => value], column2 => value]
Return values
int —

The number representing the total number of services for this client with that status

getStatusTypes()

Retrieves a list of service status types

public getStatusTypes() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Key=>value pairs of status types

getType()

Gets the type of the given service

public getType(int $service_id) : string
Parameters
$service_id : int

The ID of the parent service to validate

Return values
string —

The type of the service, it could be "service" or "domain"

getWelcomeEmailTags()

Returns all default welcome email tags, which are set into the email that is delivered when a service is provisioned.

public getWelcomeEmailTags() : array<string|int, mixed>
Return values
array<string|int, mixed> —

A multi-dimensional array of tags where the first dimension is the category and the second is a numeric array of tags

hasChildren()

Determines whether a service has any child services of the given status

public hasChildren(int $service_id[, string $status = null ]) : bool
Parameters
$service_id : int

The ID of the service to check

$status : string = null

The status of any child services to filter on (e.g. "active", "canceled", "pending", "suspended", "in_review", or null for any status) (optional, default null)

Return values
bool —

True if the service has children, false otherwise

hasParent()

Determines whether a service has a parent services of the given status

public hasParent(int $service_id) : bool
Parameters
$service_id : int

The ID of the service to check

Return values
bool —

True if the service has a parent, false otherwise

incrementServiceAttempt()

Increments the attempts to perform an action for a given service

public incrementServiceAttempt(stdClass $service, string $type[, mixed $invoice_id = null ]) : mixed
Parameters
$service : stdClass

An object representing the service

$type : string

The attempt type (provisioning, renewal, suspension, unsuspension, cancelation)

$invoice_id : mixed = null

isInstanceOf()

Checks if the given $field is a reference of $class

public isInstanceOf(mixed $field, mixed $class) : bool
Parameters
$field : mixed

The field whose instance to check

$class : mixed

The class or instance to check against

Return values
bool —

True if the $field is an instance of $class, otherwise false

isServiceOptionValueInUse()

Determines whether the given option value is currently in use by any non-cancelled service

public isServiceOptionValueInUse(int $option_value_id[, int $option_pricing_id = null ]) : bool
Parameters
$option_value_id : int

The package option value ID

$option_pricing_id : int = null

The package option pricing ID

Return values
bool —

True if the service option value is in use by at least one service, or false otherwise

move()

Moves a service to a different client

public move(int $service_id, int $client_id) : int
Parameters
$service_id : int

The ID of the service to move

$client_id : int

The ID of the client where the service will be moved on

Return values
int —

The ID of the service, void on error

renew()

Processes the renewal for the given service by contacting the module (if supported by the module), to let it know that the service should be renewed. Note: This method does not affect the renew date of the service in Blesta, it merely notifies the module; this action takes place after a service has been paid not when its renew date is bumped.

public renew(int $service_id[, int|null $invoice_id = null ]) : mixed
Parameters
$service_id : int

The ID of the service to process the renewal for

$invoice_id : int|null = null

The ID of the paid invoice that triggered this renewal (optional)

search()

Search services

public search(string $query[, int $page = 1 ][, bool $search_fields = false ]) : array<string|int, mixed>
Parameters
$query : string

The value to search services for

$page : int = 1

The page number of results to fetch (optional, default 1)

$search_fields : bool = false

If true will also search service fields for the value

Return values
array<string|int, mixed> —

An array of services that match the search criteria

searchServiceFields()

Searches services of the given module that contains the given service field key/value pair.

public searchServiceFields(int $module_id, string $key, string $value) : array<string|int, mixed>
Parameters
$module_id : int

The ID of the module to search services on

$key : string

They service field key to search

$value : string

The service field value to search

Return values
array<string|int, mixed> —

An array of stdClass objects, each containing a service

setFields()

Updates the field data for the given service, removing all existing data and replacing it with the given data

public setFields(int $service_id, array<string|int, mixed> $vars) : mixed
Parameters
$service_id : int

The ID of the service to set fields on

$vars : array<string|int, mixed>

A numerically indexed array of field data containing:

  • key The key for this field
  • value The value for this key
  • encrypted Whether or not this field should be encrypted ('true', 'false', default 'false')

suspend()

Suspends a service

public suspend(int $service_id[, array<string|int, mixed> $vars = [] ]) : mixed
Parameters
$service_id : int

The ID of the service to suspend

$vars : array<string|int, mixed> = []

An array of info including:

  • use_module Whether or not to use the module when suspending the service ('true','false', default 'true')
  • staff_id The ID of the staff member that issued the service suspension
  • suspension_reason The reason for the service suspension

unCancel()

Recreates a previously cancelled service.

public unCancel(int $service_id[, array<string|int, mixed> $vars = [] ]) : mixed
Parameters
$service_id : int

The ID of the service to recreate

$vars : array<string|int, mixed> = []

An array of service info including:

  • use_module Whether or not to use the module when canceling the service, if canceling now ('true','false', default 'true')
    • Any other service field data to pass to the module

unsuspend()

Unsuspends a service

public unsuspend(int $service_id[, array<string|int, mixed> $vars = [] ]) : mixed
Parameters
$service_id : int

The ID of the service to unsuspend

$vars : array<string|int, mixed> = []

An array of info including:

  • use_module Whether or not to use the module when unsuspending the service ('true','false', default 'true')
  • staff_id The ID of the staff member that issued the service unsuspension

validate()

Performs all validation necessary before adding a service

public validate(array<string|int, mixed> $vars[, array<string|int, mixed> $packages = null ]) : array<string|int, mixed>
Parameters
$vars : array<string|int, mixed>

An array of service info including:

  • parent_service_id The ID of the service this service is a child of (optional)
  • package_group_id The ID of the package group this service was added from (optional)
  • pricing_id The package pricing schedule ID for this service
  • client_id The ID of the client to add the service under
  • module_row_id The module row to add the service under (optional, default is first available)
  • coupon_id The ID of the coupon used for this service (optional)
  • qty The quanity consumed by this service (optional, default 1)
  • status The status of this service ('active','canceled','pending','suspended', default 'pending')
  • date_added The date this service is added (default to today's date UTC)
  • date_renews The date the service renews (optional, default calculated by package term)
  • date_last_renewed The date the service last renewed (optional)
  • date_paid_through The date the service is paid through (optional)
  • date_suspended The date the service was last suspended (optional)
  • date_canceled The date the service was last canceled (optional)
  • use_module Whether or not to use the module when creating the service ('true','false', default 'true')
  • configoptions An array of key/value pairs of package options where the key is the package option ID and the value is the option value (optional)
    • Any other service field data to pass to the module
$packages : array<string|int, mixed> = null

An array of packages ordered along with this service to determine if the given coupon may be applied given in one of the following formats:

  • A numerically indexed array of package IDs
  • An array of package IDs and pricing IDs [packageID => pricingID]
Tags
see
Services::validateService()
Return values
array<string|int, mixed> —

$vars An array of $vars, modified by error checking

validateAllowed()

Verifies that the client has access to the package for the given pricing ID

public validateAllowed(int $client_id, int $pricing_id) : bool
Parameters
$client_id : int

The ID of the client

$pricing_id : int

The ID of the package pricing

Return values
bool —

True if the client can add the package, false otherwise

validateConfigOptions()

Verifies that the given package options are valid

public validateConfigOptions(array<string|int, mixed> $config_options, int $pricing_id[, array<string|int, mixed> $current_options = [] ]) : bool
Parameters
$config_options : array<string|int, mixed>

An array of key/value pairs where each key is the package option ID and each value is the option value

$pricing_id : int

The package pricing ID

$current_options : array<string|int, mixed> = []

An array of key/value pairs currently on the service where each key is the package option ID and each value is the option value

Return values
bool —

True if valid, false otherwise

validateCoupon()

Verifies if the given coupon ID can be applied to the requested packages

public validateCoupon(int $coupon_id[, array<string|int, mixed> $packages = null ]) : bool
Parameters
$coupon_id : int

The ID of the coupon to validate

$packages : array<string|int, mixed> = null

An array of pacakges to confirm the coupon can be applied given in one of the following formats:

  • A numerically indexed array of package IDs
  • An array of package IDs and pricing IDs [packageID => pricingID]
Return values
bool —

True if the coupon can be applied, false otherwise

validateDateCanceled()

Verifies that the given date value is valid for a cancel date

public validateDateCanceled(string $date) : bool
Parameters
$date : string

The date to cancel a service or "end_of_term" to cancel at the end of the term

Return values
bool —

True if $date is valid, false otherwise

validateDateRenews()

Verifies that the given renew date is greater than the last renew date (if available)

public validateDateRenews(string $renew_date[, string $last_renew_date = null ]) : bool
Parameters
$renew_date : string

The date a service should renew

$last_renew_date : string = null

The date a service last renewed

Return values
bool —

True if renew date is valid, false otherwise

validateEncrypted()

Validates a service field's 'encrypted' field

public validateEncrypted(string $encrypted) : mixed
Parameters
$encrypted : string

Whether or not to encrypt

validateHasChildren()

Validates whether the given service has children NOT of the given status

public validateHasChildren(int $service_id[, string $status = null ]) : bool
Parameters
$service_id : int

The ID of the parent service to validate

$status : string = null

The status of children services to ignore (e.g. "canceled") (optional, default null to not ignore any child services)

Return values
bool —

True if the service has children not of the given status, false otherwise

validateOverrideFields()

Verifies that the given price and currency fields have been set together

public validateOverrideFields(mixed $price, mixed $currency) : bool
Parameters
$price : mixed

The price override, or null

$currency : mixed

The currency override, or null

Return values
bool —

True if the price and currency have been set properly together, or false otherwise

validatePriceOverride()

Verifies that the given price override is in a valid format

public validatePriceOverride(float $price) : bool
Parameters
$price : float

The price override

Return values
bool —

True if the price is valid, false otherwise

validatePricingWithOverrides()

Verifies that the given service and pricing ID are valid with price overrides

public validatePricingWithOverrides(int $pricing_id, int $service_id, float $price, string $currency) : bool
Parameters
$pricing_id : int

The ID of the pricing term

$service_id : int

The ID of the service being updated

$price : float

The price override amount

$currency : string

The price override currency

Return values
bool —

True if the pricing ID may be set for this service given the price overrides, or false otherwise

validateService()

Validates service info, including module options, for creating a service. An alternative to Services::validate() Sets Input errors on failure

public validateService(stdClass $package, array<string|int, mixed> $vars) : mixed
Parameters
$package : stdClass

A stdClass object representing the package for the service

$vars : array<string|int, mixed>

An array of values to be evaluated, including:

  • invoice_method The invoice method to use when creating the service, options are:
    • create Will create a new invoice when adding this service
    • append Will append this service to an existing invoice (see 'invoice_id')
    • none Will not create any invoice
  • invoice_id The ID of the invoice to append to if invoice_method is set to 'append'
  • pricing_id The ID of the package pricing to use for this service
  • configoptions An array of key/value pairs of package options where the key is the package option ID and the value is the option value (optional)
    • Any other service field data to pass to the module
Tags
see
Services::validate()

validateServiceEdit()

Performs all validation necessary for updating a service. Sets Input errors on failure

public validateServiceEdit(int $service_id, array<string|int, mixed> $vars[, bool $bypass_module = false ]) : mixed
Parameters
$service_id : int

The ID of the service to validate

$vars : array<string|int, mixed>

An array of key/value pairs to be evaluated:

  • configoptions An array of key/value pairs of package options where the key is the package option ID and the value is the option value (optional)
$bypass_module : bool = false

Whether or not to ignore the module service edit validation

validateStatus()

Validates a service's 'status' field

public validateStatus(string $status) : bool
Parameters
$status : string

The status type

Return values
bool —

True if $status is valid, false otherwise

validateUseModule()

Validates whether to use a module when adding/editing a service

public validateUseModule(string $use_module) : bool
Parameters
$use_module : string
Return values
bool —

True if validated, false otherwise

getFields()

Return all field data for the given service, decrypting fields where neccessary

protected getFields(int $service_id) : array<string|int, mixed>
Parameters
$service_id : int

The ID of the service to fetch fields for

Return values
array<string|int, mixed> —

An array of stdClass objects representing fields, containing:

  • key The service field name
  • value The value for this service field
  • encrypted Whether or not this field was originally encrypted (1 true, 0 false)

addCancelInvoice()

Creates an invoice for a client based on the given service being canceled i.e. service cancellation fee

private addCancelInvoice(stdClass $service, string $date_canceled) : mixed
Parameters
$service : stdClass

The service in process of being canceled

$date_canceled : string

The service cancellation date

Tags
see
Services::cancel

appendServiceInfo()

Adds more information to the given service

private appendServiceInfo(array<string|int, mixed> $services) : array<string|int, mixed>
Parameters
$services : array<string|int, mixed>

A list of stdClass objects each representing a service

Return values
array<string|int, mixed> —

An array of services with additional service information

cancelOnModule()

Cancels the given service using its module. Sets Input errors on failure

private cancelOnModule(stdClass $service, stdClass $package[, mixed $parent_service = null ][, mixed $parent_package = null ]) : mixed
Parameters
$service : stdClass

The service to cancel

$package : stdClass

The package associated with the service

$parent_service : mixed = null

An stdClass object representing the parent_service, if any

$parent_package : mixed = null

An stdClass object representing the parent package, if any

Tags
see
Services::cancel

formatConfigOptions()

Formats given config options by removing options with 0 quantity

private formatConfigOptions([array<string|int, mixed> $config_options = [] ]) : array<string|int, mixed>
Parameters
$config_options : array<string|int, mixed> = []

An array of key/value pairs of package options where the key is the package option ID and the value is the option value (optional)

Return values
array<string|int, mixed> —

An array of key/value pairs of package options where the key is the package option ID and the value is the option value

getConfigurableModuleFields()

Returns an array containing the module row and module group from the configurable options

private getConfigurableModuleFields(array<string|int, mixed> $config_options[, stdClass|null $service = null ]) : array<string|int, mixed>
Parameters
$config_options : array<string|int, mixed>

An array containing the configurable options

$service : stdClass|null = null

An object representing the service for which to get the module fields

Return values
array<string|int, mixed> —

An array containing the module row id and/or module group id, if available

getModuleClassByPricingId()

Returns info regarding the module belonging to the given $package_pricing_id

private getModuleClassByPricingId(int $package_pricing_id) : mixed
Parameters
$package_pricing_id : int

The package pricing ID to fetch the module of

Return values
mixed —

A stdClass object containing module info and the package ID belonging to the given $package_pricing_id, false if no such module exists

getOptionsAvailable()

Fetches all of the package options available for a given pricing

private getOptionsAvailable(int $pricing_id[, mixed &$pricing = null ][, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>
Parameters
$pricing_id : int

The package pricing ID of the package from which to fetch package options

$pricing : mixed = null

The package pricing object to update to set with the selected pricing

$options : array<string|int, mixed> = []

An array of key/value pairs for filtering options, including:

  • configoptions An array of key/value pairs currently in use where each key is the package option ID and each value is the option value
Return values
array<string|int, mixed> —

An array of package options

getRelations()

Fetches all relations (e.g. packages and services) for the given service ID

private getRelations(int $service_id) : array<string|int, mixed>
Parameters
$service_id : int

The ID of the service to fetch relations for

Return values
array<string|int, mixed> —

A array consisting of:

  • service The given service
  • package The service's package
  • parent_service The parent service
  • parent_package The parent service's package

getRules()

Retrieves the rule set for adding/editing services

private getRules(array<string|int, mixed> $vars[, bool $edit = false ][, int $service_id = null ]) : array<string|int, mixed>
Parameters
$vars : array<string|int, mixed>

An array of input fields

$edit : bool = false

Whether or not this is an edit request

$service_id : int = null

The ID of the service being edited (optional, default null)

Return values
array<string|int, mixed> —

The rules

getServiceLineItemAmounts()

Retrieves a list of line item amounts from the given line items

private getServiceLineItemAmounts(array<string|int, mixed> $line_items) : array<string|int, mixed>
Parameters
$line_items : array<string|int, mixed>

An array of line items that the coupon will be applying toward:

  • service_id The ID of the service, matching one of the given $services
  • description The line item description
  • qty The line item quantity
  • amount The line item amount
  • tax Whether or not the line item is taxable
  • service_option_id The ID of the service option the line item represents, if any
  • setup_fee Whether or not the line item is a setup fee
Tags
see
Services::buildServiceCouponLineItems
note

Deprecate and remove this method along with Services::buildServiceCouponLineItems

Return values
array<string|int, mixed> —

An array containing an array of services keyed by service ID, and any service option amounts keyed by service option ID, including:

  • before_cutoff An array of items including:
    • amount The service amount (null if no service amount is known)
    • qty The service quantity
    • options An array of service options, including:
      • amount The service option amount
      • qty The service option quantity
  • after_cutoff An array of items after the cutoff including:
    • amount The service amount (null if no service amount is known)
    • qty The service quantity
    • options An array of service options, including:
      • amount The service option amount
      • qty The service option quantity

getServiceOptions()

Retrieves a list of package option IDs that can be added/updated to the given service

private getServiceOptions(int $pricing_id, array<string|int, mixed> $config_options[, int $service_id = null ]) : array<string|int, mixed>
Parameters
$pricing_id : int

The ID of the new pricing ID to use for the service

$config_options : array<string|int, mixed>

A key/value array of option IDs and their selected values

$service_id : int = null

The ID of the current service before it has been updated (optional)

Return values
array<string|int, mixed> —

An array containing:

  • add A key/value array of option IDs and their option pricing ID to be added
  • edit An array containing:
    • new A key/value array of option IDs and their new option pricing ID to be upgraded to
    • old A key/value array of option IDs and their old (current) option pricing ID to upgrade from
  • delete A key/value array of current option IDs and their option pricing ID to be removed

getServiceOptionsTotal()

Retrieves the full total service options cost for the given service

private getServiceOptionsTotal(int $service_id) : float
Parameters
$service_id : int

The ID of the service to which the options belong

Tags
see
Services::buildServiceCouponLineItems
Return values
float —

The total cost of all service options

getServices()

Partially constructs the query required by Services::getList() and others

private getServices([array<string|int, mixed> $filters = [] ][, bool $children = true ][, array<string|int, mixed> $formatted_filters = [] ][, array<string|int, mixed> $additional_fields = [] ]) : Record
Parameters
$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • client_id The client ID (optional)
  • excluded_pricing_term The pricing term by which to exclude results (optional)
  • module_id The module ID on which to filter packages, cannot be used along module (optional)
  • module The class name (in snake_case) ID on which to filter packages, cannot be used along module_id (optional)
  • pricing_period The pricing period for which to fetch services (optional)
  • package_id The package ID (optional)
  • package_name The (partial) name of the packages for which to fetch services (optional)
  • service_meta The (partial) value of meta data on which to filter services (optional)
  • status The status type of the services to fetch (optional, default 'active'):
    • active All active services
    • canceled All canceled services
    • pending All pending services
    • suspended All suspended services
    • in_review All services that require manual review before they may become pending
    • scheduled_cancellation All services scheduled to be canceled
    • all All active/canceled/pending/suspended/in_review
  • type The type of the services, it can be 'services', 'domains' or null for all (optional, default null)
$children : bool = true

True to fetch all services, including child services, or false to fetch only services without a parent (optional, default true)

$formatted_filters : array<string|int, mixed> = []

The filter to apply with items in one or more of the following formats:

  • table.column => value
  • ['column' => column, 'operator' => operator, 'value' => value]
  • table => [column1 => value, column2 => value]
  • table => [['column1' => column, 'operator' => operator, 'value' => value], column2 => value]
$additional_fields : array<string|int, mixed> = []
Return values
Record —

The partially constructed query Record object

getSuspensionAndCancellationTags()

Gets a list of tags for the serice suspension and cancellation email

private getSuspensionAndCancellationTags(stdClass $service, stdClass $package, stdClass $client) : mixed
Parameters
$service : stdClass

An object representing the service

$package : stdClass

An object representing the package associated with the service

$client : stdClass

An object representing the client associated with the service

searchServices()

Partially constructs the query for searching services

private searchServices(string $query[, bool $search_fields = false ]) : Record
Parameters
$query : string

The value to search services for

$search_fields : bool = false

If true will also search service fields for the value

Tags
see

Services::search(), Services::getSearchCount()

Return values
Record —

The partially constructed query Record object

sendCancellationNoticeEmail()

Sends the service cancellation email

private sendCancellationNoticeEmail(stdClass $service, stdClass $package) : mixed
Parameters
$service : stdClass

An object representing the service

$package : stdClass

An object representing the package associated with the service

sendNotificationEmail()

Sends a service confirmation email

private sendNotificationEmail(stdClass $service, stdClass $package, int $client_id[, string $type = 'creation' ]) : mixed
Parameters
$service : stdClass

An object representing the service created

$package : stdClass

An object representing the package associated with the service

$client_id : int

The ID of the client to send the notification to

$type : string = 'creation'

The type of email notification to send, it could be 'creation' (default) or 'uncancellation'

sendScheduledCancellationNoticeEmail()

Sends the service scheduled cancellation email

private sendScheduledCancellationNoticeEmail(stdClass $service, stdClass $package) : mixed
Parameters
$service : stdClass

An object representing the service

$package : stdClass

An object representing the package associated with the service

sendSuspensionNoticeEmail()

Sends the service (un)suspension email

private sendSuspensionNoticeEmail(string $type, stdClass $service, stdClass $package) : mixed
Parameters
$type : string

The type of email to send (i.e. "suspend" or "unsuspend")

$service : stdClass

An object representing the service

$package : stdClass

An object representing the package associated with the service

setServiceOptions()

Updates the service to set all of its service config options

private setServiceOptions(int $service_id, array<string|int, mixed> $service_options, array<string|int, mixed> $config_options) : mixed
Parameters
$service_id : int

The ID of the service to update

$service_options : array<string|int, mixed>

An array of service options from Services::getServiceOptions

$config_options : array<string|int, mixed>

A key/value array of config options selected with the key being the option ID and the value being the selected value

validateEdit()

Performs all validation necessary before updating a service

private validateEdit(int $service_id, array<string|int, mixed> $vars[, bool $bypass_module = false ]) : array<string|int, mixed>
Parameters
$service_id : int

The ID of the service to validate

$vars : array<string|int, mixed>

An array of key/value pairs to be evaluated

$bypass_module : bool = false

Whether or not to ignore the module service edit validation

Tags
see
Services::validateServiceEdit()
Return values
array<string|int, mixed> —

$vars An array of $vars, modified by error checking:

  • configoptions An array of key/value pairs of package options where the key is the package option ID and the value is the option value (optional)

voidInvoices()

Any open invoices that contain line items related to the given service will be removed from the invoice, and all payments to it unapplied.

private voidInvoices(int $service_id[, array<string|int, mixed> $options = [] ]) : mixed

If the result is that all line items would be removed from the invoice, then the invoice will be voided instead.

Parameters
$service_id : int

The ID of the service whose open invoices to void

$options : array<string|int, mixed> = []

An array of options:

  • reapply_payments True or false, whether to reapply transaction payments that are unapplied. Default true
  • void_inv_canceled_service_days The number of days the invoice may be past due and still be voided
    • any to disregard the past due date
    • 0 to be the date the invoice is due
    • 1 to be one day after the invoice is due, 2, ..., n to be n days after the invoice is due
Tags
see
Services::cancel
Tags
subpackage

app.models

copyright

Copyright (c) 2010, Phillips Data, Inc.

license

http://www.blesta.com/license/ The Blesta License Agreement

link

Blesta

 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results