Blesta Source Documentation

Invoices extends AppModel

Invoice management

Table of Contents

Methods

__construct() Initialize Invoices
add() Creates a new invoice using the given data
addDelivery() Adds the invoice delivery status for the given invoice
addFromRecurring() Creates a new invoice if the given recurring invoice is set to be renewed
addRecurring() Creates a new recurring invoice using the given data
addRecurringDelivery() Adds the invoice delivery status for the given recurring invoice
amountDue() Calculates the client's amount due in the given currency. This sums all existing open invoices for the given currency.
appendServices() Edits an invoice to append a set of service IDs as line items
cacheExtensions() Returns an array of the supported cache extensions
clearCache() Clears the invoice cache
createFromServices() Creates an invoice from a set of services
createPayHash() Creates a Payment Hash that may be used to temporarily authenticate a user's access to pay an invoice, or invoices
createRenewalFromService() Creates a renewal invoice for a service
deleteByClient() Permanently deletes all invoices for the given client
deleteDelivery() Removes the invoice delivery record
deleteDraft() Permanently deletes a draft invoice
deleteRecurring() Permanently removes a recurring invoice from the system
deleteRecurringByClient() Permanently deletes all recurring invoices for the given client
deleteRecurringDelivery() Removes the recurring invoice delivery record
delivered() Marks the delivery status as sent
edit() Updates an invoice using the given data. If a new line item is added, or the quantity, unit cost, or tax status of an item is updated the latest tax rules will be applied to this invoice.
editRecurring() Updates a recurring invoice using the given data. If a new line item is added, or the quantity, unit cost, or tax status of an item is updated the latest tax rules will be applied to this invoice.
fetchCache() Fetch a cached invoice
get() Fetches the given invoice
getAll() Fetches all invoices for a client
getAllAutodebitableInvoices() Fetches all invoices for this company that are autodebitable by their respective clients
getAllDelivery() Fetches all invoice delivery records assigned to each of the given invoice IDs
getAllRecurring() Fetches all recurring invoices for a client
getAllRenewingRecurring() Fetches all renewing recurring invoices. That is, where the date_renews is <= current date + the maximum invoice days before renewal for the current client group and the recurring invoice has not already created all invoices to be created.
getAllWithService() Fetches all invoices that contain the given service
getAutodebitDate() Retrieves the date that the given invoice should be autodebited. This considers current client settings and autodebit accounts.
getCacheMethods() Fetches the available invoice cache methods
getDataPresenter() Retrieves a presenter representing a set of items and taxes for invoice data
getDelivery() Fetches all invoice delivery methods this invoice is assigned
getDeliveryList() Fetches a list of invoice deliveries for the currently active company
getDeliveryListCount() Retrieves the total number of invoice deliveries for the currently active company
getDeliveryMethods() Fetches all invoice delivery methods that are supported or enabled for this company
getItemTotals() Retrieves a list of items and their totals
getLineItems() Fetches all line items belonging to the given invoice
getList() Fetches a list of invoices for a client
getListCount() Returns the total number of invoices returned from Invoices::getClientList(), useful in constructing pagination for the getList() method.
getMeta() Fetches the meta fields for this invoice.
getPaid() Calculates the total paid on the given invoice ID
getPresenter() Retrieves a presenter representing a set of items and taxes for the invoice
getPricingPeriods() Retrieves a list of recurring invoice periods
getRecurring() Fetches the given recurring invoice
getRecurringCount() Retrieves the number of recurring invoices for the given client
getRecurringDelivery() Fetches all invoice delivery methods this recurring invoice is assigned
getRecurringFromInvoices() Fetches the recurring invoice record that produced the given invoice ID
getRecurringInfo() Evaluates the given invoice, performs necessary looks ups to determine if the invoice is for a recurring invoice or service. Returns the term and period for the recurring invoice or service.
getRecurringLineItems() Fetches all line items belonging to the given recurring invoice
getRecurringList() Fetches a list of recurring invoices for a client
getRecurringListCount() Return the total number of recurring invoices returned from Invoices::getRecurringList(), useful in constructing pagination for the getList() method.
getSearchCount() Return the total number of invoices returned from Invoices::search(), useful in constructing pagination
getStatusCount() Retrieves the number of invoices given an invoice status for the given client
getStatuses() Retrieves a list of invoice statuses and language
getSubtotal() Calculates the subtotal of the given invoice ID
getTaxRules() Retrieves all active tax rules that apply to the given client
getTaxRulesByLocation() Retrieves all active tax rules that apply to the given company and location
getTaxTotals() Calculates the amount of tax for each tax rule given that applies to the given line sub total (which is unit cost * quantity).
getTotal() Calculates the total (subtotal + tax) of the given invoice ID
getTypes() Fetches the available invoice types
invoicedCurrencies() Returns an array of all currency the given client has been invoiced in
isInstanceOf() Checks if the given $field is a reference of $class
makeLinesFromItems() Creates a list of line items from the given set of items, discounts, and taxes
merge() Merge multiples open invoices in to a single invoice
primeQuantity() Converts quantity to a float, if no qty is set, a value of 1 is assumed.
search() Search invoices
setClosed() Sets the invoice to closed if the invoice has been paid in full, otherwise removes any closed status previously set on the invoice. Only invoices with status of 'active' can be closed.
setMeta() Sets meta data for the given invoice
split() Splits an invoice in two separate invoices
unsetMeta() Deletes any meta on the given invoice ID
updateCache() Updates an invoice on cache
validateAmountApplied() Checks if the given invoice has any payments applied to it
validateDateDueAfterDateBilled() Validates that the given date due is on or after the date billed
validateDeliveryMethods() Validates that the delivery options match the available set
validateDuration() Validates the recurring invoice duration
validateIsDraft() Validates that the given invoice is a draft invoice
validatePeriod() Validates the recurring invoice period
validateStatus() Validates the invoice 'status' field
verifyPayHash() Verifies the Payment Hash is valid
writeCache() Writes an invoice on cache
addLine() Adds a line item to an existing invoice
addLineTax() Adds a new line item tax
deleteLine() Permanently removes an invoice line item and its corresponding line item taxes
deleteLineTax() Permanently removes an invoice line item's tax rule
deleteRecurringLine() Permanently removes a recurring invoice line item
getClientSettingSubquery() Gets a partial record for a subquery fetching client settings
getCurrencyPrecision() Retrieves the decimal precision for the given currency
getDiscountPrices() Builds a list of DiscountPrice objects from the given discounts
getInvoice() Partially constructs the query required by Invoices::get() and others
getInvoiceDeliveries() Partially constructs a Record object for fetching invoice deliveries
getInvoices() Partially constructs the query required by Invoices::getList() and Invoices::getListCount()
getLines() Retrieves the line items for the given invoice
getLinesForServices() Generates the line items for a given set of service IDs.
getLineTaxes() Fetches all tax info attached to the line item
getMergeRules() Returns the rule set for merging existing invoices
getNextInvoiceVars() Updates $vars with the subqueries to properly set the previous_due, id_format, and id_value fields when creating an invoice or converting a draft or profroma to an active invoice
getPreviousDue() Retrieves the previous due amount for the given client in the given currency
getRecurringInvoice() Partially constructs the query required by Invoices::getRecurring() and others
getRecurringInvoices() Partially constructs the query required by both Invoices::getRecurringList() and Invoices::getRecurringListCount()
getRecurringRules() Returns the rule set for adding/editing recurring invoices
getRecurringTaxes() Fetches all taxes for the given recurring invoice
getRules() Returns the rule set for adding/editing invoices
getTaxes() Fetches all taxes for the given invoice
getTaxPrices() Builds a list of TaxPrice objects from the given taxes
getTotals() Retrieves the totals for an invoice
itemCollectionDiscounts() Retrieves a list of all discounts on a collection
itemCollectionItems() Retrieves a list of all item prices in a collection
itemCollectionTaxes() Retrieves a list of all taxes on a collection
lineItemsChanged() Checks whether the line items for an invoice are being altered
makeInvoice() Performs a validation check on the set input rules and attempts to create an invoice
makeItemCollection() Creates an ItemPriceCollection from the given items, discounts, and taxes
makeLineItem() Creates an array representing a single line item
makeLinesBackwardCompatible() Adds deprecated tax information to each line item
pricingFactory() Retrieves an instance of the PricingFactory
requeueClosedInvoiceForDelivery() Requeues a closed invoice for email delivery if the setting is enabled
requeueForDelivery() Requeues an invoice to be delivered again using all methods from which it has already been delivered, so long as those delivery methods are still available
searchInvoices() Partially constructs the query for searching invoices
taxUpdateRequired() Identifies whether or not the given invoice with its updated line items and deleted items requires tax rules to be updated when saved. This method doesn't check whether the tax rules have been updated, just whether the invoice has been changed such that the updated tax rules would need to be updated. There's no consequence in updating tax when the tax rules have not changed.
updateTotals() Calculates and updates the stored subtotal, total, and amount paid values for the given invoice
Methods

__construct()

Initialize Invoices

public __construct() : mixed

add()

Creates a new invoice using the given data

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

An array of invoice data including:

  • client_id The client ID the invoice belongs to
  • date_billed The date the invoice goes into effect
  • date_due The date the invoice is due
  • date_closed The date the invoice was closed
  • date_autodebit The date the invoice should be autodebited
  • status 'active','draft','proforma', or 'void'
  • currency The ISO 4217 3-character currency code of the invoice
  • note_public Notes visible to the client
  • note_private Notes visible only to staff members
  • lines A numerically indexed array of line item info including:
    • service_id The service ID attached to this line item (optional)
    • description The line item description
    • qty The quantity for this line item (min. 1)
    • amount The unit cost (cost per quantity) for this line item
    • tax Whether or not to tax the line item
  • term The term for the recurring invoice as an integer 1-65535, if blank will not be considered for a recurring invoice
  • period The period for the recurring invoice ('day', 'week', 'month', 'year')
  • duration The duration of the recurring invoice ('indefinitely' for forever or 'times' for a set number of times)
  • duration_time The number of times an invoice should recur
  • recur_date_billed The date the next invoice will be created
  • delivery A numerically indexed array of delivery methods
Return values
int —

The invoice ID, void on error

addDelivery()

Adds the invoice delivery status for the given invoice

public addDelivery(int $invoice_id, array<string|int, mixed> $vars, int $client_id) : int
Parameters
$invoice_id : int

The ID of the invoice to update delivery status for

$vars : array<string|int, mixed>

An array of invoice delivery information including:

  • method The delivery method
$client_id : int

The ID of the client to add the delivery method under

Return values
int —

The invoice delivery ID, void on error

addFromRecurring()

Creates a new invoice if the given recurring invoice is set to be renewed

public addFromRecurring(int $invoice_recur_id[, array<string|int, mixed> $client_settings = null ]) : bool
Parameters
$invoice_recur_id : int

The recurring invoice ID

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

A list of client settings belonging to this invoice's client (optional)

Return values
bool —

True if any invoices were created from this recurring invoice, false otherwise

addRecurring()

Creates a new recurring invoice using the given data

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

An array of invoice data including:

  • client_id The client ID the invoice belongs to
  • term The term as an integer 1-65535 (optional, default 1)
  • period The period, 'day', 'week', 'month', 'year'
  • duration The number of times this invoice will recur or null to recur indefinitely
  • date_renews The date the next invoice will be created
  • currency The currency this invoice is created in
  • note_public Notes visible to the client
  • note_private Notes visible only to staff members
  • lines A numerically indexed array of line item info including:
    • description The line item description
    • qty The quantity for this line item (min. 1)
    • amount The unit cost (cost per quantity) for this line item
    • tax Whether or not to tax the line item
  • delivery A numerically indexed array of delivery methods
Return values
int —

The recurring invoice ID, void on error

addRecurringDelivery()

Adds the invoice delivery status for the given recurring invoice

public addRecurringDelivery(int $invoice_recur_id, array<string|int, mixed> $vars, int $client_id) : int
Parameters
$invoice_recur_id : int

The ID of the recurring invoice to update delivery status for

$vars : array<string|int, mixed>

An array of invoice delivery information including:

  • method The delivery method
$client_id : int

The ID of the client to add the delivery method under

Return values
int —

The recurring invoice delivery ID, void on error

amountDue()

Calculates the client's amount due in the given currency. This sums all existing open invoices for the given currency.

public amountDue(int $client_id, string $currency[, string $status = 'open' ]) : float
Parameters
$client_id : int

The client ID to calculate on

$currency : string

The ISO 4217 3-character currency code

$status : string = 'open'

The status type of the invoices whose amount due to fetch (optional, default 'open') one of the following:

  • open Fetches all active open invoices
  • closed Fetches all closed invoices
  • past_due Fetches all active past due invoices
  • draft Fetches all invoices with a status of "draft"
  • void Fetches all invoices with a status of "void"
  • active Fetches all invoices with a status of "active"
  • proforma Fetches all invoices with a status of "proforma"
  • to_autodebit Fetches all invoices that are ready to be autodebited now, and which can be with an active client and payment account to do so
  • pending_autodebit Fetches all invoice that are set to be autodebited in the future, and which have an active client and payment account to do so with
  • to_print Fetches all paper invoices set to be printed
  • printed Fetches all paper invoices that have been set as printed
  • pending Fetches all active invoices that have not been billed for yet
  • to_deliver Fetches all invoices set to be delivered by a method other than paper (i.e. deliverable invoices not in the list of those "to_print")
  • all Fetches all invoices
Return values
float —

The amount due

appendServices()

Edits an invoice to append a set of service IDs as line items

public appendServices(int $invoice_id, array<string|int, mixed> $service_ids) : int
Parameters
$invoice_id : int

The ID of the invoice to append to

$service_ids : array<string|int, mixed>

A numerically-indexed array of service IDs to generate line items from

Return values
int —

$invoice_id The ID of the invoice updated

cacheExtensions()

Returns an array of the supported cache extensions

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

A numerically indexed array, with the supported extensions

clearCache()

Clears the invoice cache

public clearCache(int $invoice_id[, string $extension = 'json' ][, string $language = null ]) : bool
Parameters
$invoice_id : int

The ID of the invoice to clear

$extension : string = 'json'

The cache extension (optional, 'json' by default)

$language : string = null

The language of the invoice to clear (optional)

Return values
bool —

True if the invoice cache has been deleted successfully, false otherwise

createFromServices()

Creates an invoice from a set of services

public createFromServices(int $client_id, array<string|int, mixed> $service_ids, string $currency, string $due_date[, bool $allow_pro_rata = true ][, bool $services_renew = false ][, array<string|int, mixed> $service_transfers = [] ][, int $term_cycles = 1 ]) : int
Parameters
$client_id : int

The ID of the client to create the invoice for

$service_ids : array<string|int, mixed>

A numerically-indexed array of service IDs to generate line items from

$currency : string

The currency code to use to generate the invoice

$due_date : string

The date the invoice is to be due

$allow_pro_rata : bool = true

True to allow the services to be priced considering the package pro rata details, or false otherwise (optional, default true)

$services_renew : bool = false

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

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

A numerically-indexed array of service IDs that are being transferred

$term_cycles : int = 1

The amount of terms to bill (optional, default 1)

Return values
int —

$invoice_id The ID of the invoice generated

createPayHash()

Creates a Payment Hash that may be used to temporarily authenticate a user's access to pay an invoice, or invoices

public createPayHash(int $client_id, int $invoice_id) : string
Parameters
$client_id : int

The client ID to create the hash for

$invoice_id : int

The ID of the invoice to create the hash for (if null will allow the hash to work for any invoice belonging to the client)

Return values
string —

A hash built based upon the parameters provided

createRenewalFromService()

Creates a renewal invoice for a service

public createRenewalFromService(int $service_id[, int $term_cycles = 1 ][, int $pricing_id = null ]) : int
Parameters
$service_id : int

The service ID to generate the renewal invoice

$term_cycles : int = 1

The amount of terms to renew the service (optional, default 1)

$pricing_id : int = null

The pricing ID to be used the renewal of the service, if not provided service will be renewed on the current pricing

Return values
int —

$invoice_id The ID of the invoice generated

deleteByClient()

Permanently deletes all invoices for the given client

public deleteByClient(int $client_id) : mixed
Parameters
$client_id : int

The ID of the client whose invoices to purge

deleteDelivery()

Removes the invoice delivery record

public deleteDelivery(int $invoice_delivery_id) : mixed
Parameters
$invoice_delivery_id : int

The ID of the delivery item to delete

deleteDraft()

Permanently deletes a draft invoice

public deleteDraft(int $invoice_id) : mixed
Parameters
$invoice_id : int

The invoice ID of the draft invoice to delete

deleteRecurring()

Permanently removes a recurring invoice from the system

public deleteRecurring(int $invoice_recur_id) : mixed
Parameters
$invoice_recur_id : int

The ID of the recurring invoice to delete

deleteRecurringByClient()

Permanently deletes all recurring invoices for the given client

public deleteRecurringByClient(int $client_id) : mixed
Parameters
$client_id : int

The ID of the client whose recurring invoices to purge

deleteRecurringDelivery()

Removes the recurring invoice delivery record

public deleteRecurringDelivery(int $invoice_delivery_id) : mixed
Parameters
$invoice_delivery_id : int

The ID of the recurring delivery item to delete

delivered()

Marks the delivery status as sent

public delivered(int $invoice_delivery_id[, int $company_id = null ]) : mixed
Parameters
$invoice_delivery_id : int

The ID of the delivery item to mark as sent

$company_id : int = null

The ID of the company whose invoice to mark delivered. Invoices not belonging to the given company will be ignored (optional, default null to not check the invoice company)

edit()

Updates an invoice using the given data. If a new line item is added, or the quantity, unit cost, or tax status of an item is updated the latest tax rules will be applied to this invoice.

public edit(int $invoice_id, array<string|int, mixed> $vars) : int
Parameters
$invoice_id : int

The ID of the invoice to update

$vars : array<string|int, mixed>

An array of invoice data (all optional unless noted otherwise) including:

  • client_id The client ID the invoice belongs to
  • date_billed The date the invoice goes into effect
  • date_due The date the invoice is due
  • date_closed The date the invoice was closed
  • date_autodebit The date the invoice should be autodebited
  • status 'active','draft','proforma', or 'void'
  • currency The ISO 4217 3-character currency code of the invoice
  • note_public Notes visible to the client
  • note_private Notes visible only to staff members
  • lines A numerically indexed array of line item info including:
    • id The ID for this line item (required to update, else will add as new)
    • service_id The service ID attached to this line item
    • description The line item description (if empty, along with amount, will delete line item)
    • qty The quantity for this line item (min. 1)
    • amount The unit cost (cost per quantity) for this line item (if empty, along with description, will delete line item)
    • tax Whether or not to tax the line item
  • term If editing a draft, the term for the recurring invoice as an integer 1-65535, if blank will not be considered for a recurring invoice
  • period If editing a draft, the period for the recurring invoice ('day', 'week', 'month', 'year')
  • duration If editing a draft, the duration of the recurring invoice ('indefinitely' for forever or 'times' for a set number of times)
  • duration_time If editing a draft, the number of times an invoice should recur
  • recur_date_billed If editing a draft, the date the next invoice will be created
  • delivery A numerically indexed array of delivery methods
Return values
int —

The invoice ID, void on error

editRecurring()

Updates a recurring invoice using the given data. If a new line item is added, or the quantity, unit cost, or tax status of an item is updated the latest tax rules will be applied to this invoice.

public editRecurring(int $invoice_recur_id, array<string|int, mixed> $vars) : int
Parameters
$invoice_recur_id : int

The ID of the recurring invoice to update

$vars : array<string|int, mixed>

An array of invoice data (all optional) including:

  • client_id The client ID the recurring invoice belongs to
  • term The term as an integer 1-65535 (optional, default 1)
  • period The period, 'day', 'week', 'month', 'year'
  • duration The number of times this invoice will recur or null to recur indefinitely
  • date_renews The date the next invoice will be created
  • date_last_renewed The date the last invoice was created (optional) - not recommended to overwrite this value
  • currency The currency this invoice is created in
  • note_public Notes visible to the client
  • note_private Notes visible only to staff members
  • lines A numerically indexed array of line item info including:
    • id The ID for this line item (required to update, else will add as new)
    • description The line item description (if empty, along with amount, will delete line item)
    • qty The quantity for this line item (min. 1)
    • amount The unit cost (cost per quantity) for this line item (if empty, along with description, will delete line item)
    • tax Whether or not to tax the line item
  • delivery A numerically indexed array of delivery methods
Return values
int —

The recurring invoice ID, void on error

fetchCache()

Fetch a cached invoice

public fetchCache(int $invoice_id[, string $extension = 'json' ][, string $language = null ]) : mixed
Parameters
$invoice_id : int

The ID of the invoice to fetch

$extension : string = 'json'

The cache extension (optional, 'json' by default)

$language : string = null

The language of the invoice to fetch (optional)

Return values
mixed —

An object containing the invoice data for JSON, a stream of binary data for PDF and false on error

get()

Fetches the given invoice

public get(int $invoice_id[, mixed $use_cache = false ]) : mixed

since v4.6.0 - The properties of some data returned by this method are deprecated:

  • line_items
    • taxes_applied
    • tax_subtotal
    • tax_total
    • total
    • total_w_tax
Parameters
$invoice_id : int

The ID of the invoice to fetch

$use_cache : mixed = false
Return values
mixed —

A stdClass object containing invoice information, false if no such invoice exists

getAll()

Fetches all invoices for a client

public getAll([int $client_id = null ][, string $status = 'open' ][, array<string|int, mixed> $order_by = ['date_due' => 'ASC'] ][, string $currency = null ]) : array<string|int, mixed>
Parameters
$client_id : int = null

The client ID (optional, default null to get invoices for all clients)

$status : string = 'open'

The status type of the invoices to fetch (optional, default 'open') one of the following:

  • open Fetches all active open invoices
  • closed Fetches all closed invoices
  • past_due Fetches all active past due invoices
  • draft Fetches all invoices with a status of "draft"
  • void Fetches all invoices with a status of "void"
  • active Fetches all invoices with a status of "active"
  • proforma Fetches all invoices with a status of "proforma"
  • to_autodebit Fetches all invoices that are ready to be autodebited now, and which can be with an active client and payment account to do so
  • pending_autodebit Fetches all invoice that are set to be autodebited in the future, and which have an active client and payment account to do so with
  • to_print Fetches all paper invoices set to be printed
  • printed Fetches all paper invoices that have been set as printed
  • pending Fetches all active invoices that have not been billed for yet
  • to_deliver Fetches all invoices set to be delivered by a method other than paper (i.e. deliverable invoices not in the list of those "to_print")
  • all Fetches all invoices
$order_by : array<string|int, mixed> = ['date_due' => 'ASC']

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

$currency : string = null

The currency code to limit results on (null = any currency)

Return values
array<string|int, mixed> —

An array of stdClass objects containing invoice information

getAllAutodebitableInvoices()

Fetches all invoices for this company that are autodebitable by their respective clients

public getAllAutodebitableInvoices(int $client_group_id[, bool $pending = false ][, string $days = 'autodebit_days_before_due' ]) : array<string|int, mixed>
Parameters
$client_group_id : int

The client group ID

$pending : bool = false

True to fetch all invoices that will be ready to autodebit in the future, or false to fetch all invoices ready to be autodebited (optional, default false)

$days : string = 'autodebit_days_before_due'

The number of days before invoices are to be autodebited:

  • autodebit_days_before_due Use the autodebit days before due setting
  • notice_pending_autodebit Use the autodebit days before due setting plus the notice pending autodebit setting
Return values
array<string|int, mixed> —

An array of client IDs, each containing an array of stdClass objects representing invoice information

getAllDelivery()

Fetches all invoice delivery records assigned to each of the given invoice IDs

public getAllDelivery([array<string|int, mixed> $invoice_ids = null ][, string $delivery_method = null ][, string $status = 'all' ]) : array<string|int, mixed>
Parameters
$invoice_ids : array<string|int, mixed> = null

A list of invoice IDs (optional)

$delivery_method : string = null

The delivery method to filter by (e.g. "email"), (optional)

$status : string = 'all'

The delivery status, either "all" for all, "unsent" for deliveries not marked sent, or "sent" for deliveries marked sent (optional, default "all")

Return values
array<string|int, mixed> —

An array of stdClass objects containing invoice delivery log information

getAllRecurring()

Fetches all recurring invoices for a client

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

The client ID (optional, default null to get recurring invoices for all clients)

Return values
array<string|int, mixed> —

An array of stdClass objects containing recurring invoice information

getAllRenewingRecurring()

Fetches all renewing recurring invoices. That is, where the date_renews is <= current date + the maximum invoice days before renewal for the current client group and the recurring invoice has not already created all invoices to be created.

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

The ID of the client group whose renewing recurring invoices to fetch

Return values
array<string|int, mixed> —

An array of stdClass objects, each representing a recurring invoice

getAllWithService()

Fetches all invoices that contain the given service

public getAllWithService(int $service_id[, int $client_id = null ][, string $status = 'open' ][, array<string|int, mixed> $order_by = ['date_due' => 'ASC'] ]) : mixed
Parameters
$service_id : int

The ID of the service whose invoices to fetch

$client_id : int = null

The client ID (optional, default null to get invoices for all clients)

$status : string = 'open'

The status type of the invoices to fetch (optional, default 'open') one of the following:

  • open Fetches all active open invoices
  • closed Fetches all closed invoices
  • past_due Fetches all active past due invoices
  • draft Fetches all invoices with a status of "draft"
  • void Fetches all invoices with a status of "void"
  • active Fetches all invoices with a status of "active"
  • proforma Fetches all invoices with a status of "proforma"
  • to_autodebit Fetches all invoices that are ready to be autodebited now, and which can be with an active client and payment account to do so
  • pending_autodebit Fetches all invoice that are set to be autodebited in the future, and which have an active client and payment account to do so with
  • to_print Fetches all paper invoices set to be printed
  • printed Fetches all paper invoices that have been set as printed
  • pending Fetches all active invoices that have not been billed for yet
  • to_deliver Fetches all invoices set to be delivered by a method other than paper (i.e. deliverable invoices not in the list of those "to_print")
  • all Fetches all invoices
$order_by : array<string|int, mixed> = ['date_due' => 'ASC']

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

getAutodebitDate()

Retrieves the date that the given invoice should be autodebited. This considers current client settings and autodebit accounts.

public getAutodebitDate(int $invoice_id) : mixed
Parameters
$invoice_id : int

The ID of the invoice

Return values
mixed —

A string representing the UTC date that this invoice will be autodebited, or false if the invoice cannot be autodebited

getCacheMethods()

Fetches the available invoice cache methods

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

A key/value array of invoice types

getDataPresenter()

Retrieves a presenter representing a set of items and taxes for invoice data

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

The ID of the client the invoice data is for

$vars : array<string|int, mixed>

An array of input representing the new invoice data

  • date_billed The date the invoice is to be billed
  • date_due The date the invoice is to be due
  • autodebit 1 or 0, whether or not the invoice can be autodebited
  • status The invoice status (e.g. 'active')
  • currency The ISO 4217 3-character currency code
  • lines A numerically-indexed array of arrays, each representing a line item
    • service_id The ID of the service this line item correlates to, if any
    • description The line item description
    • qty The line item quantity
    • amount The line item unit cost
    • tax "true" if the line item is taxable
Return values
InvoiceDataPresenter —

The presenter

getDelivery()

Fetches all invoice delivery methods this invoice is assigned

public getDelivery(int $invoice_id[, bool $sent = null ]) : array<string|int, mixed>
Parameters
$invoice_id : int

The ID of the invoice

$sent : bool = null

True to get only invoice delivery records that have been sent, or false to get only delivery records that have not been sent (optional, defaults to fetch all)

Return values
array<string|int, mixed> —

An array of stdClass objects containing invoice delivery log information

getDeliveryList()

Fetches a list of invoice deliveries for the currently active company

public getDeliveryList([string $method = null ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_sent' => 'DESC'] ][, array<string|int, mixed> $filters = [] ]) : mixed
Parameters
$method : string = null

The delivery method to filter by (optional, default null for all)

$page : int = 1

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

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

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

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

A list of parameters to filter by, including:

  • string The (partial) string on which to filter logs
  • start_date The start date on which to filter logs
  • end_date The end date on which to filter logs

getDeliveryListCount()

Retrieves the total number of invoice deliveries for the currently active company

public getDeliveryListCount([string $method = null ][, array<string|int, mixed> $filters = [] ]) : int
Parameters
$method : string = null

The delivery method to filter by (optional, default null for all)

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

A list of parameters to filter by, including:

  • string The (partial) string on which to filter logs
  • start_date The start date on which to filter logs
  • end_date The end date on which to filter logs
Return values
int —

The total number of invoice deliveries

getDeliveryMethods()

Fetches all invoice delivery methods that are supported or enabled for this company

public getDeliveryMethods([int $client_id = null ][, int $client_group_id = null ][, bool $enabled = true ]) : array<string|int, mixed>
Parameters
$client_id : int = null

The ID of the client to fetch the delivery methods for

$client_group_id : int = null

The ID of the client group to fetch the delivery methods for if $client_id is not given

$enabled : bool = true

If true, will only return delivery methods that are enabled for this company, else all supported methods are returned

Return values
array<string|int, mixed> —

An array of delivery methods in key/value pairs

getItemTotals()

Retrieves a list of items and their totals

public getItemTotals(array<string|int, mixed> $items[, array<string|int, mixed> $discounts = [] ][, array<string|int, mixed> $taxes = [] ]) : array<string|int, mixed>

since 4.0.0 - Use Blesta\Core\Pricing...

Parameters
$items : array<string|int, mixed>

An array of items including:

  • price The unit price of the item
  • qty The item quantity (optional, default 1)
  • description The item description (optional)
$discounts : array<string|int, mixed> = []

An array of applicable discounts including (optional):

  • amount The discount amount
  • type The discount type ('amount' or 'percent')
  • description The discount description (optional)
  • apply An array of item indexes to which the discount applies (optional, defaults to all)
$taxes : array<string|int, mixed> = []

An array containing arrays of applicable taxes where each array group represents taxes to cascade on each other; including (optional):

  • amount The tax amount
  • type The tax type ('exclusive' or 'inclusive')
  • description The tax description (optional)
  • apply An array of item indexes to which the tax applies (optional, defaults to all)
Return values
array<string|int, mixed> —

An array containing:

  • items An array of items and pricing information about each item
  • totals An array of pricing information about all items
  • discounts An array of discounts
  • taxes An array of taxes

getLineItems()

Fetches all line items belonging to the given invoice

public getLineItems(int $invoice_id[, mixed $use_cache = false ]) : array<string|int, mixed>

since v4.6.0 - The properties of some data returned by this method are deprecated:

  • taxes_applied
  • tax_subtotal
  • tax_total
  • total
  • total_w_tax
Parameters
$invoice_id : int

The ID of the invoice to fetch line items for

$use_cache : mixed = false
Return values
array<string|int, mixed> —

An array of stdClass objects each representing a line item

getList()

Fetches a list of invoices for a client

public getList([int $client_id = null ][, string $status = 'open' ][, int $page = 1 ][, array<string|int, mixed> $order_by = ['date_due' => 'ASC'] ][, array<string|int, mixed> $filters = [] ]) : array<string|int, mixed>
Parameters
$client_id : int = null

The client ID (optional, default null to get invoices for all clients)

$status : string = 'open'

The status type of the invoices to fetch (optional, default 'open') one of the following:

  • open Fetches all active open invoices
  • closed Fetches all closed invoices
  • past_due Fetches all active past due invoices
  • draft Fetches all invoices with a status of "draft"
  • void Fetches all invoices with a status of "void"
  • active Fetches all invoices with a status of "active"
  • proforma Fetches all invoices with a status of "proforma"
  • to_autodebit Fetches all invoices that are ready to be autodebited now, and which can be with an active client and payment account to do so
  • pending_autodebit Fetches all invoice that are set to be autodebited in the future, and which have an active client and payment account to do so with
  • to_print Fetches all paper invoices set to be printed
  • printed Fetches all paper invoices that have been set as printed
  • pending Fetches all active invoices that have not been billed for yet
  • to_deliver Fetches all invoices set to be delivered by a method other than paper (i.e. deliverable invoices not in the list of those "to_print")
  • all Fetches all invoices
$page : int = 1

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

$order_by : array<string|int, mixed> = ['date_due' => 'ASC']

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

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

A list of parameters to filter by, including:

  • invoice_number The invoice number on which to filter invoices
  • currency The currency code on which to filter invoices
  • invoice_line The (partial) description of the invoice line on which to filter invoices
Return values
array<string|int, mixed> —

An array of stdClass objects containing invoice information, or false if no invoices exist

getListCount()

Returns the total number of invoices returned from Invoices::getClientList(), useful in constructing pagination for the getList() method.

public getListCount([int $client_id = null ][, string $status = 'open' ][, array<string|int, mixed> $filters = [] ]) : int
Parameters
$client_id : int = null

The client ID (optional, default null to get invoice count for all clients)

$status : string = 'open'

The status type of the invoices to fetch (optional, default 'open') one of the following:

  • open Fetches all active open invoices
  • closed Fetches all closed invoices
  • past_due Fetches all active past due invoices
  • draft Fetches all invoices with a status of "draft"
  • void Fetches all invoices with a status of "void"
  • active Fetches all invoices with a status of "active"
  • proforma Fetches all invoices with a status of "proforma"
  • to_autodebit Fetches all invoices that are ready to be autodebited now, and which can be with an active client and payment account to do so
  • pending_autodebit Fetches all invoice that are set to be autodebited in the future, and which have an active client and payment account to do so with
  • to_print Fetches all paper invoices set to be printed
  • printed Fetches all paper invoices that have been set as printed
  • pending Fetches all active invoices that have not been billed for yet
  • to_deliver Fetches all invoices set to be delivered by a method other than paper (i.e. deliverable invoices not in the list of those "to_print")
  • all Fetches all invoices
$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • invoice_number The invoice number on which to filter invoices
  • currency The currency code on which to filter invoices
  • invoice_line The (partial) description of the invoice line on which to filter invoices
Tags
see
Invoices::getList()
Return values
int —

The total number of invoices

getMeta()

Fetches the meta fields for this invoice.

public getMeta(int $invoice_id[, string $key = null ]) : mixed
Parameters
$invoice_id : int

The invoice ID to fetch meta data for

$key : string = null

The key to fetch if fetching only a single meta field, null to fetch all meta fields

Return values
mixed —

An array of stdClass objects if fetching all meta data, a stdClass object if fetching a specific meta field, boolean false if fetching a specific meta field that does not exist

getPaid()

Calculates the total paid on the given invoice ID

public getPaid(int $invoice_id) : float
Parameters
$invoice_id : int

The ID of the invoice to calculate the total paid on

Return values
float —

The total paid on the invoice

getPresenter()

Retrieves a presenter representing a set of items and taxes for the invoice

public getPresenter(int $invoice_id) : bool|InvoicePresenter
Parameters
$invoice_id : int

The ID of the invoice whose pricing to fetch

Return values
bool|InvoicePresenter —

The presenter, otherwise false

getPricingPeriods()

Retrieves a list of recurring invoice periods

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

Key=>value pairs of recurring invoice pricing periods

getRecurring()

Fetches the given recurring invoice

public getRecurring(int $invoice_recur_id) : mixed
Parameters
$invoice_recur_id : int

The ID of the recurring invoice to fetch

Return values
mixed —

A stdClass object containing recurring invoice information, false if no such recurring invoice exists

getRecurringCount()

Retrieves the number of recurring invoices for the given client

public getRecurringCount([int $client_id = null ][, array<string|int, mixed> $filters = [] ]) : int
Parameters
$client_id : int = null

The client ID (optional, default null to get recurring invoice count for company)

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

A list of parameters to filter by, including:

  • invoice_number The invoice number on which to filter invoices
  • currency The currency code on which to filter invoices
  • invoice_line The (partial) description of the invoice line on which to filter invoices
Return values
int —

The number of recurring invoices for $client_id

getRecurringDelivery()

Fetches all invoice delivery methods this recurring invoice is assigned

public getRecurringDelivery(int $invoice_recur_id) : array<string|int, mixed>
Parameters
$invoice_recur_id : int

The ID of the recurring invoice

Return values
array<string|int, mixed> —

An array of stdClass objects containing invoice delivery log information

getRecurringFromInvoices()

Fetches the recurring invoice record that produced the given invoice ID

public getRecurringFromInvoices(int $invoice_id) : mixed
Parameters
$invoice_id : int

The ID of the invoice created by a recurring invoice

Return values
mixed —

A stdClass object representing the recurring invoice, false if no such recurring invoice exists or the invoice was not created from a recurring invoice

getRecurringInfo()

Evaluates the given invoice, performs necessary looks ups to determine if the invoice is for a recurring invoice or service. Returns the term and period for the recurring invoice or service.

public getRecurringInfo(int $invoice_id) : mixed
Parameters
$invoice_id : int

The ID of the invoice

Return values
mixed —

boolean false if the invoice is not for a recurring service or invoice, otherwise an array of recurring info including:

  • amount The amount to recur
  • term The term to recur
  • period The recurring period (day, week, month, year, onetime) used in conjunction with term in order to determine the next recurring payment

getRecurringLineItems()

Fetches all line items belonging to the given recurring invoice

public getRecurringLineItems(int $invoice_recur_id) : array<string|int, mixed>
Parameters
$invoice_recur_id : int

The ID of the recurring invoice to fetch line items for

Return values
array<string|int, mixed> —

An array of stdClass objects each representing a line item

getRecurringList()

Fetches a list of recurring invoices for a client

public getRecurringList([int $client_id = null ][, int $page = 1 ][, array<string|int, mixed> $order = ['id' => 'asc'] ][, array<string|int, mixed> $filters = [] ]) : array<string|int, mixed>
Parameters
$client_id : int = null

The client ID (optional, default null to get recurring invoices for all clients)

$page : int = 1

The page to return results for

$order : array<string|int, mixed> = ['id' => 'asc']

The fields and direction to order by. Key/value pairs where key is the field and value is the direction (asc/desc)

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

A list of parameters to filter by, including:

  • invoice_number The invoice number on which to filter invoices
  • currency The currency code on which to filter invoices
  • invoice_line The (partial) description of the invoice line on which to filter invoices
Return values
array<string|int, mixed> —

An array of stdClass objects containing recurring invoice information

getRecurringListCount()

Return the total number of recurring invoices returned from Invoices::getRecurringList(), useful in constructing pagination for the getList() method.

public getRecurringListCount(int $client_id[, array<string|int, mixed> $filters = [] ]) : int
Parameters
$client_id : int

The client ID

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

A list of parameters to filter by, including:

  • invoice_number The invoice number on which to filter invoices
  • currency The currency code on which to filter invoices
  • invoice_line The (partial) description of the invoice line on which to filter invoices
Tags
see
Invoices::getRecurringList()
Return values
int —

The total number of recurring invoices

getSearchCount()

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

public getSearchCount(string $query) : mixed
Parameters
$query : string

The value to search invoices for

Tags
see
Invoices::search()

getStatusCount()

Retrieves the number of invoices given an invoice status for the given client

public getStatusCount([int $client_id = null ][, string $status = 'open' ][, array<string|int, mixed> $filters = [] ]) : int
Parameters
$client_id : int = null

The client ID (optional, default null to get invoice count for company)

$status : string = 'open'

The status type of the invoices to fetch (optional, default 'open') one of the following:

  • open Fetches all active open invoices
  • closed Fetches all closed invoices
  • past_due Fetches all active past due invoices
  • draft Fetches all invoices with a status of "draft"
  • void Fetches all invoices with a status of "void"
  • active Fetches all invoices with a status of "active"
  • proforma Fetches all invoices with a status of "proforma"
  • to_print Fetches all paper invoices set to be printed
  • printed Fetches all paper invoices that have been set as printed
  • pending Fetches all active invoices that have not been billed for yet
  • to_deliver Fetches all invoices set to be delivered by a method other than paper (i.e. deliverable invoices not in the list of those "to_print")
$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • invoice_number The invoice number on which to filter invoices
  • currency The currency code on which to filter invoices
  • invoice_line The (partial) description of the invoice line on which to filter invoices
Return values
int —

The number of invoices of type $status for $client_id

getStatuses()

Retrieves a list of invoice statuses and language

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

A key/value array of statuses and their language

getSubtotal()

Calculates the subtotal of the given invoice ID

public getSubtotal(int $invoice_id) : float

since v4.6.0 - use \Blesta\Core\Pricing\

Parameters
$invoice_id : int

The ID of the invoice to calculate the subtotal of

Return values
float —

The subtotal of the invoice

getTaxRules()

Retrieves all active tax rules that apply to the given client

public getTaxRules(int $client_id) : array<string|int, mixed>
Parameters
$client_id : int

The client ID

Return values
array<string|int, mixed> —

A numerically indexed array of stdClass objects each representing a tax rule to apply to this client

getTaxRulesByLocation()

Retrieves all active tax rules that apply to the given company and location

public getTaxRulesByLocation(int $company_id, string $country, string $state) : array<string|int, mixed>
Parameters
$company_id : int

The ID of the company to fetch tax rules on

$country : string

The ISO 3166-1 alpha2 country code to fetch tax rules on

$state : string

3166-2 alpha-numeric subdivision code to fetch tax rules on

Return values
array<string|int, mixed> —

A numerically indexed array of stdClass objects each representing a tax rule to apply to this company and location

getTaxTotals()

Calculates the amount of tax for each tax rule given that applies to the given line sub total (which is unit cost * quantity).

public getTaxTotals(float $line_subtotal, array<string|int, mixed> $taxes) : array<string|int, mixed>

since v4.6.0 - use \Blesta\Core\Pricing\ library

Also returns the line total including inclusive tax rules as well as the total with all tax rules

Parameters
$line_subtotal : float

The subtotal (quanity * unit cost) for the line item

$taxes : array<string|int, mixed>

An array of stdClass objects each representing a tax rule to be applied to the line subtotal

Return values
array<string|int, mixed> —

An array containing the following:

  • tax An array of tax rule applied amounts
  • tax_subtotal The tax subtotal (all inclusive taxes applied)
  • tax_total All taxes applied (inclusive and exclusive)
  • line_total The total for the line including inclusive taxes
  • line_total_w_tax The total for the line including all taxes (inclusive and exclusive)

getTotal()

Calculates the total (subtotal + tax) of the given invoice ID

public getTotal(int $invoice_id) : float

since v4.6.0 - use \Blesta\Core\Pricing\

Parameters
$invoice_id : int

The ID of the invoice to calculate the total of

Return values
float —

The total of the invoice

getTypes()

Fetches the available invoice types

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

A key/value array of invoice types

invoicedCurrencies()

Returns an array of all currency the given client has been invoiced in

public invoicedCurrencies(int $client_id[, string $status = 'active' ]) : array<string|int, mixed>
Parameters
$client_id : int
$status : string = 'active'

The status type of the invoices to fetch (optional, default 'active') - ['open','closed','past_due','draft', 'proforma','void','active'] (or 'all' for all active/draft/proforma/void)

Return values
array<string|int, mixed> —

An array of stdClass objects, each representing a currency in use

isInstanceOf()

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

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

The field to check

$class : mixed

The class or instance to check against

Return values
bool —

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

makeLinesFromItems()

Creates a list of line items from the given set of items, discounts, and taxes

public makeLinesFromItems(array<string|int, mixed> $vars) : array<string|int, mixed>

since v4.1.0

Parameters
$vars : array<string|int, mixed>

A key/value array, including:

  • items An array of stdClass items from which to create the line items, each including:
    • description The line item description to set
    • price The unit price of the line item
    • qty The line quantity
    • discounts An array of stdClass discounts applied to the line, including:
      • description The coupon description
      • amount The amount of discount
      • type The type of discount
      • total The total amount discounted from the line
    • taxes An array of stdClass taxes applied to the line, including:
      • description The tax description
      • amount The amount of tax
      • type The type of tax
      • total The total amount taxed from the line
Tags
see
Invoices::getItemTotals
Return values
array<string|int, mixed> —

An array of line items, each including:

  • service_id The ID of the service to which the line belongs
  • description The line description
  • qty The line quantity
  • amount The unit price
  • order The line item order relative to other line items
  • tax True or false, whether the item is taxable

merge()

Merge multiples open invoices in to a single invoice

public merge(array<string|int, mixed> $invoice_ids[, int $invoice_id = null ]) : int
Parameters
$invoice_ids : array<string|int, mixed>

A list of invoice IDs to be merged

$invoice_id : int = null

The ID of the invoice where the invoice lines would be merged, null to create a new invoice

Return values
int —

The ID of the merged invoice, void on error

primeQuantity()

Converts quantity to a float, if no qty is set, a value of 1 is assumed.

public primeQuantity(mixed $qty) : float
Parameters
$qty : mixed

The quantity to be primed, may be an integer, float, or fractional string

Return values
float —

The quanity rounded to 4 decimal places

search()

Search invoices

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

The value to search invoices for

$page : int = 1

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

Return values
array<string|int, mixed> —

An array of invoices that match the search criteria

setClosed()

Sets the invoice to closed if the invoice has been paid in full, otherwise removes any closed status previously set on the invoice. Only invoices with status of 'active' can be closed.

public setClosed(int $invoice_id) : bool
Parameters
$invoice_id : int

The ID of the invoice to close or unclose

Return values
bool —

True if the invoice was closed, false otherwise

setMeta()

Sets meta data for the given invoice

public setMeta(int $invoice_id, string $key, mixed $value) : mixed
Parameters
$invoice_id : int

The ID of the invoice to set meta data for

$key : string

The key of the invoice meta data

$value : mixed

The value to store for this meta field

split()

Splits an invoice in two separate invoices

public split(int $invoice_id[, array<string|int, mixed> $line_items = [] ]) : mixed
Parameters
$invoice_id : int

The ID of the invoice to split

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

An array containing the line items to move to the new invoice

Return values
mixed —

The ID of the new invoice, void on error

unsetMeta()

Deletes any meta on the given invoice ID

public unsetMeta(int $invoice_id[, string $key = null ]) : mixed
Parameters
$invoice_id : int

The invoice ID to unset meta data for

$key : string = null

The key to unset, null will unset all keys

updateCache()

Updates an invoice on cache

public updateCache(int $invoice_id[, mixed $data = null ][, string $extension = 'json' ]) : bool
Parameters
$invoice_id : int

The ID of the invoice to save on cache

$data : mixed = null

The data of the invoice to cache (optional, if not provided the invoice data will be cached the next time the invoice is rendered)

$extension : string = 'json'

The cache extension (optional, 'json' by default)

Return values
bool —

True if the invoice has been saved on cache successfully, void on error

validateAmountApplied()

Checks if the given invoice has any payments applied to it

public validateAmountApplied(int $invoice_id) : bool
Parameters
$invoice_id : int

The invoice ID to check

Return values
bool —

True if the invoice has payments applied to it, false otherwise

validateDateDueAfterDateBilled()

Validates that the given date due is on or after the date billed

public validateDateDueAfterDateBilled(string $date_due, string $date_billed) : bool
Parameters
$date_due : string

The date the invoice is due

$date_billed : string

The date the invoice is billed

Return values
bool —

True if the date due is on or after the date billed, false otherwise

validateDeliveryMethods()

Validates that the delivery options match the available set

public validateDeliveryMethods([array<string|int, mixed> $methods = null ]) : bool
Parameters
$methods : array<string|int, mixed> = null

A key=>value array of delivery methods (e.g. "email"=>true)

Return values
bool —

True if at least one delivery method was given, false otherwise

validateDuration()

Validates the recurring invoice duration

public validateDuration(mixed $duration) : bool
Parameters
$duration : mixed

An integer idenfying the number of the times the recurring invoice should recur, null for indefinitely

Return values
bool —

True if the duration is valid, false otherwise

validateIsDraft()

Validates that the given invoice is a draft invoice

public validateIsDraft(int $invoice_id) : bool
Parameters
$invoice_id : int

The invoice ID

Return values
bool —

True if the given invoice is a draft, and false otherwise

validatePeriod()

Validates the recurring invoice period

public validatePeriod(string $period) : bool
Parameters
$period : string

The period type

Return values
bool —

True if validated, false otherwise

validateStatus()

Validates the invoice 'status' field

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

The status to check

Return values
bool —

True if validated, false otherwise

verifyPayHash()

Verifies the Payment Hash is valid

public verifyPayHash(int $client_id, int $invoice_id, string $hash) : bool
Parameters
$client_id : int

The client ID to verify the hash for

$invoice_id : int

The ID of the invoice to verify the hash for

$hash : string

The original hash to verify against

Return values
bool —

True if the hash is valid, false otherwise

writeCache()

Writes an invoice on cache

public writeCache(int $invoice_id, mixed $data[, string $extension = 'json' ][, string $language = null ]) : bool
Parameters
$invoice_id : int

The ID of the invoice to save on cache

$data : mixed

The data of the invoice to cache

$extension : string = 'json'

The cache extension (optional, 'json' by default)

$language : string = null

The language of the invoice being saved (optional)

Return values
bool —

True if the invoice has been saved on cache successfully, void on error

addLine()

Adds a line item to an existing invoice

private addLine(int $invoice_id, array<string|int, mixed> $vars) : int
Parameters
$invoice_id : int

The ID of the invoice to add a line item to

$vars : array<string|int, mixed>

A list of line item vars including:

  • service_id The service ID attached to this line item
  • description The line item description
  • qty The quantity for this line item (min. 1)
  • amount The unit cost (cost per quantity) for this line item
  • tax Whether or not to tax the line item
  • order The order number of the line item (optional, default is the last)
Return values
int —

The ID of the line item created

addLineTax()

Adds a new line item tax

private addLineTax(int $line_id, int $tax_id[, bool $cascade = false ][, bool $subtract = false ]) : mixed
Parameters
$line_id : int

The line item ID

$tax_id : int

The tax ID

$cascade : bool = false

Whether or not this tax rule should cascade over other rules

$subtract : bool = false

Whether or not this tax rule should be subtracted from the line item value

deleteLine()

Permanently removes an invoice line item and its corresponding line item taxes

private deleteLine(int $line_id) : mixed
Parameters
$line_id : int

The line item ID

deleteLineTax()

Permanently removes an invoice line item's tax rule

private deleteLineTax(int $line_id) : mixed
Parameters
$line_id : int

The line item ID

deleteRecurringLine()

Permanently removes a recurring invoice line item

private deleteRecurringLine(int $line_id) : mixed
Parameters
$line_id : int

The line item ID

getClientSettingSubquery()

Gets a partial record for a subquery fetching client settings

private getClientSettingSubquery(string $setting) : Record
Parameters
$setting : string

The name of the setting to fetch

Return values
Record —

The partially constructed query Record object

getCurrencyPrecision()

Retrieves the decimal precision for the given currency

private getCurrencyPrecision(string $currency, int $company_id) : int
Parameters
$currency : string

The ISO 4217 3-character currency code

$company_id : int

The ID of the company

Return values
int —

The currency decimal precision

getDiscountPrices()

Builds a list of DiscountPrice objects from the given discounts

private getDiscountPrices(array<string|int, mixed> $discounts) : array<string|int, mixed>

since 4.0.0 - Use Blesta\Core\Pricing...

Parameters
$discounts : array<string|int, mixed>

An array of discount information including:

  • amount The tax amount
  • type The discount type ('amount', 'percent')
  • description The description (optional)
  • apply An array of item indexes to which the discount applies (optional)
Tags
see
::makeItemCollection
Return values
array<string|int, mixed> —

An array containing arrays of:

  • price A DiscountPrice object
  • apply An array of item indexes to which the price applies

getInvoice()

Partially constructs the query required by Invoices::get() and others

private getInvoice(int $invoice_id) : Record
Parameters
$invoice_id : int

The ID of the invoice to fetch

Return values
Record —

The partially constructed query Record object

getInvoiceDeliveries()

Partially constructs a Record object for fetching invoice deliveries

private getInvoiceDeliveries([string $method = null ][, array<string|int, mixed> $filters = [] ]) : Record
Parameters
$method : string = null

The invoice delivery method to filter by (optional)

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

A list of parameters to filter by, including:

  • string The (partial) string on which to filter logs
  • start_date The start date on which to filter logs
  • end_date The end date on which to filter logs
Return values
Record —

A partially-constructed Record object for fetching invoice deliveries

getInvoices()

Partially constructs the query required by Invoices::getList() and Invoices::getListCount()

private getInvoices([array<string|int, mixed> $filters = [] ][, array<string|int, mixed> $options = [] ][, mixed $count = false ]) : Record
Parameters
$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • client_id The client ID (optional, default null to fetch invoices for all clients)
  • invoice_number The invoice number on which to filter invoices
  • currency The currency code on which to filter invoices
  • invoice_line The (partial) description of the invoice line on which to filter invoices
  • status The status type of the invoices to fetch (optional, default 'open') one of the following:
    • open Fetches all active open invoices
    • closed Fetches all closed invoices
    • past_due Fetches all active past due invoices
    • draft Fetches all invoices with a status of "draft"
    • void Fetches all invoices with a status of "void"
    • active Fetches all invoices with a status of "active"
    • proforma Fetches all invoices with a status of "proforma"
    • to_autodebit Fetches all invoices that are ready to be autodebited now, and which can be with an active client and payment account to do so
    • pending_autodebit Fetches all invoice that are set to be autodebited in the future, and which have an active client and payment account to do so with
    • to_print Fetches all paper invoices set to be printed
    • printed Fetches all paper invoices that have been set as printed
    • pending Fetches all active invoices that have not been billed for yet
    • to_deliver Fetches all invoices set to be delivered by a method other than paper (i.e. deliverable invoices not in the list of those "to_print")
    • all Fetches all invoices
$options : array<string|int, mixed> = []

A list of additional options

  • autodebit_date The autodebit date to fetch invoices; for use with the "to_autodebit" or "pending_autodebit" statuses
  • client_group_id The ID of the client group to filter invoices on
$count : mixed = false
Return values
Record —

The partially constructed query Record object

getLines()

Retrieves the line items for the given invoice

private getLines(int $invoice_id) : array<string|int, mixed>
Parameters
$invoice_id : int

The invoice ID of the line items to retrieve

Return values
array<string|int, mixed> —

An array of line items for the given invoice

getLinesForServices()

Generates the line items for a given set of service IDs.

private getLinesForServices(array<string|int, mixed> $service_ids, string $currency, mixed &$coupons[, bool $allow_pro_rata = true ][, bool $services_renew = false ][, array<string|int, mixed> $service_transfers = [] ][, int $term_cycles = 1 ]) : array<string|int, mixed>

May also bump service renew dates for prorated services.

Parameters
$service_ids : array<string|int, mixed>

A numerically-indexed array of service IDs

$currency : string

The ISO 4217 3-character currency code of the invoice

$coupons : mixed
$allow_pro_rata : bool = true

True to allow the services to be priced considering the package pro rata details, or false otherwise (optional, default true)

$services_renew : bool = false

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

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

A numerically-indexed array of service IDs that are being transferred

$term_cycles : int = 1

The amounts of terms to bill (optional, default 1)

Return values
array<string|int, mixed> —

A list of line items

getLineTaxes()

Fetches all tax info attached to the line item

private getLineTaxes(int $invoice_line_id) : array<string|int, mixed>
Parameters
$invoice_line_id : int

The ID of the invoice line item to fetch tax info for

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

An array of stdClass objects each representing a tax rule

getMergeRules()

Returns the rule set for merging existing invoices

private getMergeRules(array<string|int, mixed> $vars) : array<string|int, mixed>
Parameters
$vars : array<string|int, mixed>

The input vars

Return values
array<string|int, mixed> —

Invoice rules

getNextInvoiceVars()

Updates $vars with the subqueries to properly set the previous_due, id_format, and id_value fields when creating an invoice or converting a draft or profroma to an active invoice

private getNextInvoiceVars(array<string|int, mixed> $vars, array<string|int, mixed> $client_settings[, bool $new = true ]) : array<string|int, mixed>
Parameters
$vars : array<string|int, mixed>

An array of invoice data from Invoices::add() or Invoices::edit()

$client_settings : array<string|int, mixed>

An array of client settings

$new : bool = true

True if this is a new invoice, false if being updated

Return values
array<string|int, mixed> —

An array of invoice data now including the proper subqueries for setting the previous_due, id_format and id_value fields

getPreviousDue()

Retrieves the previous due amount for the given client in the given currency

private getPreviousDue(int $client_id, string $currency) : float
Parameters
$client_id : int

The client ID

$currency : string

The ISO 4217 3-character currency code

Return values
float —

The previous amount due for this client

getRecurringInvoice()

Partially constructs the query required by Invoices::getRecurring() and others

private getRecurringInvoice(int $invoice_recur_id) : Record
Parameters
$invoice_recur_id : int

The recurring invoice ID to fetch

Return values
Record —

The partially constructed query Record object

getRecurringInvoices()

Partially constructs the query required by both Invoices::getRecurringList() and Invoices::getRecurringListCount()

private getRecurringInvoices([array<string|int, mixed> $filters = [] ][, bool $group = true ]) : Record
Parameters
$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • client_id The client ID (optional, default null to fetch invoices for all clients)
  • invoice_number The invoice number on which to filter invoices
  • currency The currency code on which to filter invoices
  • invoice_line The (partial) description of the invoice line on which to filter invoices
$group : bool = true

True to group the query as required, false to not group at all (grouping should still be done)

Return values
Record —

The partially constructed query Record object

getRecurringRules()

Returns the rule set for adding/editing recurring invoices

private getRecurringRules(array<string|int, mixed> $vars) : array<string|int, mixed>
Parameters
$vars : array<string|int, mixed>

The input vars

Return values
array<string|int, mixed> —

Invoice rules

getRecurringTaxes()

Fetches all taxes for the given recurring invoice

private getRecurringTaxes(int $invoice_recur_id) : array<string|int, mixed>
Parameters
$invoice_recur_id : int

The invoice recurrence ID

Return values
array<string|int, mixed> —

An array of all tax rules for this recurring invoice

getRules()

Returns the rule set for adding/editing invoices

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

The input vars

$edit : bool = false

True if the invoice is being edited

Return values
array<string|int, mixed> —

Invoice rules

getTaxes()

Fetches all taxes for the given invoice

private getTaxes(int $invoice_id) : array<string|int, mixed>
Parameters
$invoice_id : int

The invoice ID

Return values
array<string|int, mixed> —

An array of all tax rules for this invoice

getTaxPrices()

Builds a list of TaxPrice objects from the given taxes

private getTaxPrices(array<string|int, mixed> $taxes) : array<string|int, mixed>

since 4.0.0 - Use Blesta\Core\Pricing...

Parameters
$taxes : array<string|int, mixed>

An array of tax information including:

  • amount The tax amount
  • type The tax type ('inclusive', 'exclusive')
  • description The description (optional)
  • apply An array of item indexes to which the tax applies (optional)
Tags
see
::makeItemCollection
Return values
array<string|int, mixed> —

An array containing arrays of:

  • prices An array of TaxPrice objects
  • apply An array of item indexes to which the prices apply

getTotals()

Retrieves the totals for an invoice

private getTotals(int $invoice_id) : array<string|int, mixed>
Parameters
$invoice_id : int

The ID of the invoice whose totals to fetch

Return values
array<string|int, mixed> —

An array of totals including:

  • subtotal
  • total
  • total_without_exclusive_tax
  • total_after_tax
  • total_after_discount
  • tax_amonut
  • discount_amount

itemCollectionDiscounts()

Retrieves a list of all discounts on a collection

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

since 4.0.0 - Use Blesta\Core\Pricing...

Parameters
$collection : ItemPriceCollection

The collection from which to fetch all discounts

Return values
array<string|int, mixed> —

An array of stdClass objects representing each discount, including:

  • description The discount description
  • amount The discount amount
  • type The discount type
  • total The total amount actually discounted

itemCollectionItems()

Retrieves a list of all item prices in a collection

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

since 4.0.0 - Use Blesta\Core\Pricing...

Parameters
$collection : ItemPriceCollection

The collection from which to fetch all items

Return values
array<string|int, mixed> —

An array of stdClass objects representing each item, including:

  • description The item description
  • price The item unit price
  • qty The item quantity
  • subtotal The item subtotal
  • total The item total
  • total_after_tax The item total including tax
  • total_after_discount The item total after discount
  • tax_amount The total item tax
  • discount_amount The total item discount

itemCollectionTaxes()

Retrieves a list of all taxes on a collection

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

since 4.0.0 - Use Blesta\Core\Pricing...

Parameters
$collection : ItemPriceCollection

The collection from which to fetch all taxes

Return values
array<string|int, mixed> —

An array of stdClass objects representing each tax, including:

  • description The tax description
  • amount The tax amount
  • type The tax type
  • total The total amount actually taxed

lineItemsChanged()

Checks whether the line items for an invoice are being altered

private lineItemsChanged(int $invoice_id, array<string|int, mixed> $vars) : bool
Parameters
$invoice_id : int

The ID of the invoice to be checked

$vars : array<string|int, mixed>

The vars being used to alter the invoice

Return values
bool —

Whether the line items have been changed

makeInvoice()

Performs a validation check on the set input rules and attempts to create an invoice

private makeInvoice(array<string|int, mixed> $vars, array<string|int, mixed> $client_settings) : int
Parameters
$vars : array<string|int, mixed>

An array of invoice data including:

  • client_id The client ID the invoice belongs to
  • date_billed The date the invoice goes into effect
  • date_due The date the invoice is due
  • date_closed The date the invoice was closed
  • date_autodebit The date the invoice should be autodebited
  • status 'active','draft','proforma', or 'void'
  • currency The ISO 4217 3-character currency code of the invoice
  • note_public Notes visible to the client
  • note_private Notes visible only to staff members
  • lines A numerically indexed array of line item info including:
    • service_id The service ID attached to this line item (optional)
    • description The line item description
    • qty The quantity for this line item (min. 1)
    • amount The unit cost (cost per quantity) for this line item
    • tax Whether or not to tax the line item
  • term The term for the recurring invoice as an integer 1-65535, if blank will not be considered for a recurring invoice
  • period The period for the recurring invoice ('day', 'week', 'month', 'year')
  • duration The duration of the recurring invoice ('indefinitely' for forever or 'times' for a set number of times)
  • duration_time The number of times an invoice should recur
  • recur_date_billed The date the next invoice will be created
  • delivery A numerically indexed array of delivery methods
$client_settings : array<string|int, mixed>
Return values
int —

The invoice ID, void on error

makeItemCollection()

Creates an ItemPriceCollection from the given items, discounts, and taxes

private makeItemCollection(array<string|int, mixed> $items[, array<string|int, mixed> $discounts = [] ][, array<string|int, mixed> $taxes = [] ]) : ItemPriceCollection

since 4.0.0 - Use Blesta\Core\Pricing...

Parameters
$items : array<string|int, mixed>

An array of items including:

  • price The unit price of the item
  • qty The item quantity (optional, default 1)
  • description The item description (optional)
$discounts : array<string|int, mixed> = []

An array of applicable discounts including (optional):

  • amount The discount amount
  • type The discount type ('amount' or 'percent')
  • description The discount description (optional)
  • apply An array of item indexes to which the discount applies (optional, defaults to all)
$taxes : array<string|int, mixed> = []

An array containing arrays of applicable taxes where each array group represents taxes to cascade on each other; including (optional):

  • amount The tax amount
  • type The tax type ('exclusive' or 'inclusive')
  • description The tax description (optional)
  • apply An array of item indexes to which the tax applies (optional, defaults to all)
Return values
ItemPriceCollection —

An ItemPriceCollection object of all the items

makeLineItem()

Creates an array representing a single line item

private makeLineItem(string $description, mixed $qty, float $price, bool $taxable, int $service_id, int $order) : An

since v4.1.0

Parameters
$description : string

The line item description

$qty : mixed

The line item quantity

$price : float

The unit price

$taxable : bool

True if the item is taxable, or false otherwise

$service_id : int

The ID of the service the line item should be assigned to

$order : int

The order of the line item

Return values
An —

array representing a line item

makeLinesBackwardCompatible()

Adds deprecated tax information to each line item

private makeLinesBackwardCompatible(array<string|int, mixed> $lines) : array<string|int, mixed>

since v4.6.0

Parameters
$lines : array<string|int, mixed>

An array of stdClass objects representing invoice line items, including:

  • subtotal
  • taxes An array of tax rules for each line item @see ::getLineTaxes
Return values
array<string|int, mixed> —

An array of invoice line items with tax information added to each line

pricingFactory()

Retrieves an instance of the PricingFactory

private pricingFactory() : PricingFactory

since 4.0.0 - Use Blesta\Core\Pricing...

Return values
PricingFactory —

The PricingFactory

requeueClosedInvoiceForDelivery()

Requeues a closed invoice for email delivery if the setting is enabled

private requeueClosedInvoiceForDelivery(int $invoice_id, int $client_id) : mixed
Parameters
$invoice_id : int

The ID of the invoice to requeue for delivery

$client_id : int

The ID of the client the invoice belongs to

requeueForDelivery()

Requeues an invoice to be delivered again using all methods from which it has already been delivered, so long as those delivery methods are still available

private requeueForDelivery(int $invoice_id, int $client_id) : mixed
Parameters
$invoice_id : int

The ID of the invoice to requeue for delivery

$client_id : int

The ID of the client the invoice belongs to

searchInvoices()

Partially constructs the query for searching invoices

private searchInvoices(string $query) : Record
Parameters
$query : string

The value to search invoices for

Tags
see

Invoices::search(), Invoices::getSearchCount()

Return values
Record —

The partially constructed query Record object

taxUpdateRequired()

Identifies whether or not the given invoice with its updated line items and deleted items requires tax rules to be updated when saved. This method doesn't check whether the tax rules have been updated, just whether the invoice has been changed such that the updated tax rules would need to be updated. There's no consequence in updating tax when the tax rules have not changed.

private taxUpdateRequired(int $invoice_id, array<string|int, mixed> $lines, array<string|int, mixed> $delete_items) : bool
Parameters
$invoice_id : int

The ID of the invoice to evaluate

$lines : array<string|int, mixed>

An array of line items including:

  • id The ID of the line item (if available)
  • tax Whether or not the line items is taxable (true/false)
  • amount The amount per quantity for the line item
  • qty The quantity of the line item
$delete_items : array<string|int, mixed>

An array of items to be deleted from the invoice

Tags
see
Invoices::edit()
Return values
bool —

True if the invoice has been modified in such a way to warrant updating the tax rules applied, false otherwise

updateTotals()

Calculates and updates the stored subtotal, total, and amount paid values for the given invoice

private updateTotals(int $invoice_id) : mixed
Parameters
$invoice_id : int

The ID of the invoice to update totals for

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