A client user.

The client is one of the most important records tracked by WHMCS. A client object models a single WHMCS customer. Clients can log into WHMCS's client area and can order services, create support tickets, or access all other functionality available in the client area. Their records contain contact information for the client, authentication and payment settings for the client, and other configuration options necessary for the client to properly use WHMCS.

Most objects stored in WHMCS are either directly related to a client or connected to a client through a client's related objects, such as invoices, orders, or quotes.

class Client extends AbstractUser implements ContactInterface, UserInterface

Traits

EmailPreferences

Constants

STATUS_ACTIVE

STATUS_INACTIVE

STATUS_CLOSED

PAYMENT_DATA_MIGRATED

Properties summary

Type Property Description
protected $table
protected $columnMap
$timestamps
protected $dates
protected $booleans
protected $casts
$unique
protected $appends
protected $fillable
protected $hidden
int $id A client's unique id number.
string $firstName A client's first name.
string $lastName A client's last name.
string $companyName The name of the company employing a client.
string $email A client's email address.
string $address1 The first line of the address a client resides at.
string $address2 The second line of the address a client resides at.
string $city The city a client resides in.
string $state The state or province a client resides in.
string $postcode The post or zip code a client resides in.
string $country The two-letter ISO code of the country a client resides in.
string $phoneNumber A client's phone number.
string $taxId A client's tax id.
string $passwordHash A client's stored password hash.
string $twoFactorAuthModule The name of a client's two factor authentication module, if they are using one.
string $twoFactorAuthData A client's two-factor authentication module's internal data, stored as a PHP serialized string.
int $currencyId The id number of a client's preferred currency.
string $defaultPaymentGateway A client's default default payment gateway module.
float $credit The amount of credit a client has available.
bool $taxExempt Whether or not a client is exempt from paying taxes.
bool $overrideLateFee Whether or not a client should be charged late payment fees.
bool $overrideOverdueNotices Whether or not a client should receive overdue invoice notices.
bool $separateInvoices Whether or not a client should receive separate invoices for their purchased services.
bool $disableAutomaticCreditCardProcessing Whether or not a client's invoices should be automatically processed.
DateTime $dateCreated The date a client was created.
string $notes Internal admin-provided notes about a client. These notes are not visible to the client.
int $billingContactId The id number of a client's associated billing contact.
int $securityQuestionId The id number of a client's configured security question.
string $securityQuestionAnswer The encrypted answer to a client's configured security question.
string $creditCardType The type of credit card a client has on file.
string $creditCardLastFourDigits The last four digits of a client's credit card on file.
string $creditCardExpiryDate The encrypted expiration date of a client's card on file.
int $groupId The id number of the group that a client belongs to.
string $storedBankNameCrypt The encrypted name of a client's bank.
string $storedBankTypeCrypt A client's encrypted bank type.
string $storedBankCodeCrypt A client's encrypted bank code.
string $storedBankAccountCrypt A client's encrypted bank account number.
string $paymentGatewayToken A client's payment gateway token, if required by the payment gateway.
Carbon $lastLoginDate The last date a client logged into the client area.
string $lastLoginIp The IP address a client used the last time they logged into the client area.
string $lastLoginHostname The resolved hostname of the IP address used the last time a client logged into the client area.
string $status A client's status, either "Active", "Inactive", or "Closed".
string $language A client's preferred display language.
string $passwordResetKey The auto-generated key from a client's last password reset attempt.
Carbon $passwordResetKeyExpiryDate The date that a client's most recent password reset key will expire
bool $emailOptOut Whether or not to disable sending email to a client.
bool $marketingEmailsOptIn Has the client opted in to marketing emails.
bool $overrideAutoClose If true, do not automatically set this client's account status to 'Closed.'
bool $allowSSO Determines if Single Sign-On is permitted for this client user.
bool $emailVerified Determines if the client's email address ownership has been verified.
string $fullName A client's first name and last name.
string $countryName The full name of the country a client resides in.
string $groupName The name of the group a client belongs to.
array $emailPreferences An array of email preferences for the client
Collection|Service[] $services The services a client has purchased.
Collection|Addon[] $addons The addons a client has purchased.
Collection|Domain[] $domains The domains a client has purchased.
Collection|Contact[] $contacts A client's associated contacts.
Contact $billingContact A client's associated billing contact.
Collection|Quote[] $quotes The quotes assigned to a client.
Affiliate $affiliate A client's affiliate record, if activated as an affiliate.
SecurityQuestion $securityQuestion The security question a client has chosen for authentication.
Collection|Invoice[] $invoices
Collection|Transaction[] $transactions
Collection|CustomFieldValue[] $customFieldValues
$remoteAccountLinks
Collection|Order[] $orders
Currency $currencyrel A client's currency.
string $username A client's username (email).
Carbon $updatedAt Last update of the client data (or 0000-00-00 00:00:00 if no updated since 6.0.0).
Carbon $createdAt Initial creation of the client data (or 0000-00-00 00:00:00 if created before 6.0.0).
Collection|PayMethodInterface[]|Model[] $payMethods
ContactInterface $defaultBillingContact
Collection|Status[] $domainSslStatuses The ssl statuses for the client

Methods summary

Return Type Method Name Description
HasMany|Domain domains() A client can have many domains.
HasMany|Service services() A client can have many services.
HasMany|Addon addons() A client can have many add-on services.
HasMany contacts() A client can have many contacts.
HasOne billingContact() -
HasMany quotes() A client can have many quotes for services.
HasOne affiliate() A client can have an associated affiliate record.
belongsTo securityQuestion() A client can have an associated security question.
HasMany invoices() A client can have many invoices.
HasMany transactions() A client can have many transactions.
HasMany remoteAccountLinks() A client can have many linked remote accounts.
HasMany orders() A client can have many orders.
HasMany|Consent marketingConsent() -
Builder scopeLoggedIn(Builder $query) Apply filter for the currently authenticated user.
Builder scopeEmail($query, $email) Filter by email.
HasOne currencyrel() A client has an associated currency.
static string[] getStatuses() Get client status values.
bool hasDomain(string $domainName) Determines if client has a given domain name.
string generateCreditCardEncryptionKey() Generate the AES key used to encrypt a user's credit card information.
Collection|Alert[] getAlerts(AlertFactory $factory = null) Retrieve a client's alerts.
array|false isCreditCardExpiring(int $withinMonths = 2) Determine if a user's credit card is going to expire within a number of months.
string getFullNameAttribute() "fullName" is the concatenation of first and last name.
string getCountryNameAttribute() Returns the human readable name for the clients country.
string getSecurityQuestionAnswerAttribute(string $answer) Decrypt security question answers from storage.
setSecurityQuestionAnswerAttribute(string $answer) Encrypt security question answers for storage.
string generateCreditCardEncryptedField(string $value) Generate an AES Encrypted string from the passed value.
getUsernameAttribute() -
bool hasSingleSignOnPermission() Returns if the client has Single Sign-On Enabled for their account.
bool isAllowedToAuthenticate() Should the user be allowed to authenticate
bool isEmailAddressVerified() Returns if the client's email address ownership has been verified.
string getEmailVerificationId() Returns the email verification id to verify email ownership.
static string generateEmailVerificationKey() Returns a key used to verify ownership of an email account.
Client sendEmailAddressVerification() Sends the email address verification email to the client.
updateLastLogin(Carbon $time = null, $ip = null, $host = null) -
HasMany|CustomFieldValue customFieldValues() -
getCustomFieldType() -
getCustomFieldRelId() -
bool hasPermission(string|int $permission) This fulfills the UserInterface
HasMany tickets() A client can have many tickets.
bool isOptedInToMarketingEmails() Determine if user is opted in to marketing emails.
Client marketingEmailOptIn(string $userIp = '', bool $performCurrentSettingCheck = true) Opt in to email marketing.
Client marketingEmailOptOut(string $userIp = '', bool $performCurrentSettingCheck = true) Opt out of email marketing.
Client logActivity(string $message) Log activity.
bool|null deleteEntireClient() Deletes a client and all associated data.
static  getGroups() -
needsCardDetailsMigrated() -
needsBankDetailsMigrated() -
needsUnknownPaymentTokenMigrated() -
needsAnyPaymentDetailsMigrated() -
migratePaymentDetailsIfRequired($forceInCron = false) -
markCardDetailsAsMigrated() -
markBankDetailsAsMigrated() -
markPaymentTokenMigrated() -
HasMany payMethods() -
HasOne|BelongsTo defaultBillingContact() Return a model of the billing contact or the client itself
string getGroupNameAttribute() -
HasMany domainSslStatuses() -
generateUniquePlaceholderEmail() -
deleteAllCreditCards() -
static array getUsedCardTypes() Get the card types currently used.
array buildBillingContactsArray() -
PayMethodInterface createRemoteCardPayMethod(Gateway $gateway, string $cardNumber, string $cardExpiryDate, string $remoteToken, string|integer $billingContactId = 'billing', string $description = '', null|string $cardType = null, null|string $cardStartDate = null, null|string $cardIssueNumber = null) -
PayMethodInterface createCardPayMethod(string $cardNumber, string $cardExpiryDate, string|integer $billingContactId = 'billing', string $description = '', null|string $cardType = null, null|string $cardStartDate = null, null|string $cardIssueNumber = null) -
PayMethodInterface createBankPayMethod(string $accountType, string $routingNumber, string $accountNumber, string $bankName, string $accountHolderName, string|integer $billingContactId = 'billing', string $description = '') -
PayMethodInterface createRemoteBankPayMethod(Gateway $gateway, string $remoteToken, string $accountNumber = '', string $accountHolderName = '', string|integer $billingContactId = 'billing', string $description = '') -
float getClientDiscountPercentage() Get client discount percentage.
Client addCredit(string $description, float $amount) Add a credit + credit log entry.
getLink() -

Details

HasMany|Domain domains ()

A client can have many domains.

Return Value

HasMany|Domain

HasMany|Service services ()

A client can have many services.

Return Value

HasMany|Service

HasMany|Addon addons ()

A client can have many add-on services.

Return Value

HasMany|Addon

HasMany contacts ()

A client can have many contacts.

Return Value

HasMany

HasOne billingContact ()

Return Value

HasOne

HasMany quotes ()

A client can have many quotes for services.

Return Value

HasMany

HasOne affiliate ()

A client can have an associated affiliate record.

Return Value

HasOne

belongsTo securityQuestion ()

A client can have an associated security question.

Return Value

belongsTo

HasMany invoices ()

A client can have many invoices.

Return Value

HasMany

HasMany transactions ()

A client can have many transactions.

Return Value

HasMany

A client can have many linked remote accounts.

NB: this will not return remote auth links of contacts associated with the client.

Return Value

HasMany

HasMany orders ()

A client can have many orders.

Return Value

HasMany

HasMany|Consent marketingConsent ()

Return Value

HasMany|Consent

Builder scopeLoggedIn (Builder $query)

Apply filter for the currently authenticated user.

Parameters

Builder $query

Return Value

Builder

Builder scopeEmail ($query, $email)

Filter by email.

Parameters

$query
$email

Return Value

Builder

HasOne currencyrel ()

A client has an associated currency.

Named currencyrel because the name currency conflicts with field name.

Return Value

HasOne

static string[] getStatuses ()

Get client status values.

Return Value

string[]

bool hasDomain (string $domainName)

Determines if client has a given domain name.

Checks for both domains associated to services as well as domain registrations.

Parameters

string $domainName

Return Value

bool

protected string generateCreditCardEncryptionKey ()

Generate the AES key used to encrypt a user's credit card information.

Return Value

string

Collection|Alert[] getAlerts (AlertFactory $factory = null)

Retrieve a client's alerts.

Parameters

AlertFactory $factory

Return Value

Collection|Alert[]

array|false isCreditCardExpiring (int $withinMonths = 2)

Determine if a user's credit card is going to expire within a number of months.

Parameters

int $withinMonths

Return Value

array|false An array with expiring credit card information

string getFullNameAttribute ()

"fullName" is the concatenation of first and last name.

In classic WHMCS objects, we compute a field named "name" which combines the first and last name for convenience in templates.

Return Value

string The combined name

string getCountryNameAttribute ()

Returns the human readable name for the clients country.

Return Value

string

string getSecurityQuestionAnswerAttribute (string $answer)

Decrypt security question answers from storage.

Parameters

string $answer

Return Value

string

setSecurityQuestionAnswerAttribute (string $answer)

Encrypt security question answers for storage.

Parameters

string $answer

string generateCreditCardEncryptedField (string $value)

Generate an AES Encrypted string from the passed value.

Parameters

string $value

Return Value

string

getUsernameAttribute ()

bool hasSingleSignOnPermission ()

Returns if the client has Single Sign-On Enabled for their account.

Return Value

bool

bool isAllowedToAuthenticate ()

Should the user be allowed to authenticate

Return Value

bool

bool isEmailAddressVerified ()

Returns if the client's email address ownership has been verified.

Return Value

bool

string getEmailVerificationId ()

Returns the email verification id to verify email ownership.

Generates a new email verification id and stores it by either updating the row or inserting the row. This prevents stale keys from being used after a request has been made.

Return Value

string

static string generateEmailVerificationKey ()

Returns a key used to verify ownership of an email account.

Return Value

string

Client sendEmailAddressVerification ()

Sends the email address verification email to the client.

Return Value

Client

updateLastLogin (Carbon $time = null, $ip = null, $host = null)

Parameters

Carbon $time
$ip
$host

HasMany|CustomFieldValue customFieldValues ()

Return Value

HasMany|CustomFieldValue

protected getCustomFieldType ()

protected getCustomFieldRelId ()

bool hasPermission (string|int $permission)

This fulfills the UserInterface

Parameters

string|int $permission

Return Value

bool

HasMany tickets ()

A client can have many tickets.

Return Value

HasMany

bool isOptedInToMarketingEmails ()

Determine if user is opted in to marketing emails.

Return Value

bool

Client marketingEmailOptIn (string $userIp = '', bool $performCurrentSettingCheck = true)

Opt in to email marketing.

Parameters

string $userIp
bool $performCurrentSettingCheck

Return Value

Client

Exceptions

AlreadyOptedIn

Client marketingEmailOptOut (string $userIp = '', bool $performCurrentSettingCheck = true)

Opt out of email marketing.

Parameters

string $userIp
bool $performCurrentSettingCheck

Return Value

Client

Exceptions

AlreadyOptedOut

Client logActivity (string $message)

Log activity.

Parameters

string $message

Return Value

Client

bool|null deleteEntireClient ()

Deletes a client and all associated data.

Return Value

bool|null

Exceptions

Exception
Fatal

static getGroups ()

needsCardDetailsMigrated ()

needsBankDetailsMigrated ()

needsUnknownPaymentTokenMigrated ()

needsAnyPaymentDetailsMigrated ()

migratePaymentDetailsIfRequired ($forceInCron = false)

Parameters

$forceInCron

markCardDetailsAsMigrated ()

markBankDetailsAsMigrated ()

markPaymentTokenMigrated ()

HasMany payMethods ()

Return Value

HasMany

HasOne|BelongsTo defaultBillingContact ()

Return a model of the billing contact or the client itself

This is determined by a value set against billingcid.

Return Value

HasOne|BelongsTo

string getGroupNameAttribute ()

Return Value

string

HasMany domainSslStatuses ()

Return Value

HasMany

generateUniquePlaceholderEmail ()

deleteAllCreditCards ()

static array getUsedCardTypes ()

Get the card types currently used.

Return Value

array

array buildBillingContactsArray ()

Return Value

array

PayMethodInterface createRemoteCardPayMethod (Gateway $gateway, string $cardNumber, string $cardExpiryDate, string $remoteToken, string|integer $billingContactId = 'billing', string $description = '', null|string $cardType = null, null|string $cardStartDate = null, null|string $cardIssueNumber = null)

Parameters

Gateway $gateway
string $cardNumber The card number (or last 4 digits). Full card number will not be stored.
string $cardExpiryDate Card expiry date in mmyy format.
string $remoteToken The remote token for the pay method.
string|integer $billingContactId The id of the billing contact to use.
string $description The description for the new pay method.
null|string $cardType The card type to use. Null will attempt to get card type from card number.
null|string $cardStartDate Optional. Card start date in mmyy format.
null|string $cardIssueNumber Optional. The issue number for the card.

Return Value

PayMethodInterface

Exceptions

Exception For missing required values.

PayMethodInterface createCardPayMethod (string $cardNumber, string $cardExpiryDate, string|integer $billingContactId = 'billing', string $description = '', null|string $cardType = null, null|string $cardStartDate = null, null|string $cardIssueNumber = null)

Parameters

string $cardNumber The card number (or last 4 digits). Full card number will not be stored.
string $cardExpiryDate Card expiry date in mmyy format.
string|integer $billingContactId The id of the billing contact to use.
string $description The description for the new pay method.
null|string $cardType The card type to use. Null will attempt to get card type from card number.
null|string $cardStartDate Optional. Card start date in mmyy format.
null|string $cardIssueNumber Optional. The issue number for the card.

Return Value

PayMethodInterface

Exceptions

Exception For missing required values.

PayMethodInterface createBankPayMethod (string $accountType, string $routingNumber, string $accountNumber, string $bankName, string $accountHolderName, string|integer $billingContactId = 'billing', string $description = '')

Parameters

string $accountType A type, such as checking or savings
string $routingNumber Bank routing number
string $accountNumber Bank account number
string $bankName Name of bank the account belongs to
string $accountHolderName Name of the account holder
string|integer $billingContactId The id of the billing contact to use.
string $description The description for the new pay method.

Return Value

PayMethodInterface

Exceptions

Exception For missing required values.

PayMethodInterface createRemoteBankPayMethod (Gateway $gateway, string $remoteToken, string $accountNumber = '', string $accountHolderName = '', string|integer $billingContactId = 'billing', string $description = '')

Parameters

Gateway $gateway
string $remoteToken The remote token for a remote bank account.
string $accountNumber Bank account number
string $accountHolderName Name of the account holder
string|integer $billingContactId The id of the billing contact to use.
string $description The description for the new pay method.

Return Value

PayMethodInterface

Exceptions

Exception For missing required values.

float getClientDiscountPercentage ()

Get client discount percentage.

Return Value

float

Client addCredit (string $description, float $amount)

Add a credit + credit log entry.

Parameters

string $description
float $amount

Return Value

Client