Blesta Source Documentation

ServiceChangeBuilder extends AbstractServiceChangeBuilder uses Meta

Service change builder

Table of Contents

Properties

$discounts
$formatFactory
$itemFactory
$options
$presenterFactory
$pricingFactory
$serviceFactory
$settings
$taxes

Methods

__construct()	Init
build()	Retrieve a ServiceChangePresenter
discounts()	Sets all discounts
options()	Sets any key/value custom options
settings()	Sets a list of settings
taxes()	Sets all tax rules
formatDiscounts()	Formats the discounts
formatOptions()	Formats the options
formatSettings()	Formats the settings
formatTaxes()	Formats the taxes
getMeta()	Retrieves all meta information set on a meta item combined together
getMetaFromCollection()	Retrieves all meta information set on an item collection
builderFactory()	Creates an instance of the BuilderFactory
combineDescription()	Combines two items via their meta data to determine a new description
combineKeys()	Updates the given service data items to have the same keys as the service collection for items that match, and which can be combined.
combinePrice()	Combines two items via their prices and meta data to determine a new single price
discountsContainType()	Determines whether any of the given discounts contains a discount of the given type
getCombinedKey()	Retrieves the given $item's new key
getKeys()	Hashes each collection's item keys in a key/value array
getOptionKey()	Retrieves the new item key to use for the given service option item
getServiceKey()	Retrieves the new item key to use for the given service item
makeMetaItem()	Creates a new Item which can be added as meta to an ItemPrice
metaItemsMatch()	Compares all discounts from $discounts1 with $discounts2 to check whether all discounts are present identically in both arguments
pairCollections()	Pairs items in one collection with items in the other collection for all items that have no matching key (i.e. are not already paired). The paired items are 0-cost items.
removeFees()	Updates the collection to remove setup fees and cancel fees that shouldn't apply
removeUnchanged()	Updates the collection to remove items that have not changed
serviceBuilder()	Creates an instance of the ServiceBuilder
serviceDataBuilder()	Creates an instance of the ServiceDataBuilder
updateMeta()	Updates the given MetaItemInterface to set the first meta item with the given data

$discounts


        protected
            array<string|int, mixed>
    $discounts
     = []

An array of stdClass objects representing each discount

$formatFactory


        protected
            Instance
    $formatFactory

of FormatFactory

$itemFactory


        protected
            Instance
    $itemFactory

of ItemFactory

$options


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

All key/value custom options

$presenterFactory


        protected
            Instance
    $presenterFactory

of PresenterFactory

$pricingFactory


        protected
            Instance
    $pricingFactory

of PricingFactory

$serviceFactory


        protected
            Instance
    $serviceFactory

of ServiceFactory

$settings


        protected
            array<string|int, mixed>
    $settings
     = []

All key/value settings

$taxes


        protected
            array<string|int, mixed>
    $taxes
     = []

An array of stdClass objects representing each tax rule

__construct()

Init


    public
                    __construct(ServiceFactory $serviceFactory, FormatFactory $formatFactory, PricingFactory $pricingFactory, PresenterFactory $presenterFactory, ItemFactory $itemFactory) : mixed

Parameters

$serviceFactory : ServiceFactory: An instance of the ServiceFactory
$formatFactory : FormatFactory: An instance of the FormatFactory
$pricingFactory : PricingFactory: An instance of the PricingFactory
$presenterFactory : PresenterFactory: An instance of the PresenterFactory
$itemFactory : ItemFactory: An instance of the ItemFactory

build()

Retrieve a ServiceChangePresenter


    public
                    build(stdClass $service, array<string|int, mixed> $vars, stdClass $package, stdClass $pricing, array<string|int, mixed> $options) : ServiceChangePresenter

Parameters

$service : stdClass

An stdClass object representing the original service, including:

name The service's name
qty The service quantity
override_price The service's override price
override_currency The service's override currency
date_renews The service renew date
options An array of service options, each option an stdClass object containing:
- id The option value ID
- service_id The service ID
- option_pricing_id The option's pricing ID
- qty The option quantity
- option_value The option value
- option_value_name The option value name
- option_id The option's ID
- option_label The option's label
- option_name The name of the option
- option_type The type of option
- option_pricing_term The option's pricing term
- option_pricing_period The option's pricing period
- option_pricing_price The option's pricing price
- option_pricing_setup_fee The option's pricing setup fee
- option_pricing_currency The option's pricing currency
package_pricing An stdClass object representing the service's package pricing, including:
- id The package pricing ID
- package_id The package ID
- term The pricing term
- period The pricing period
- setup_fee The pricing setup fee
- cancel_fee The pricing cancelation fee
- currency The pricing currency
package An stdClass object representing the service's package, including:
- name The package name
- taxable 1 or 0, whether the package is taxable
- prorata_day The package pro rata day
- prorata_cutoff The package pro rata cutoff day

$vars : array<string|int, mixed>

An array of input data, including:

pricing_id The ID of the selected package pricing
qty The new service quantity - default's to current service quantity if not specified
override_price The new override price
override_currency The new override currency
configoptions An array of new config options where each key is the option ID and the value is the selected option value

$package : stdClass

An stdClass object representing the new package being changed to, including:

id The package ID
name The package's name
taxable 1 or 0, whether the package is taxable
prorata_day The package pro rata day
prorata_cutoff The package pro rata cutoff day

$pricing : stdClass

An stdClass object representing the new service's package pricing, including:

id The package pricing ID
package_id The package ID
term The pricing term
period The pricing period
setup_fee The pricing setup fee
cancel_fee The pricing cancelation fee
currency The pricing currency

$options : array<string|int, mixed>

An array of stdClass objects representing all new service package options, each including:

id The option ID
label The option label
name The option name
type The option type
values An array of stdClass objects representing each option value, including:
- id The option value ID
- option_id The option ID
- value The option value
- min The minimum value
- max The maximum value
- step The step value
- pricing An array whose first index contains an stdClass object representing the option value pricing, including:
  - id The option value pricing ID
  - pricing_id The pricing ID
  - option_value_id The option value ID
  - term The pricing term
  - period The pricing period
  - price The option value price
  - setup_fee The option value setup fee
  - cancel_fee The option value cancelation fee
  - currency The option value currency

Return values

ServiceChangePresenter —

An instance of the ServiceChangePresenter

discounts()

Sets all discounts


    public
                    discounts(array<string|int, mixed> $discounts) : this

Parameters

$discounts : array<string|int, mixed>

A list of two arrays ('old' and 'new') each with stdClass objects representing each coupon that apply either before or after the service change, containing:

id The coupon ID
code The coupon code
used_qty The number of times the coupon has been used
max_qty The max number of coupon uses
start_date The date the coupon begins
end_date The date the coupon ends
status The coupon status
type The type of coupon as it applies to packages (exclusive, inclusive)
recurring 1 or 0, whether the coupon applies to recurring services
limit_recurring 1 or 0, whether the coupon limitations apply to recurring services
apply_package_options 1 or 0, whether the coupon applies to a service's package options
amounts An array of stdClass objects representing each coupon amount, containing:
- coupon_id The coupon ID
- currency The coupon amount currency
- amount The coupon amount
- type The coupon amount type (percent, amount)
packages An array of stdClass objects representing each assigned coupon package, containing:
- coupon_id The coupon ID
- package_id The assigned package ID

Return values

this

options()

Sets any key/value custom options


    public
                    options(array<string|int, mixed> $options) : this

Parameters

$options : array<string|int, mixed>

An array of custom options:

includeSetupFees (optional) true/false, whether to include applicable setup fees. Default false.
includeCancelFees (optional) true/false, whether to include applicable cancel fees. Default false.
applyDate* (optional) The effective date the items apply. Coupons only apply with respect to this date. Default now.
startDate* (optional) The effective date the service term begins. Services are dated from this startDate unless overridden by proration. Default now.
recur (optional) true/false, whether to treat the service as recurring, i.e., the service already exists and is renewing. May affect coupon discounts. Default false.
transfer (optional) 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.
renewal (optional) true/false, whether to use the renewal price or not, i.e., the service is a domain being renewed. May affect coupon discounts. Default false.
cycles (optional) The amount of term cycles the service will be renewed. Default 1
prorateStartDate* (optional) datetime stamp. If set, will prorate the service from this date to the prorateEndDate
prorateEndDate* (optional) datetime stamp. If set, will override the otherwise calculated prorate end date.
prorateEndDateData* (optional) datetime stamp. If set, will override the otherwise set prorateEndDate when included with the Service Change Presenter only. This is typically used to prorate a service from its current renew date to a new renew date by providing the new renew date here while the service's current renew date is the prorateEndDate.
config_options (optional) array, a list of the config options currently on a service which is having a price change calculated.
upgrade (optional) true/false, whether this price is being calculated for a package upgrade.
option_currency (optional, for service changes) The ISO 4217 3-character currency code to which option prices should be converted
service_currency (optional, for service changes) The ISO 4217 3-character currency code to which service prices should be converted

Return values

this

settings()

Sets a list of settings


    public
                    settings(array<string|int, mixed> $settings) : this

Parameters

$settings : array<string|int, mixed>: An array containing all client and company settings as key/value pairs

Return values

this

taxes()

Sets all tax rules


    public
                    taxes(array<string|int, mixed> $taxes) : this

Parameters

$taxes : array<string|int, mixed>

An array of stdClass objects representing each tax rule that applies, containing:

id The tax ID
company_id The company ID
level The tax level
name The name of the tax
amount The tax amount
type The tax type (inclusive, exclusive)
status The tax status

Return values

this

formatDiscounts()

Formats the discounts


    protected
                    formatDiscounts(DiscountFormatterInterface $formatter, ItemCollection $collection) : ItemCollection

Parameters

$formatter : DiscountFormatterInterface: The formatter
$collection : ItemCollection: The item collection to append formatted discounts to

Return values

ItemCollection —

A collection of Items

formatOptions()

Formats the options


    protected
                    formatOptions(ArrayFormatterInterface $formatter) : mixed

Parameters

$formatter : ArrayFormatterInterface: The formatter

Return values

mixed —

The formatter's output formatting

formatSettings()

Formats the settings


    protected
                    formatSettings(ArrayFormatterInterface $formatter) : mixed

Parameters

$formatter : ArrayFormatterInterface: The formatter

Return values

mixed —

The formatter's output formatting

formatTaxes()

Formats the taxes


    protected
                    formatTaxes(TaxFormatterInterface $formatter, ItemCollection $collection) : ItemCollection

Parameters

$formatter : TaxFormatterInterface: The formatter
$collection : ItemCollection: The item collection to append formatted taxes to

Return values

ItemCollection —

A collection of Items

getMeta()

Retrieves all meta information set on a meta item combined together


    protected
                    getMeta(MetaItemInterface $item) : array<string|int, mixed>

Parameters

$item : MetaItemInterface: The item whose meta information to retrieve

Return values

array<string|int, mixed> —

An array of all meta data

getMetaFromCollection()

Retrieves all meta information set on an item collection


    protected
                    getMetaFromCollection(ItemCollection $collection) : array<string|int, mixed>

Parameters

$collection : ItemCollection: An item collection

Return values

array<string|int, mixed> —

An array of all meta data

builderFactory()

Creates an instance of the BuilderFactory


    private
                    builderFactory() : BuilderFactory

Return values

BuilderFactory

combineDescription()

Combines two items via their meta data to determine a new description


    private
                    combineDescription([ItemCollection|null $oldMeta = null ][, ItemCollection|null $newMeta = null ]) : string

Parameters

$oldMeta : ItemCollection|null = null: The old meta data, or null
$newMeta : ItemCollection|null = null: The new meta data, or null

Return values

string —

The combined description

combineKeys()

Updates the given service data items to have the same keys as the service collection for items that match, and which can be combined.


    private
                    combineKeys(ItemPriceCollection $serviceCollection, ItemPriceCollection $serviceDataCollection) : ItemPriceCollection

Parameters

$serviceCollection : ItemPriceCollection
$serviceDataCollection : ItemPriceCollection

Return values

ItemPriceCollection —

The updated service data collection

combinePrice()

Combines two items via their prices and meta data to determine a new single price


    private
                    combinePrice(float $oldPrice, float $newPrice[, ItemCollection|null $oldMeta = null ][, ItemCollection|null $newMeta = null ]) : float

Parameters

$oldPrice : float: The subotatl price (excluding taxes, discounts) of the old item
$newPrice : float: The subtotal price (excluding taxes, discounts) of the new item
$oldMeta : ItemCollection|null = null: The old meta data, or null
$newMeta : ItemCollection|null = null: The new meta data, or null

Return values

float —

The new price

discountsContainType()

Determines whether any of the given discounts contains a discount of the given type


    private
                    discountsContainType(array<string|int, mixed> $discounts[, string $type = 'amount' ]) : bool

Parameters

$discounts : array<string|int, mixed>: An array of DiscountPrice objects
$type : string = 'amount': The type of discount type to look for (optional, default 'amount')

Return values

bool —

True if any of the given discount prices are of the given type, or false otherwise

getCombinedKey()

Retrieves the given $item's new key


    private
                    getCombinedKey(MetaItemInterface $item, array<string|int, mixed> $servicePackages, array<string|int, mixed> $serviceOptions) : string|null

Parameters

$item : MetaItemInterface

The item whose new key to retrieve

$servicePackages : array<string|int, mixed>

An array keyed by service IDs that each contain an array:

package_id The ID of the package
discounts An array of item discounts

$serviceOptions : array<string|int, mixed>

An array keyed by service IDs that each contain an array of option IDs, which also contains an array:

discounts An array of item discounts

Return values

string|null —

The new key

getKeys()

Hashes each collection's item keys in a key/value array


    private
                    getKeys(ItemPriceCollection $collection) : array<string|int, mixed>

Parameters

$collection : ItemPriceCollection

Return values

array<string|int, mixed> —

An array of each item key (and its state for meta items)

getOptionKey()

Retrieves the new item key to use for the given service option item


    private
                    getOptionKey(MetaItemInterface $item, int $optionId, array<string|int, mixed> $serviceOptions) : string

Parameters

$item : MetaItemInterface

The item whose new key to retrieve

$optionId : int

The ID of the package option representing this item

$serviceOptions : array<string|int, mixed>

An array keyed by service IDs that each contain an array of option IDs, which also contains an array:

discounts An array of item discounts

Return values

string —

The item's new key

getServiceKey()

Retrieves the new item key to use for the given service item


    private
                    getServiceKey(MetaItemInterface $item, array<string|int, mixed> $servicePackages) : string

Parameters

$item : MetaItemInterface

The item whose new key to retrieve

$servicePackages : array<string|int, mixed>

An array keyed by service IDs that each contain an array:

package_id The ID of the package
discounts An array of item discounts

Return values

string —

The item's new key

makeMetaItem()

Creates a new Item which can be added as meta to an ItemPrice


    private
                    makeMetaItem(array<string|int, mixed>|null $meta, string $state) : Item|null

Parameters

$meta : array<string|int, mixed>|null: The meta data
$state : string: The state field to set on the meta data

Return values

Item|null —

A new item with the given meta set, or null if no meta exists

metaItemsMatch()

Compares all discounts from $discounts1 with $discounts2 to check whether all discounts are present identically in both arguments


    private
                    metaItemsMatch(array<string|int, mixed> $item1, array<string|int, mixed> $item2) : bool

Parameters

$item1 : array<string|int, mixed>: An array of discount objects to compare
$item2 : array<string|int, mixed>: An array of discount objects to compare against

Return values

bool —

True if the arguments contain the same identical discounts, or false otherwise

pairCollections()

Pairs items in one collection with items in the other collection for all items that have no matching key (i.e. are not already paired). The paired items are 0-cost items.


    private
                    pairCollections(ItemPriceCollection $oldCollection, ItemPriceCollection $newCollection) : array<string|int, mixed>

Also updates the meta data to indicate the state of the pairing.

Parameters

$oldCollection : ItemPriceCollection: A collection
$newCollection : ItemPriceCollection: A collection

Return values

array<string|int, mixed> —

An array containing the old and new collections:

oldCollection The updated old collection
newCollection The updated new collection

removeFees()

Updates the collection to remove setup fees and cancel fees that shouldn't apply


    private
                    removeFees(ItemPriceCollection $collection) : ItemPriceCollection

Parameters

$collection : ItemPriceCollection: The collection

Return values

ItemPriceCollection —

The updated collection

removeUnchanged()

Updates the collection to remove items that have not changed


    private
                    removeUnchanged(ItemPriceCollection $collection) : ItemPriceCollection

Parameters

$collection : ItemPriceCollection: The collection

Return values

ItemPriceCollection —

The updated collection

serviceBuilder()

Creates an instance of the ServiceBuilder


    private
                    serviceBuilder() : ServiceBuilder

Return values

ServiceBuilder

serviceDataBuilder()

Creates an instance of the ServiceDataBuilder


    private
                    serviceDataBuilder() : ServiceDataBuilder

Return values

ServiceDataBuilder

updateMeta()

Updates the given MetaItemInterface to set the first meta item with the given data


    private
                    updateMeta(MetaItemInterface $item, array<string|int, mixed> $meta) : MetaItemInterface

Parameters

$item : MetaItemInterface: The item whose meta information to update
$meta : array<string|int, mixed>: The meta information to update the item with

Return values

MetaItemInterface —

The updated item