Blesta Source Documentation

Quotations extends AppModel

Quotations management

Table of Contents

Methods

__construct() Initialize Invoices
add() Creates a new quotation using the given data
clearCache() Clears the quotation cache
edit() Updates a quotation 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 quotation.
fetchCache() Fetch a cached quotation
generateInvoice() Generates an invoice from an existing quotation
get() Fetches the given quotation
getAll() Fetches all quotations for a client
getDataPresenter() Retrieves a presenter representing a set of items and taxes for quotation data
getInvoices() Returns all invoices associated to a quotation
getLineItems() Fetches all line items belonging to the given quotation
getList() Fetches a list of quotations for a client
getListCount() Returns the total number of quotations returned from Quotations::getClientList(), useful in constructing pagination for the getList() method.
getPresenter() Retrieves a presenter representing a set of items and taxes for the quotation
getSearchCount() Return the total number of quotations returned from Quotations::search(), useful in constructing pagination
getStatusCount() Retrieves the number of quotations given an quotation status for the given client
getStatuses() Gets the available statuses for quotations
search() Search quotations
updateCache() Updates a quotation on cache
updateStatus() Updates the status of a given quotation
validateDateDueAfterDateCreated() Validates that the given date due is on or after the date created
writeCache() Writes a quotation on cache
addLine() Adds a line item to an existing quotation
addLineTax() Adds a new line item tax
deleteLine() Permanently removes a quotation line item and its corresponding line item taxes
deleteLineTax() Permanently removes a quotation line item's tax rule
getCurrencyPrecision() Retrieves the decimal precision for the given currency
getInvoiceRules() Returns the rule set for adding/editing quotations
getLines() Retrieves the line items for the given quotation
getLineTaxes() Fetches all tax info attached to the line item
getNextQuotationVars() Updates $vars with the subqueries to properly set the id_format and id_value fields when creating a quotation
getQuotation() Partially constructs the query required by Quotations::get() and others
getQuotations() Partially constructs the query required by Quotations::getList() and Quotations::getListCount()
getRules() Returns the rule set for adding/editing quotations
getTaxes() Fetches all taxes for the given quotation
makeQuote() Performs a validation check on the set input rules and attempts to create a quote
searchQuotations() Partially constructs the query for searching quotations
sendApprovedEmail() Sends the Quotation Approved email
sendApprovedNotification() Sends the Quotation Approved notification
taxUpdateRequired() Identifies whether or not the given quotation 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 quotation
Methods

__construct()

Initialize Invoices

public __construct() : mixed

add()

Creates a new quotation using the given data

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

An array of quotation data including:

  • client_id The client ID the quote belongs to
  • staff_id The staff ID the quote was generated by
  • title The title of the quotation
  • status The status of the quotation, it could be 'draft', 'pending', 'approved', 'invoiced', 'expired', 'dead' or 'lost'
  • currency The ISO 4217 3-character currency code of the quote
  • notes Notes visible to the client
  • private_notes Notes visible to the staff
  • date_created The date the quotation was created
  • date_expires The date the quotation expires
  • 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
Return values
int —

The quote ID, void on error

clearCache()

Clears the quotation cache

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

The ID of the quotation to clear

$extension : string = 'json'

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

$language : string = null

The language of the quotation to clear (optional)

Return values
bool —

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

edit()

Updates a quotation 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 quotation.

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

The ID of the quotation to update

$vars : array<string|int, mixed>

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

  • client_id The client ID the quote belongs to
  • staff_id The staff ID the quote was generated by
  • title The title of the quotation
  • status The status of the quotation, it could be 'draft', 'pending', 'approved', 'invoiced', 'expired', 'dead' or 'lost'
  • currency The ISO 4217 3-character currency code of the quote
  • notes Notes visible to the client
  • private_notes Notes visible to the staff
  • date_created The date the quotation was created
  • date_expires The date the quotation expires
  • 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
Return values
int —

The quotation ID, void on error

fetchCache()

Fetch a cached quotation

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

The ID of the quotation to fetch

$extension : string = 'json'

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

$language : string = null

The language of the quotation to fetch (optional)

Return values
mixed —

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

generateInvoice()

Generates an invoice from an existing quotation

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

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

  • percentage_due The (%) percentage due in the first payment (optional)
  • first_due_date The due date of the first invoice
  • second_due_date The due date of the second invoice (optional)

get()

Fetches the given quotation

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

The ID of the quotation to fetch

Return values
mixed —

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

getAll()

Fetches all quotations for a client

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

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

$status : string = 'draft'

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

  • approved Fetches all approved quotations
  • pending Fetches all pending quotations
  • expired Fetches all expired quotations
  • invoiced Fetches all invoiced quotations
  • dead Fetches all quotations with a status of "quotations"
  • lost Fetches all quotations with a status of "lost"
  • draft Fetches all quotations with a status of "draft"
  • all Fetches all quotations
$order_by : array<string|int, mixed> = ['date_expires' => '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 quotation information

getDataPresenter()

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

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

The ID of the client the quotation data is for

$vars : array<string|int, mixed>

An array of input representing the new quotation data

  • client_id The client ID the quote belongs to
  • staff_id The staff ID the quote was generated by
  • title The title of the quotation
  • status The status of the quotation, it could be 'draft', 'pending', 'approved', 'invoiced', 'expired', 'dead' or 'lost'
  • currency The ISO 4217 3-character currency code of the quote
  • notes Notes visible to the client
  • date_created The date the quotation was created
  • date_expires The date the quotation expires
  • 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
Return values
InvoiceDataPresenter —

The presenter

getInvoices()

Returns all invoices associated to a quotation

public getInvoices(int $quotation_id) : array<string|int, mixed>
Parameters
$quotation_id : int

The ID of the quotation to fecth the invoices

Return values
array<string|int, mixed> —

An array containing the invoices associated to the quotation

getLineItems()

Fetches all line items belonging to the given quotation

public getLineItems(int $quotation_id) : array<string|int, mixed>
Parameters
$quotation_id : int

The ID of the quotation to fetch line items for

Return values
array<string|int, mixed> —

An array of stdClass objects each representing a line item

getList()

Fetches a list of quotations for a client

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

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

$status : string = 'draft'

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

  • approved Fetches all approved quotations
  • pending Fetches all pending quotations
  • expired Fetches all expired quotations
  • invoiced Fetches all invoiced quotations
  • dead Fetches all quotations with a status of "quotations"
  • lost Fetches all quotations with a status of "lost"
  • draft Fetches all quotations with a status of "draft"
  • all Fetches all quotations
$page : int = 1

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

$order_by : array<string|int, mixed> = ['date_expires' => '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:

  • quotation_number The quotation number on which to filter quotations
  • currency The currency code on which to filter quotations
  • description The (partial) description on which to filter quotations
  • quotation_line The (partial) description of the quotation line on which to filter quotations
Return values
array<string|int, mixed> —

An array of stdClass objects containing quotation information, or false if no quotations exist

getListCount()

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

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

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

$status : string = 'draft'

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

  • approved Fetches all approved quotations
  • pending Fetches all pending quotations
  • expired Fetches all expired quotations
  • invoiced Fetches all invoiced quotations
  • dead Fetches all quotations with a status of "quotations"
  • lost Fetches all quotations with a status of "lost"
  • draft Fetches all quotations with a status of "draft"
  • all Fetches all quotations
$filters : array<string|int, mixed> = []

A list of parameters to filter by, including:

  • quotation_number The quotation number on which to filter quotations
  • currency The currency code on which to filter quotations
  • quotation_line The (partial) description of the quotation line on which to filter quotations
Tags
see
Quotations::getList()
Return values
int —

The total number of quotations

getPresenter()

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

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

The ID of the quotation whose pricing to fetch

Return values
bool|InvoicePresenter —

The presenter, otherwise false

getSearchCount()

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

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

The value to search quotations for

Tags
see
Quotations::search()

getStatusCount()

Retrieves the number of quotations given an quotation status for the given client

public getStatusCount([int $client_id = null ][, string $status = 'draft' ][, 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 = 'draft'

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

  • approved Fetches all approved quotations
  • pending Fetches all pending quotations
  • expired Fetches all expired quotations
  • invoiced Fetches all invoiced quotations
  • dead Fetches all quotations with a status of "quotations"
  • lost Fetches all quotations with a status of "lost"
  • draft Fetches all quotations with a status of "draft"
  • all Fetches all quotations
$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
  • quotation_line The (partial) description of the quotation line on which to filter quotations
Return values
int —

The number of invoices of type $status for $client_id

getStatuses()

Gets the available statuses for quotations

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

An array containing the available statuses for quotations

search()

Search quotations

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

The value to search quotations for

$page : int = 1

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

Return values
array<string|int, mixed> —

An array of quotations that match the search criteria

updateCache()

Updates a quotation on cache

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

The ID of the quotation to save on cache

$data : mixed = null

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

$extension : string = 'json'

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

Return values
bool —

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

updateStatus()

Updates the status of a given quotation

public updateStatus(int $quotation_id, string $status) : mixed
Parameters
$quotation_id : int

The ID of the quotation to update

$status : string

The new status of the quotation

validateDateDueAfterDateCreated()

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

public validateDateDueAfterDateCreated(string $date_expires, string $date_created) : bool
Parameters
$date_expires : string

The date the quotation expires

$date_created : string

The date the quotation was created

Return values
bool —

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

writeCache()

Writes a quotation on cache

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

The ID of the quotation to save on cache

$data : mixed

The data of the quotation to cache

$extension : string = 'json'

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

$language : string = null

The language of the quotation being saved (optional)

Return values
bool —

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

addLine()

Adds a line item to an existing quotation

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

The ID of the quotation to add a line item to

$vars : array<string|int, mixed>

A list of line item vars 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
  • 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 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 a quotation 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 a quotation line item's tax rule

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

The line item ID

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

getInvoiceRules()

Returns the rule set for adding/editing quotations

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

The input vars

Return values
array<string|int, mixed> —

Quotations rules

getLines()

Retrieves the line items for the given quotation

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

The quotation ID of the line items to retrieve

Return values
array<string|int, mixed> —

An array of line items for the given invoice

getLineTaxes()

Fetches all tax info attached to the line item

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

The ID of the quotation 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

getNextQuotationVars()

Updates $vars with the subqueries to properly set the id_format and id_value fields when creating a quotation

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

An array of quote data from Quotations::add() or Quotations::edit()

$client_settings : array<string|int, mixed>

An array of client settings

Return values
array<string|int, mixed> —

An array of quote data now including the proper subqueries for setting the id_format and id_value fields

getQuotation()

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

private getQuotation(int $quotation_id) : Record
Parameters
$quotation_id : int

The ID of the quotation to fetch

Return values
Record —

The partially constructed query Record object

getQuotations()

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

private getQuotations([array<string|int, mixed> $filters = [] ][, array<string|int, mixed> $options = [] ]) : 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 quotations for all clients)
  • quotation_number The quotation number on which to filter quotations
  • currency The currency code on which to filter quotations
  • quotation_line The (partial) description of the quotation line on which to filter quotations
  • status The status type of the quotations to fetch (optional, default 'open') one of the following:
    • approved Fetches all approved quotations
    • pending Fetches all pending quotations
    • expired Fetches all expired quotations
    • invoiced Fetches all invoiced quotations
    • dead Fetches all quotations with a status of "quotations"
    • lost Fetches all quotations with a status of "lost"
    • draft Fetches all quotations with a status of "draft"
    • all Fetches all quotations
$options : array<string|int, mixed> = []

A list of additional options

  • client_group_id The ID of the client group to filter quotations on
Return values
Record —

The partially constructed query Record object

getRules()

Returns the rule set for adding/editing quotations

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

The input vars

Return values
array<string|int, mixed> —

Quotations rules

getTaxes()

Fetches all taxes for the given quotation

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

The ID of the quotation to fetch

Return values
array<string|int, mixed> —

An array of all tax rules for this quotation

makeQuote()

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

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

An array of quote data including:

  • client_id The client ID the quote belongs to
  • staff_id The staff ID the quote was generated by
  • title The title of the quotation
  • status The status of the quotation, it could be 'draft', 'pending', 'approved', 'invoiced', 'expired', 'dead' or 'lost'
  • currency The ISO 4217 3-character currency code of the quote
  • notes Notes visible to the client
  • date_created The date the quotation was created
  • date_expires The date the quotation expires
  • 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
$client_settings : array<string|int, mixed>
Return values
int —

The quotation ID, void on error

searchQuotations()

Partially constructs the query for searching quotations

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

The value to search quotations for

Tags
see

Quotations::search(), Quotations::getSearchCount()

Return values
Record —

The partially constructed query Record object

sendApprovedEmail()

Sends the Quotation Approved email

private sendApprovedEmail(int $quotation_id) : bool
Parameters
$quotation_id : int

The ID of the quotation to send the approved notification

Return values
bool —

True if the email was sent successfully, false otherwise

sendApprovedNotification()

Sends the Quotation Approved notification

private sendApprovedNotification(int $quotation_id) : bool
Parameters
$quotation_id : int

The ID of the quotation to send the approved notification

Return values
bool —

True if the email was sent successfully, false otherwise

taxUpdateRequired()

Identifies whether or not the given quotation 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 $quotation_id, array<string|int, mixed> $lines, array<string|int, mixed> $delete_items) : bool
Parameters
$quotation_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
Quotations::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 quotation

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

The ID of the quotation to update totals for

Tags
subpackage

app.models

copyright

Copyright (c) 2022, Phillips Data, Inc.

license

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

link

Blesta

 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results