Blesta Source Documentation

Contacts extends AppModel

Contact management

Table of Contents

Methods

__construct() Initialize Contacts
add() Add a contact with the fields given
addNumber() Adds a new number
addType() Add a contact type
delete() Permanently removes this contact from the system.
deleteNumber() Permanently removes a number from the system
deleteType() Delete a contact type and reset the type for all affected contacts to null
edit() Edit the contact with the fields given, all fields optional
editNumber() Updates an existing number
editType() Update the contact type with the given data
get() Fetch the contact with the given contact ID
getAll() Fetches a list of all contacts under a client
getByUserId() Fetch the contact with the given contact ID
getContactTypes() Retrieves a list of client contact types
getList() Fetches a list of all contacts under a client
getListCount() Return the total number of contacts returned from Contacts::getList(), useful in constructing pagination for the getList() method.
getNumber() Fetches a specific number
getNumberLocations() Returns a list of contact number locations
getNumbers() Fetches all numbers for the given contact and (optionally) type
getNumberTypes() Returns a list of contact number types
getPermissionOptions() Returns an array of key/value pairs of all available permission options
getPermissions() Fetch all permissions set for a contact
getType() Retrieve a single contact type
getTypes() Return all existing contact types in the system for the given company
hasPermission() Checks whether or not the contact has permissions for the given area
intlNumber() Internationalizes the given format number (+NNN.NNNNNNNNNN)
setPermissions() Sets permissions for the given contact
validateContact() Validate contact information for add or edit
validateContactNumberLocation() Validates the contact numbers 'location' field
validateContactNumberType() Validates the contact numbers 'type' field
validateContactType() Validates a contact's 'contact_type' field
validateContactTypeId() Validates a contact's 'contact_type_id' field
validateCountrySet() Validates a country is set when a state is provided
validateIsPrimary() Validates whether this contact is the primary contact for a client
validateReceivesInvoices() Validates whether the given contact is the contact whom invoices are addressed to and can be based on the given contact type
adjustInput() Adjusts input for contact creation/editing/validation
getContacts() Partially constructs the query required by both Contacts::getList() and Contacts::getListCount()
getNumberRules() Returns the rule set for adding/editing numbers
getReadOnlyFieldRules() Gets the rules for all contact fields that are read only by the client group
getRequiredFieldRules() Gets the rules for all contact fields that are require by the client group
getRules() Returns the rule set for adding/editing contacts
getTypeRules() Returns the rule set for adding/editing types
permissions() A partial query of contact permissions
Methods

__construct()

Initialize Contacts

public __construct() : mixed

add()

Add a contact with the fields given

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

An array of variable contact info, including:

  • client_id The client ID this contact will be associated with
  • user_id The user ID this contact belongs to if this contact has their own unique user record (optional)
  • staff_id The ID of the staff user, if a staff user is executing the action (optional)
  • contact_type The type of contact, either 'primary' (default), 'billing', or 'other' (optional)
  • contact_type_id The ID of the contact type if contact_type is 'other' (optional)
  • first_name The first name of this contact
  • last_name The last name of this contact
  • title The business title for this contact (optional)
  • company The company/organization this contact belongs to (optional)
  • email This contact's email address
  • address1 This contact's address (optional)
  • address2 This contact's address line two (optional)
  • city This contact's city (optional)
  • state The 3-character ISO 3166-2 subdivision code, requires country (optional)
  • zip The zip/postal code for this contact (optional)
  • country The 2-character ISO 3166-1 country code, required if state is given (optional)
  • numbers An array of number data including (optional):
    • number The phone number to add
    • type The type of phone number 'phone', 'fax' (optional, default 'phone')
    • location The location of this phone line 'home', 'work', 'mobile' (optional, default 'home')
  • verify Whether or not the email should be verified, overrides the company and client group settings
Tags
see
Contacts::addNumber()
Return values
int —

The contact ID, void on error

addNumber()

Adds a new number

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

The contact ID to attach the number

$vars : array<string|int, mixed>

An array of number information including:

  • number The phone number to add
  • type The type of phone number 'phone', 'fax' (optional, default 'phone')
  • location The location of this phone line 'home', 'work', 'mobile' (optional, default 'home')
Return values
int —

The contact number ID of the number created, void if error

addType()

Add a contact type

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

An array of contact type information including:

  • name The name of this contact type
  • is_lang Whether or not 'name' is a language definition
  • company_id The company ID to add the contact type under (optional)
Return values
int —

The contact type ID created, void if error

delete()

Permanently removes this contact from the system.

public delete(int $contact_id) : mixed
Parameters
$contact_id : int

The ID of the contact to remove from the system

deleteNumber()

Permanently removes a number from the system

public deleteNumber(int $contact_number_id) : mixed
Parameters
$contact_number_id : int

The Id of the number to delete

deleteType()

Delete a contact type and reset the type for all affected contacts to null

public deleteType(int $contact_type_id) : mixed
Parameters
$contact_type_id : int

The contact type ID

edit()

Edit the contact with the fields given, all fields optional

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

The contact ID to update

$vars : array<string|int, mixed>

An array of variable contact info, including:

  • user_id The user ID this contact belongs to if this contact has their own unique user record (optional)
  • staff_id The ID of the staff user, if a staff user is executing the action (optional)
  • contact_type The type of contact, either "primary" or "other" (optional, default the current value)
  • contact_type_id The ID of the contact type if contact_type is "other" (optional)
  • first_name The first name of this contact
  • last_name The last name of this contact
  • title The business title for this contact (optional)
  • company The company/organization this contact belongs to (optional)
  • email This contact's email address
  • address1 This contact's address (optional)
  • address2 This contact's address line two (optional)
  • city This contact's city (optional)
  • state The 3-character ISO 3166-2 subdivision code, requires country (optional)
  • zip The zip/postal code for this contact (optional)
  • country The 2-character ISO 3166-1 country code, required if state is given (optional)
  • numbers An array of number data including (optional):
    • id The ID of the contact number to update (if empty, will add as new)
    • number The phone number to add (if empty, will remove this record)
    • type The type of phone number 'phone', 'fax' (optional, default 'phone')
    • location The location of this phone line 'home', 'work', 'mobile' (optional, default 'home')
  • verify Whether or not the email should be verified, overrides the company and client group settings
Tags
see
Contacts::addNumber()
see
Contacts::editNumber()
Return values
stdClass —

object represented the updated contact if successful, void otherwise

editNumber()

Updates an existing number

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

The number ID to update

$vars : array<string|int, mixed>

An array of number information including:

  • number The phone number to add
  • type The type of phone number 'phone', 'fax' (optional, default 'phone')
  • location The location of this phone line 'home', 'work', 'mobile' (optional, default 'home')

editType()

Update the contact type with the given data

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

The contact type ID to update

$vars : array<string|int, mixed>

An array of contact type information including:

  • name The name of this contact type
  • is_lang Whether or not 'name' is a language definition

get()

Fetch the contact with the given contact ID

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

The contact ID to fetch

Return values
mixed —

A stdClass contact object, or false if the contact does not exist

getAll()

Fetches a list of all contacts under a client

public getAll(int $client_id[, string $contact_type = null ][, array<string|int, mixed> $order = ['last_name' => 'asc', 'first_name' => 'asc'] ]) : array<string|int, mixed>
Parameters
$client_id : int

The client ID to fetch contacts for

$contact_type : string = null

The contact type to fetch (i.e. "primary", "billing", or "other") (optional, default all contact types)

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

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

Return values
array<string|int, mixed> —

A list of stdClass objects representing each contact

getByUserId()

Fetch the contact with the given contact ID

public getByUserId(int $user_id, int $client_id) : mixed
Parameters
$user_id : int

The contact user ID to fetch on

$client_id : int

The contact client ID to fetch on

Return values
mixed —

A stdClass contact object, or false if the contact does not exist

getContactTypes()

Retrieves a list of client contact types

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

Key=>value pairs of client contact types

getList()

Fetches a list of all contacts under a client

public getList(int $client_id[, int $page = 1 ][, string $order = ['last_name' => 'asc', 'first_name' => 'asc'] ]) : array<string|int, mixed>
Parameters
$client_id : int

The client ID to fetch contacts for

$page : int = 1

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

$order : string = ['last_name' => 'asc', 'first_name' => 'asc']

The sort and order fields (optional, default the last name and first name ascending)

Return values
array<string|int, mixed> —

An array of objects

getListCount()

Return the total number of contacts returned from Contacts::getList(), useful in constructing pagination for the getList() method.

public getListCount(int $client_id) : int
Parameters
$client_id : int

The client ID to fetch contacts for

Tags
see
Companies::getList()
Return values
int —

The total number of clients

getNumber()

Fetches a specific number

public getNumber(int $contact_number_id) : mixed
Parameters
$contact_number_id : int

The ID of the number to fetch

Return values
mixed —

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

getNumberLocations()

Returns a list of contact number locations

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

A key=>value list of contact number locations

getNumbers()

Fetches all numbers for the given contact and (optionally) type

public getNumbers(int $contact_id[, string $type = null ][, string $location = null ][, array<string|int, mixed> $order = ["FIELD(location,'work','home','mobile')" => 'ASC'] ]) : array<string|int, mixed>
Parameters
$contact_id : int

The contact ID to fetch all numbers for

$type : string = null

The type of number to fetch ('phone', or 'fax', default null for all)

$location : string = null

The location of the number to fetch ('home', 'work', or 'mobile', default null for all)

$order : array<string|int, mixed> = ["FIELD(location,'work','home','mobile')" => 'ASC']

An array of sort and order fields (optional, default phone location ascending)

Return values
array<string|int, mixed> —

An array of stdClass objects representing contact numbers, false if no records found

getNumberTypes()

Returns a list of contact number types

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

A key=>value list of contact number types

getPermissionOptions()

Returns an array of key/value pairs of all available permission options

public getPermissionOptions(int $company_id) : array<string|int, mixed>
Parameters
$company_id : int

The ID of the company to fetch options under

Return values
array<string|int, mixed> —

An array of key/value pairs

getPermissions()

Fetch all permissions set for a contact

public getPermissions(int $contact_id) : array<string|int, mixed>
Parameters
$contact_id : int

The ID of the contact to set permissions for

Return values
array<string|int, mixed> —

An array of stdClass objects, each representing a permission

getType()

Retrieve a single contact type

public getType(int $contact_type_id) : mixed
Parameters
$contact_type_id : int

The contact type ID

Return values
mixed —

An stdClass object representing the contact type, or false if none exist

getTypes()

Return all existing contact types in the system for the given company

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

The company ID to fetch contact types for (optional)

Return values
array<string|int, mixed> —

An array of stdClass objects representing contact types

hasPermission()

Checks whether or not the contact has permissions for the given area

public hasPermission(int $company_id, int $contact_id, string $area) : bool
Parameters
$company_id : int

The ID of the company

$contact_id : int

The ID of the contact

$area : string

The area to check

Return values
bool —

True if permission allowed, false otherwise

intlNumber()

Internationalizes the given format number (+NNN.NNNNNNNNNN)

public intlNumber(string $number, string $country[, string $code_delimiter = '.' ]) : string
Parameters
$number : string

The phone number

$country : string

The ISO 3166-1 alpha2 country code

$code_delimiter : string = '.'

The delimiter to use between the country prefix and the number

Return values
string —

The number in +NNN.NNNNNNNNNN

setPermissions()

Sets permissions for the given contact

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

The ID of the contact to set permissions for

$vars : array<string|int, mixed>

A numerically indexed array of arrays containing:

  • area The area

validateContact()

Validate contact information for add or edit

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

An array of variable contact info, including:

  • contact_id The contact ID to update (required on edit)
  • client_id The client ID this contact will be associated with
  • user_id The user ID this contact belongs to if this contact has their own unique user record (optional)
  • staff_id The ID of the staff user, if a staff user is executing the action (optional)
  • contact_type The type of contact, either 'primary' (default), 'billing', or 'other' (optional)
  • contact_type_id The ID of the contact type if contact_type is 'other' (optional)
  • first_name The first name of this contact
  • last_name The last name of this contact
  • title The business title for this contact (optional)
  • company The company/organization this contact belongs to (optional)
  • email This contact's email address
  • address1 This contact's address (optional)
  • address2 This contact's address line two (optional)
  • city This contact's city (optional)
  • state The 3-character ISO 3166-2 subdivision code, requires country (optional)
  • zip The zip/postal code for this contact (optional)
  • country The 2-character ISO 3166-1 country code, required if state is given (optional)
  • numbers An array of number data including (optional):
    • number The phone number to add
    • type The type of phone number 'phone', 'fax' (optional, default 'phone')
    • location The location of this phone line 'home', 'work', 'mobile' (optional, default 'home')
$edit : bool = false

Whether this data is being validated for an edit (optional, default false)

$validate_client : bool = false

Whether to validate the client ID (optional, default false)

Tags
see
Contacts::addNumber()
Return values
bool —

True if the contact info is valid, false otherwise

validateContactNumberLocation()

Validates the contact numbers 'location' field

public validateContactNumberLocation(string $location) : bool
Parameters
$location : string

The location to check

Return values
bool —

True if validated, false otherwise

validateContactNumberType()

Validates the contact numbers 'type' field

public validateContactNumberType(string $type) : bool
Parameters
$type : string

The type to check

Return values
bool —

True if validated, false otherwise

validateContactType()

Validates a contact's 'contact_type' field

public validateContactType(string $contact_type[, int $contact_id = null ][, int $client_id = null ]) : bool
Parameters
$contact_type : string

The contact type to check

$contact_id : int = null

The ID of the contact being updated

$client_id : int = null

The ID of the contact being added to

Return values
bool —

True if validated, false otherwise

validateContactTypeId()

Validates a contact's 'contact_type_id' field

public validateContactTypeId(int $contact_type_id, string $contact_type, int $client_id) : bool
Parameters
$contact_type_id : int

The contact type ID to check

$contact_type : string

The contact type

$client_id : int

The ID of the client the contact's type is being set for

Return values
bool —

True if validated, false otherwise

validateCountrySet()

Validates a country is set when a state is provided

public validateCountrySet(string $state, string $country) : bool
Parameters
$state : string

The state

$country : string

The country

Return values
bool —

True if a country is set, false otherwise

validateIsPrimary()

Validates whether this contact is the primary contact for a client

public validateIsPrimary(int $contact_id) : bool
Parameters
$contact_id : int

The contact ID

Return values
bool —

True if this contact is a client's primary billing contact, false otherwise

validateReceivesInvoices()

Validates whether the given contact is the contact whom invoices are addressed to and can be based on the given contact type

public validateReceivesInvoices([string $contact_type = null ][, int $contact_id = null ]) : bool
Parameters
$contact_type : string = null

The contact type of the contact (i.e. "primary", "billing", "other"; optional)

$contact_id : int = null

The contact ID

Return values
bool —

True if this contact is the contact whom invoices are addressed to, false otherwise

adjustInput()

Adjusts input for contact creation/editing/validation

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

An array of variable contact info, including:

  • contact_id The contact ID to update
  • client_id The client ID this contact will be associated with
  • user_id The user ID this contact belongs to if this contact has their own unique user record (optional)
  • contact_type The type of contact, either 'primary' (default), 'billing', or 'other' (optional)
  • contact_type_id The ID of the contact type if contact_type is 'other' (optional)
  • first_name The first name of this contact
  • last_name The last name of this contact
  • title The business title for this contact (optional)
  • company The company/organization this contact belongs to (optional)
  • email This contact's email address
  • address1 This contact's address (optional)
  • address2 This contact's address line two (optional)
  • city This contact's city (optional)
  • state The 3-character ISO 3166-2 subdivision code, requires country (optional)
  • zip The zip/postal code for this contact (optional)
  • country The 2-character ISO 3166-1 country code, required if state is given (optional)
  • numbers An array of number data including (optional):
    • number The phone number to add
    • type The type of phone number 'phone', 'fax' (optional, default 'phone')
    • location The location of this phone line 'home', 'work', 'mobile' (optional, default 'home')
$edit : bool = false

Whether this data is being adjusted for an update (optional, default false)

Return values
array<string|int, mixed> —

The adjust input data

getContacts()

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

private getContacts(int $client_id) : Record
Parameters
$client_id : int

The client ID to fetch contacts for

Return values
Record —

The partially constructed query Record object

getNumberRules()

Returns the rule set for adding/editing numbers

private getNumberRules([bool $multiple = false ][, bool $edit = false ][, bool $require_id = false ][, int $client_id = null ][, array<string|int, mixed> &$vars = [] ]) : array<string|int, mixed>
Parameters
$multiple : bool = false

True if validating multiple numbers, false to validate a single number (optional, default false)

$edit : bool = false

True if editing numbers, false otherwise (optional, default false)

$require_id : bool = false

True to require ID when editing numbers, false otherwise (optional, default false)

$client_id : int = null

The ID of the client this contact is associated with

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

The input vars

Return values
array<string|int, mixed> —

Number rules

getReadOnlyFieldRules()

Gets the rules for all contact fields that are read only by the client group

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

An array containing the parameters to validate

$edit : bool = false

Whether this data is being validated for an edit (optional, default false)

$staff_id : int = null

The ID of the staff user, if a staff user is executing the action (optional)

Return values
array<string|int, mixed> —

A list of rules with the addition of the client groups read only fields

getRequiredFieldRules()

Gets the rules for all contact fields that are require by the client group

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

An array containing the parameters to validate

$edit : bool = false

Whether this data is being validated for an edit (optional, default false)

$staff_id : int = null

The ID of the staff user, if a staff user is executing the action (optional)

Return values
array<string|int, mixed> —

A list of rules with the addition of the client groups required fields

getRules()

Returns the rule set for adding/editing contacts

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

Whether the input is being validated for an edit

Return values
array<string|int, mixed> —

Contact rules

getTypeRules()

Returns the rule set for adding/editing types

private getTypeRules() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Type rules

permissions()

A partial query of contact permissions

private permissions(int $contact_id) : Record
Parameters
$contact_id : int

The ID of the contact to fetch permissions for

Return values
Record
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