WHMCS Documentation - User contributions [en]

Further Security Steps

2016-06-21T20:03:22Z

Steven.Mueller:

WHMCS has many features built-in to help keep your data safe, but here are several simple extra steps you can take to secure your WHMCS installation even further.

==Secure the Writeable Directories==

We recommend moving all writeable directories to a non-public directory above your web root to prevent web based access. There are three writeable directories required for WHMCS to function, they are: "attachments", "downloads" and "templates_c"

<div class="docs-alert-warning">We recommend moving all writeable directories to a non-public location above your web root to prevent web based access.</div>

When you move the directories, you need to provide WHMCS with the new paths to use them. You do this by adding (or updating if they already exist) the following lines in the ''configuration.php'' file within the root WHMCS directory.

<source lang="php">
$attachments_dir = "/home/username/attachments/";
$downloads_dir = "/home/username/downloads/";
$templates_compiledir = "/home/username/templates_c/";
</source>

In the above example, "username" is the cPanel username and so the 3 folders are located in the home directory, above public_html.

<div class="docs-alert-info">Note that if you are running suPHP or phpSuExec chmod 755 should be sufficient permissions to make the directories writeable as this is the highest permission available for both folders and files when running in that condition.</div>

==Secure the `configuration.php` File==

We recommend adjusting the permissions set for the "configuration.php" file located in your WHMCS root directory. This file contains sensitive data that cannot be recovered without a backup of the file. To avoid accidentally overwriting, editing or deleting the file, change the permission setting of this file to `400`. This provides read only access to the file by the system and prevents anyone else from reading, editing or executing the file.

To change the permissions on this file, you can run the following command from shell while in your WHMCS root directory:
<pre>
chmod 400 configuration.php
</pre>

<div class="docs-alert-warning">
<span class="title">Attention!</span>
<p>Some systems may require you to set the permission to 440 or 444 depending on how the server is configured. For most, 400 should suffice, but if you encounter an error loading the application after setting the permission to 400, try 440 and then 444.</p>
</div>
<div class="docs-alert-warning">
<span class="title">License Key Updates</span>
<p>Should you need to ever update your license key, you must set the permissions on this file to 755 to allow the system to edit the file. Once the key is updated, you can revert the permissions to 400.</p></div>

==Move the Crons Directory==

{{:Custom Crons Directory}}

==Restrict Access by IP==

For increased protection, if your staff use fixed IP addresses, you can add even more protection to your admin area by restricting access to a specific set of IPs. This is done by creating a file with the name .htaccess within your WHMCS admin directory, with the following content:

<source lang="php">
order deny,allow
allow from 12.34.5.67
allow from 98.76.54.32
deny from all
</source>

You can specify as many different '''allow from''' lines as you require. Or you can even allow entire IP subnet's by specifying just the first part of an IP, for example: "12.34.". This is called Htaccess IP Restriction.

==Change your WHMCS Admin Folder Name==

Customising the url of your WHMCS admin area makes it harder for boths and malicious users to find it. It is not required, but if you wish to do so, find out how here: [[Customising the Admin Directory]]

==Restrict Database Privileges==
For day to day use, only the following database privileges are required. All others may be disabled.

*DELETE
*INSERT
*SELECT
*UPDATE
*LOCK TABLES

Please note that installation, upgrading, activating, and deactivating modules require the following additional privileges.

*ALTER
*CREATE
*DROP
*INDEX

[[Installation|<< Back to Installation Overview]]

CentovaCast

2016-05-24T16:35:36Z

Steven.Mueller: /* Common Error Codes */ DOCS-6466: Broken Link on CentovaCast server

{{Provisioning_Module
| changepw = Yes
| clientarealink = Yes
| additional = Start, Stop and Restart Stream}}
Centova Cast is an internet radio stream hosting control panel. To find out more about it, please refer to http://www.centova.com/pages/cast/

The guides below explain how to setup and utilise the Centova Cast integration with WHMCS.

==Setting Up a CentovaCast Product==

#Login to WHMCS, go to Setup, and then click Manage Servers. Then, click Add New Server.
#On the Add New Server page, fill out the following fields:

Name - Set this to the hostname of the machine on which Centova Cast is running.

IP Address: Set this to the IP address of the machine on which Centova Cast is running.

Hostname: Enter the complete URL to your Centova Cast installation, for example:
http://centovacast.yourdomain.com/cast/

Type: Select Centovacast from the list.

Username: Set this to: admin

Password: Enter your Centova Cast administrator password.

All other fields can be ignored. When finished, click Create Server.

#Next, go to Setup, and then click Products/Services. Then, click Create a New Product.
#Select Shared Hosting Account and select a suitable product group and name. Then, click Continue.
#On the Module Settings tab, fill out the following fields:

Module Name - Select "Centovacast" from the list.

Account template name - Enter the name of the Centova Cast account template to use for this
package. You can create your account templates in Centova Cast by clicking “Account Templates”
This feature allows you to predefine completely custom configurations for each package.

Max listeners - Specify the maximum number simultaneous listeners for this stream. You may
optionally leave this blank to use the value specified in the account template.

Max bit rate - Specify the maximum bit rate (in kbps) for this stream. You may optionally
leave this blank to use the value specified in the account template.
*Data transfer limit - Specify the monthly data transfer limit for this stream. You may
optionally leave this blank to use the value specified in the account template.

Disk quota - Specify the disk quota for this stream (which must be large enough to
accommodate all of this server's configuration files, log files, and any media uploaded for
the autoDJ). You may optionally leave this blank to use the value specified in the account
template.

Start server - Set this to “yes” to automatically start the server after provisioning, or
“no” if you want the user to start it manually before using it. Note that this only applies
to non-autoDJ streams; if an autoDJ is enabled, it cannot be started until media is uploaded.

#This step is optional. If you would like to allow your users to “build their own” packages, and have WHMCS to prompt the user for various stream limit options (bit rate, data transfer limit, etc.) and be able to set custom pricing for each option, click the Configurable Options tab.
#Next, click the the Add New Configurable Option link, and follow the directions to create one of the following options. Note that in all cases, the “Option Name” field is case-sensitive and must precisely match what is shown below or the option will not be recognized by Centova Cast.

Max listeners - This allows the user to specify a custom listener limit. Enter Max listeners
in the Option Name field to begin. Next, in the Add Option field, enter the number of
listeners, then enter the extra fee for this number of listeners, and click Save Changes.
Repeat this process for each listener limit you wish to offer.

Max bit rate - This allows the user to specify a custom maximum bit rate (in kbps). Enter Max
bit rate in the Option Name field to begin. Next, in the Add Option field, enter the bit rate,
then enter the extra fee for this bit rate, and click Save Changes. Repeat this process for
each bit rate you wish to offer. Note that Centova Cast treats this as a numeric value in
kbps, and will strip any non-numeric characters out of this value before attempting to use it.

Data transfer limit - This allows the user to specify a custom data transfer limit (in MB per
month). Enter Data transfer limit in the Option Name field to begin. Next, in the Add Option
field, enter the limit (in MB), then enter the extra fee for this limit, and click Save
Changes. Repeat this process for each limit you wish to offer. Note that Centova Cast treats
this as a numeric value in megabytes, and will strip any non-numeric characters out of this
value before attempting to use it.

Disk quota - This allows the user to specify a custom disk quota (in MB). Enter Disk quota
in the Option Name field to begin. Next, in the Add Option field, enter the quota (in MB),
then enter the extra fee for this quota, and click Save Changes. Repeat this process for each
quota you wish to offer. Note that Centova Cast treats this as a numeric value in megabytes,
and will strip any non-numeric characters out of this value before attempting to use it.

#All other fields should be filled out in the usual manner, as when creating any other WHMCS product. When finished, click Save Changes to create your product.

The Centova Cast module is now ready to use, and will function like any other built-in WHMCS module (CPanel, Plesk, etc.)

==Common Error Codes==

* '''Unsupported protocol:''' - this indicates you have an incorrect value for hostname field in the server setup. Double check to ensure you have entered the full URL to Centova Cast as instructed in the steps above.

* '''Invalid source/server type:''' - this indicates you haven't entered an account template name in the products module settings, or that the name entered is invalid and not found within the Centova Cast system.

For further assistance, Centova's documentation is available @ http://www.centova.com/docs/cast/centovacast_install.pdf
{{modules}}

Products and Services

2016-05-24T15:45:53Z

Steven.Mueller: /* Pricing Tab */ DOCS-6455: Clarify how to populate the Termination Email field in the Pricing Tab

Products are configured via the '''Setup > Products/Services > Products/Services''' page

Basic instructions for creating your first product group and product can be found under [[Setting Up Your First Product]]. This page explains all the advanced options available, including hiding products, stock control and upgrades.

[[File:Videotutorial.png‎|center|link=http://www.youtube.com/watch?v=0lqzsTSUGw0&hd=1|Watch Video Tutorial]]

==Product Groups==
Products are organised on the order form by group, as each group has a separate page, this means products can be split into categories or across several pages for ease of display. For example you may wish to list your shared hosting plans on a separate page to the reseller plans. Clients can switch between groups on the order form or you can link to them directly (see [[#Links Tab]]).

*To create a product group click the '''Create a New Group''' link
*Enter a name for the group - this will be displayed on the order form
* Under normal circumstances all product groups will use the system default order form template specified in the general settings. However if you wish to use a different template for just this group, select it from the '''Order Form Template''' option here.<br/>'''N.B.''' Any order form template selected here cannot be overwritten by the carttpl variable in the link URL.
*Use the tick boxes to select which ''payment gateways'' will be offered on the checkout page to pay for products within this group.
*To hide this group from the order form tick the ''Hidden'' checkbox
*Click ''Create Group''. To edit the group at a later date click the corresponding Edit icon on the Products/Services page.

==Products==
To create a product click the '''Create a New Product''' link and you will see these three options:
* '''Product Type''' - There are 4 options to choose from and used to determine only how WHMCS should handle it. This is only for system use - you use the groups to divide products into categories for your own use.
**Shared Hosting - for web hosting accounts
**Reseller Hosting - for web hosting reseller accounts
**Dedicated/VPS Server - for servers and displays server hostname, ns & root pw fields on signup
**Other - for anything else
*'''Product Group''' - The group the product belongs to for display on the order form
*'''Product Name''' - The name to display to customers and throughout the admin area
Once created the following options will be available for configuration. To edit a product at a later date click the corresponding Edit icon on the Products/Services page.

==Group and Product Sorting==

Groups and Products are sortable using the crosshair icon on the appropriate row. This is on the left for Groups and the right for Products.

[[File:Drag_and_drop_sorting.png|center|850x250px]]

After moving, a success message will appear on the top right of the page to show the sort order has saved.

[[File:Product_drag_and_drop_success.png]]

It is not possible to move products between groups using the drag and drop method.
===Details Tab===
This is the first tab you see and contains general information about a product including its name and product group.

* '''Product Type''', '''Product Group''' and '''Product Name''' - See above [[#Products]]
*'''Product Description''' - The detailed information displayed on the order form relating to this product
*'''Welcome Email''' - The email template to send when the product is activated. You can create custom email templates to use on different products - see [[Email Templates]] for more info.
*'''Require Domain''' - To show the domain registration options on ordering. Should always be enabled for hosting and disabled for any other products that don't require a domain name.
*'''Stock Control''' - Can be used if you have a specific quantity of an item available (for example servers) or a limited special offer product - tick to enable and enter a quantity remaining and WHMCS will stop orders when it reaches zero. When a stock controlled item is cancelled (either by cancellation request or clicking "Cancel Order" on an order) the stock level will automatically increase. However if a member of staff manually changes the product to cancelled or terminated status it will not re-add stock to the product.
*'''Sort Order''' - Can be set to a number to overide the default product ordering of alphabetical names. A product with sort order of 0 will appear in the list first, 1 will be beneath that, 2 beneath that etc..
*'''Apply Tax''' - Tick if tax rules should be applied to this product. For more information refer to [[Tax/VAT Rules]].
*'''Hidden''' - Tick to not show the product on the order form - can still be ordered using the direct order links
*'''Retire''' - When ticked the product is hidden from admin area lists, such as the Products/Services dropdown in the client's Products/Services tab.

===Pricing Tab===
This second tab is where the prices and length of the product are specified.
[[File:Price grid.png|thumb|Price Grid]]
*'''Payment Types''' - consists of Free, One Time & Recurring options
*When One Time or Recurring payment types are selected, the '''pricing grid''' will appear for entry of the product price. Enable each billing cycle by ticking the corresponding '''Enable''' checkbox.
**For Free products the grid will not appear as one cannot specify a price for a free product.
**For One Time products, enable the One Time/Monthly column and enter your prices into that column.
**For Recurring pricing types there are several billing cycles to choose from depending on how often you want clients to be billed. You can enable as many or as few as you like.
**The '''setup fee''' in each column allows you to specify different setup fees depending on the cycle chosen, for example you may charge setup fees on monthly cycles and offer free setup if paid annually
**If you do not wish to offer a particular billing cycle, UNtick the Enable checkbox to '''disable''' it. In this screenshot the product will only be available monthly or annually with no setup fee.
*'''Allow Multiple Quantities''' - When enabled this option allows clients to choose the quantity of this product they wish to order, on the checkout page an option will be available. The product must require no additional configuration such as product custom fields, configurable options.
*'''Recurring Cycles Limit''' - For Recurring payment types the default value 0 will invoice indefinitely until cancelled. However by entering a value in this field you can limit the number of times this product will invoice the client. For example entering 5 on a monthly product would cause no invoice to be generated in the 6th month after ordering.
*'''Auto Terminate/Fixed Term''' - You can setup products to automatically terminate after a set number of days from the date of signup. This can be used to offer free trial products for a certain period of time, or time limited products that should only recur for a certain number of cycles before stopping.
**To enable enter the number of days to wait before terminating, and choose an email template to be sent to the client when the termination occurs (for example an up-selling email to promote your paid products in the case of a trial, or confirmation of payment completing for instalment payment situations). Set the Auto Terminate/Fixed Term value to 0 to disable this feature.
**Entering a number in this field will cause the product to be terminated when the cron runs x days after the product registration date.
*'''Termination Email''' - When the above feature is enabled, choose an email to be sent to the client when the product is terminated.
<div class="docs-alert-info">
<span class="title">Note:</span><br />
The Termination Email dropdown field is only populated with custom product type email templates. For more information on creating a custom email template, please visit [http://docs.whmcs.com/Email_Templates http://docs.whmcs.com/Email_Templates]
</div>
*'''Prorata Billing''' - This allows you to bill products on a specific day of the month and charge a prorata'd amount at the initial time of order. If enabled all clients will be charged on one exact day each month. When disabled the product will use the default anniversary billing system (eg. Jun 15 - Jul 15).
<div class="docs-alert-info">
<span class="title">Note:</span><br />
Prorata billing is not compatible with the free domain logic or having domain renewal invoices generated further in advance than other products.
</div>
*'''Prorata Date''' - If you set this to 1, then all clients would be charged on the 1st of each month.
*'''Charge Next Month''' - After this day of the month has been reached, a client will also be charged for the next month in their initial payment when signing up on a monthly billing cycle. If you had prorata date set to 1, and a client signed up on the 30th of the month, they'd only be charged a tiny amount without this setting. So it is pro-rated amount + next month in advance.<br/>'''TIP:''' If you wish to pro-rate a product but not use the 'charge next month' feature, set "Prorata Date" to a normal value and "Charge Next Month" to 32.

===Module Settings (aka Provisioning)===

This tab specifies which server type the product will use and how WHMCS will behave when this product is ordered.
*From the Module Name dropdown menu select the type of server you're using
*The options you will see depend upon the module chosen, and more info specific to each module can be found in the [[Server_Modules|Provisioning Modules]] section
*If a product has no specific module to be linked to then you can set it to "[[Auto_Release|Autorelease]]" in order to have the activation simulated and therefore welcome email sent automatically
*There are 4 automation settings to choose from for product activation and they are:
**Automatically setup the product as soon as an order is placed - this will setup instantly usually used for free products
**Automatically setup the product as soon as the first payment is received - this will perform the setup as soon as the order is paid for
**Automatically setup the product when you manually accept a pending order - this will perform the setup only when an admin has manually reviewed and accepted the order
**Do not automatically setup this product - never auto setup the product - admins can still initiate manually from the product details page under a clients profile

===Custom Fields===

From this tab you can create custom fields for this product, allowing you to collect additional information from your clients on the order form required for supplying the product.
*Field types consist of text boxes, dropdown selections, yes/no checkboxes, memo text boxes and password fields (text entered here with appear as asterisks ****)
*Fields can be set as admin only for private data, required/optional on the order form, displayed on the order form or only in the client area, or displayed on invoices (such as VAT numbers)
*See [[Custom_Fields|Custom Fields]] for more info

===Configurable Options===

Use this tab to select which configurable options are associated with the product, they can be displayed on the order form or in the client area.
*Configurable Options allow you to give your clients options which alter the price of the product
*Refer to [[Addons_and_Configurable_Options|Addons & Configurable Options]] for more info

===Upgrades===

The sixth tab allows you to specify whether the client can upgrade or downgrade from this product to another.
*Upgrades/downgrades can be fully automated by WHMCS with many of the modules
*All you need to do on this tab is select the products that the product can be upgraded or downgraded to
*Use Ctrl+Click to select multiple products
*There is also a checkbox for enabling the upgrades of configurable options if there are any on the product
*From the '''Upgrade Email''' dropdown menu you can select an email template to be sent when a client upgrades to this product. A new Product email template will first need to be created under Setup > Email Templates.
*See the [[Automated_Upgrades_and_Downgrades|Automated Upgrades and Downgrades]] article for more info on how upgrades/downgrades are calculated and processed.

===Free Domain===

Use this tab to configure the offer of a free domain with this product is desired
*WHMCS lets you offer free domains with your packages when purchased with certain payment terms
*For example you might want to offer a free domain when a package is purchased annually as an incentive
*Refer to the [[Domains_Configuration#Offering_Free_Domain_Registration_with_Selected_Packages|Offering Free Domain Registration]] article for more details on how to configure it

===Other===

The penultimate tab contains miscellaneous settings such as product affiliate rates, product downloads and overage billing.
*'''Custom Affiliate Payout''' - These settings allow you to specify a custom payout rate for this specific product if using the built in affiliate system, this setting overrides the system default commission rate, it can even be disabled.
*'''Affiliate Pay Amount''' - Based on your setting above to either percentage or fixed amount, this is the percentage or amount paid for a purchase of this product
*'''One Time Payout''' - Tick this if you want to pay only a one off commission
*'''Subdomain Options''' - Enter a domain in the format ".yourdomain.com" if you want to offer a free subdomain option for the domain at signup. You can offer more than one by entering a comma separated list, eg. ".yourdomain.com,.yourdomain.net"
*'''Product Downloads''' - Lets you offer files to be automatically released to the customer when the product is activated. See [[Product Downloads Distribution]] for more information
*'''Overage Billing''' - Allows you to bill for the product based on disk and bandwidth usage for the month. Refer to [[Disk Space and Bandwidth Overage Billing]] for more information.

===Links tab===

The final tab contains some ready-made URLs to add to a webpage linking to this product.
*Each URL will add the product to the shopping cart and jump straight to the configuration step
*There are many more possible variations, refer to [[Linking to WHMCS]].

Interacting With The Database

2016-05-24T15:43:18Z

Steven.Mueller: /* The Query Manager */

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component. This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [https://laravel.com/docs/4.2/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Interacting With The Database

2016-05-24T15:41:41Z

Steven.Mueller: /* The Schema Manager */ Docs-6452: Fix dead links on the Interacting With The Database page

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component. This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [http://laravel.com/docs/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Interacting With The Database

2016-05-24T15:41:20Z

Steven.Mueller: /* The Query Manager */ DOCS-6452: Fix dead links on the Interacting With The Database page

=Database connectivity changes in WHMCS 6.0=

The mysql PHP extension was deprecated when PHP 5.5 was released in June 2013<ref>http://php.net/ChangeLog-5.php#5.5.0</ref> and is scheduled to be removed in PHP 7<ref>https://wiki.php.net/rfc/remove_deprecated_functionality_in_php7</ref>. WHMCS 6.0 introduces a new database connection and library to ensure compatibility with modern PHP environments and best practices.

==New functionality==

WHMCS 6.0 incorporates the Laravel framework 4.1's database component. This library includes a Database Abstraction Layer (DBAL) called "Capsule" and an Object Relational Mapping (ORM) library called "Eloquent". The new DBAL is based on the PHP Data Objects (PDO MySQL) extension and uses WHMCS's existing <tt>configuration.php</tt> file. No configuration file changes are required to use the new database connection.

The Capsule DBAL component introduces two libraries to WHMCS, a query manager for running database queries and a schema manager for an abstracted API to table management. Capsule's underlying PDO connection is also available for advanced database usage. Capsule has three static methods to get to these components:

* '''Capsule::table(string $tableName)''': Access the query manager for the given table.
* '''Capsule::schema()''': Access the schema manager for the WHMCS database.
* '''Capsule::connection()''': Access the connection manager to interact with the underlying database connection.

'''Note:''' WHMCS 6.0 makes two connections to the database. One connection is made through the legacy mysql extension to handle existing hooks, modules, and other customizations. The other connection is made by PDO to drive new DBAL and model based functionality in the program.

==Deprecated functionality==

The current [[SQL Helper Functions]] are present in WHMCS 6.0 and above, but are now deprecated and may be removed in a later version of the product:
* '''select_query()'''
* '''update_query()'''
* '''insert_query()'''
* '''full_query()'''

The mysql extension driven database connection is now deprecated and may be discontinued in a later version of the product. WHMCS encourages all third party developers to use the Capsule DBAL and PDO connection for all new database interaction.

=Using Capsule=

Declare an alias to Laravel's database manager in your project file's <tt>use</tt> block to access Capsule:

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Run queries or modify tables as you like.
</syntaxhighlight>

==The Query Manager==

: ''Please see [http://laravel.com/docs/queries Laravel's query documentation] for more information.''

The '''Capsule::table(string $tableName)''' method provides access to the query manager. Declare it with the name of the table you wish to query as it's first parameter to interact with that table. The query manager has a wide range of functionality to perform advanced select, join, insert, update, and delete statements. Capsule's select calls return rows as ''stdClass'' objects.

Capsule escapes all input, so it is not necessary to add escaping slashes to variables passed to these methods.

All of Capsule's methods throw an exception on failure. Please place Capusle calls in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling and to avoid potential fatal errors in your hook, module, or other customization.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Print all client first names using a simple select.

/** @var stdClass $client */
foreach (Capsule::table('tblclients')->get() as $client) {
echo $client->firstname . PHP_EOL;
}

// Rename all clients named "John Deo" to "John Doe" using an update statement.
try {
$updatedUserCount = Capsule::table('tblclients')
->where('firstname', 'John')
->where('lastname', 'Deo')
->update(
[
'lastname' => 'Doe',
]
);

echo "Fixed {$updatedUserCount} misspelled last names.";
} catch (\Exception $e) {
echo "I couldn't update client names. {$e->getMessage()}";
}
</syntaxhighlight>

==The Schema Manager==

: ''Please see [http://laravel.com/docs/4.1/schema Laravel's schema builder documentation] for more information.''

Use the '''Capsule::schema()''' method to access the schema manager to modify table schema if necessary. The schema manager has support for creating, dropping and truncating tables and for modifying columns, indexes, and keys.

'''Note''': WHMCS does not recommend changing default table schema as that can affect product functionality.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Create a new table.
try {
Capsule::schema()->create(
'my_table',
function ($table) {
/** @var \Illuminate\Database\Schema\Blueprint $table */
$table->increments('id');
$table->string('name');
$table->integer('serial_number');
$table->boolean('is_required');
$table->timestamps();
}
);
} catch (\Exception $e) {
echo "Unable to create my_table: {$e->getMessage()}";
}
</syntaxhighlight>

==The Connection Manager==

The '''Capsule::connection()''' method provides low-level access to the database connection itself. Use it to initiate transactions with automatic commit and rollback or to access the underlying PDO connection to perform manual database queries outside the DBAL. The connection manager also has methods to retrieve query and schema managers.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
try {
Capsule::connection()->transaction(
function ($connectionManager)
{
/** @var \Illuminate\Database\Connection $connectionManager */
$connectionManager->table('my_table')->insert(
[
'name' => $_POST['name'],
'serial_number' => $_POST['serialNumber'],
'is_required' => (int)(bool) $_POST['isRequired'],
]
);
}
);
} catch (\Exception $e) {
echo "Uh oh! Inserting didn't work, but I was able to rollback. {$e->getMessage()}";
}
</syntaxhighlight>

===Getting to PDO===

Use the connection manager's '''getPdo()''' method to retrieve the underlying PDO connection instance. Use the PDO connection to perform manual queries and advanced database usage.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Perform potentially risky queries in a transaction for easy rollback.
$pdo = Capsule::connection()->getPdo();
$pdo->beginTransaction();

try {
$statement = $pdo->prepare(
'insert into my_table (name, serial_number, is_required) values (:name, :serialNumber, :isRequired)'
);

$statement->execute(
[
':name' => $_POST['name'],
':serialNumber' => $_POST['serialNumber'],
':isRequired' => (bool) $_POST['isRequired'],
]
);

$pdo->commit();
} catch (\Exception $e) {
echo "Uh oh! {$e->getMessage()}";
$pdo->rollBack();
}
</syntaxhighlight>

=Troubleshooting=

==Exceptions==

All Capsule methods throw an exception on failure. Catch these exceptions and analyze their messages and stack traces to help determine the nature of the failure. WHMCS recommends placing all database interactivity in <tt>try</tt>/<tt>catch</tt> blocks for graceful error handling.

==The Capsule Query Log==

The connection manager's '''getQueryLog()''' method returns an array of all queries made during the life of the page request. Queries are stored in the log as an array containing the query run, the parameter bindings passed to the query, and the time it took for the query to execute, measured in milliseconds.

<syntaxhighlight lang="php">
<?php

use Illuminate\Database\Capsule\Manager as Capsule;

// Loop through each Capsule query made during the page request.
foreach (Capsule::connection()->getQueryLog() as $query) {
echo "Query: {$query['query']}" . PHP_EOL;
echo "Execution Time: {$query['time']}ms" . PHP_EOL;
echo "Parameters: " . PHP_EOL;

foreach ($query['bindings'] as $key => $value) {
echo "{$key} => {$value}" . PHP_EOL;
}
}
</syntaxhighlight>

==The WHMCS Activity Log==

All uncaught PDO-based query failures, including those made by Capsule and manual PDO queries, are written to to the WHMCS activity log. View the system activity log to view the details of these failed queries.

=See Also=
* [[SQL Helper Functions]] (functional, but deprecated in WHMCS 6.0)

=External Links=
* [http://laravel.com/docs/4.2/queries Query Builder - Laravel 4.2]
* [http://laravel.com/docs/4.2/schema Schema Builder - Laravel 4.2]
* [http://php.net/manual/en/book.pdo.php PHP: PDO]

=References=
<references />

Support Tab

2016-05-24T15:36:39Z

Steven.Mueller: /* Client Tickets Require Login */ DOCS-6447: Client Tickets Require Login functionality is incorrectly documented

<br/><br/>{{General Settings}}

For information regarding the support centre in WHMCS [[Support_Center|refer to this page]].

===Support Module===
If a third party support system is installed, select it here.

===Support Ticket Mask Format===
This options allows for the customisation of the support ticket number assigned to new tickets as they are opened. Entering the following codes into the mask field will change the format of the ticket number, you can even add letters and dates:

<source lang="php">
%A - Uppercase letter | %a - Lowercase letter | %n - Number | %y - Year | %m - Month | %d - Day | %i - Ticket ID
</source>

For example a mask format configuration of '''%A%A%A - %n%n%n%n - %y''' would result in a ticket number of '''AAA - 111 - 2013'''. Where %A is replaced with any random uppercase letter and %n is replaced with any random number between 0-9.

<div class="docs-alert-info">
<span class="title">'''Note:'''</span><br />
The maximum length of the ticket mask is 15 characters.
</div>

===Ticket Reply List Order===
Choose the order support ticket messages are displayed when viewing a ticket in the admin area.

===Ticket Reply Email Limit===
Specifies the maximum number of emails you wish to receive into your support system from an individual email address within a 15 minute period. This is useful if a client opens a ticket and has an auto-responder active on their email address; the auto-responder replies to your message, the support system sends an automated acknowledgement email, their auto-responder responds ad infinitum. By default WHMCS will prevent the 10th email being imported into the support system.

===Show Client Only Departments===
By default support departments with the ''Clients Only'' option enabled are hidden from visitors on the ticket submission page. Ticking this option will cause such departments to be displayed to visitors and allow them to submit tickets to them.

===Client Tickets Require Login===
Enabling this will prompt clients to login before they can view a support ticket. This will not prevent unregistered users from viewing their tickets.

===Attachment Thumbnail Previews===
When enabled a thumbnail sized preview of any images attached to a support ticket will be displayed, allowing you quickly identify & see what's in the attachment you're looking for without even needing to open it.

===Knowledgebase Suggestions===
Enabling will display the title and first line of articles from your knowledgebase relevant to the support ticket message a customer is typing. It is displayed between the ticket body and the submit button. You must have at-least 5 articles in your KB if 30 words each before this feature will function.

===Support Ticket Rating===
A star-rating system will appear below each staff reply when enabled. Customers can rate the responses on a scale of 1-5 and the Support Ticket Ratings Reviewer report is available with the results.

===Ticket Closure Feedback Request===
In addition to the above option, you can also send an email to users once a support ticket has been closed. They will be directed to a page asking the client to rate and provide comments on each member of staff's response to the ticket as well as a general comment. The message will only be sent once per ticket and only for tickets with at-least one staff reply.

The results are collated into two reports under the Reports tab; Ticket Feedback Scores and Ticket Feedback Comments.

If auto-close ticket notifications are also enabled the feedback email will take precedence. Ie. The feedback email will be sent instead of the ticket closure notification.

===Prevent Email Reopening===

Enabling this setting will prevent replies by email from re-opening a ticket once it has been closed. Instead, when a user attempts to reply to a closed ticket via email, the user is sent an email based on the email template "Closed Ticket Bounce Message" and the reply is not added to the ticket.

<div class="docs-alert-info">
<span class="title">'''Note:'''</span><br />
This does not prevent users from replying to and re-opening closed tickets from the client area.
</div>

For registered clients, the email message they receive explains that if they wish to re-open the ticket they attempted to reply to, that they can login to the client area and do so from there. For non-registered users, they need to open a new ticket and are instructed as such.

===Update Last Reply Timestamp===
With the '''Every time a reply is made''' option selected, whenever a client replies to a support ticket the "Last Reply" timestamp will be reset. This can mean that a client bumping a ticket actually delays a staff response as it would move to the back of the queue. Choosing the '''Every time for staff replies, only on a change of status for clients''' option will prevent this by only resetting the "Last Reply" timestamp when a member of staff replies or when the ticket status is changed.

===Disable Reply Email Logging===
When ticked, ticket responses will not be recorded in the email log. This saves some disk space in the database as it is already logged in the ticket itself.

===KB SEO Friendly URLs===
Enabling this requires mod_rewrite enabled on your server, it will rewrite ''/knowledgebase.php?action=view&id=1'' to "/knowledgebase/1/How_do_I_login.html" for example. Making your knowledgebase, announcements and downloads more friendly to search engines. For more information [[Support_Center#Search_Engine_Friendly_URLS|refer to this page]].

===Allowed File Attachment Types===
Specify the file types that customers are permitted to attach to support tickets. For example .jpg,.gif,.jpeg,.png<br />
It is not possible to accept .php attachments for security reasons as this could potentially allow someone to upload a malicious script to your server.

===Network Issues Require Login===
When enabled, only customers who are logged in will be able to view the network issues pages.

===Include Product Downloads===
If a product has an [[Product_Downloads_Distribution|associated download]] it is usually only available on the product details page, ticking this option will also display this file on the Downloads page. Clients will still only be able to download the file if they own the relevant product.

Using Models

2016-05-10T19:56:56Z

Steven.Mueller: DOCS-6461 - Broken link on "Using Models" docs page

WHMCS 6.0 introduces a code-driven method for interacting with data stored in the database. Many tables in the WHMCS installation are modeled as classes available both internally to WHMCS and to third party code. These classes, based on the Eloquent 4.1 ORM library, model tables, columns, and relationships between tables in WHMCS' backend database. Use these classes to easily interact with WHMCS' backend data without the need for complex SQL statements.

A model-based class in WHMCS corresponds to a single table in the database and has properties that map to the columns in that table. For instance, the <tt>\WHMCS\User\Client</tt> class models data in the <tt>tblclients</tt> table. It includes the properties <tt>$id</tt>, <tt>$firstName</tt>, <tt>$lastName</tt>, and others that map to the <tt>id</tt>, <tt>firstname</tt>, <tt>lastname</tt>, and other columns in that table. Model-based classes also have properties that relate to other model-based classes. For example, a client can have more than one domain or contact on their account. The client's <tt>$domains</tt> and <tt>$contacts</tt> properties contain collections of <tt>\WHMCS\Domain\Domain</tt> and <tt>\WHMCS\User\Client\Contact</tt> instances, which in turn model data in the <tt>tbldomains</tt> and <tt>tblcontacts</tt> tables, and each have their own column and relational properties.

This page describes basic interactivity with model classes. Please see [http://laravel.com/docs/eloquent Laravel's Eloquent ORM manual] for a much more detailed reference.

=Creating Records=

Creating new records using model-based classes is as simple as creating a local object.

# Declare a new instance of the class of data to insert.
# Populate the object's properties.
# Call the <tt>save()</tt> method to insert the new record into the database.

Models with a primary key have that key automatically populated on save. In most model-based classes the <tt>$id</tt> property is the classes' primary key. As with all all backend interaction it's helpful to place the <tt>save()</tt> call in a <tt>try</tt>/<tt>catch</tt> block to intelligently handle any error situations.

<syntaxhighlight lang="php">
<?php

use WHMCS\User\Client;

$newClient = new Client;
$newClient->firstName = 'John';
$newClient->lastName = 'Doe';
$newClient->email = 'jdoe@example.org';

try {
$newClient->save();
echo "I just created John Doe's client record. His id number is {$newClient->id}.";
} catch (Exception $e) {
echo "Uh oh. I couldn't create John Doe's client record. {$e->getMessage()}";
}
</syntaxhighlight>

=Retrieving Records=

Use a model's static <tt>find()</tt> method to locate a record by its primary key. <tt>find()</tt> retrieves the record or returns <tt>null</tt> if the record doesn't exist in the database. Alternatively, use the static <tt>findOrFail()</tt> method to throw an exception instead of retuning a null value if the record isn't found.

<syntaxhighlight lang="php">
<?php

use WHMCS\User\Client;

$clientId = 1234;

// Look for John Doe by id. $johnDoe will be null if id 1234 doesn't exist.
$johnDoe = Client::find($clientId);

// Look for John Doe by id, but throw an exception if id 1234 doesn't exist.
try {
$johnDoe = Client::findOrFail($clientId);
} catch (Exception $e) {
echo "I couldn't find John Doe. {$e->getMessage()}";
}
</syntaxhighlight>

Querying for data is also possible with chains of <tt>where()</tt> method calls. Call it statically first with the names of the property and value to search for. End the chain with a <tt>get()</tt> method call to query the database and retrieve a collection of the results.

<syntaxhighlight lang="php">
<?php

use WHMCS\User\Client;

// Look for all clients with the name "John Doe".
$johnDoes = Client::where('firstName', 'John')->where('lastName', 'Doe')->get();

foreach ($johnDoes as $john) {
echo "I found a John Doe from {$john->city}, {$john->state} with the id number {$client->id}.";
}
</syntaxhighlight>

Once models are retrieved then their related properties to other models are also immediately available. Relational model properties in turn have other relational properties that can be chained together in multiple ways.

<syntaxhighlight lang="php">
<?php

use WHMCS\User\Client;

$clientId = 1234;
$johnDoe = Client::find($clientId);

echo 'John Doe has ' . $johnDoe->services->count() . ' service(s).';
echo 'John Doe also has ' . $johnDoe->contacts->count() . "contacts. The first one goes by " . $johnDoe->contacts->first()->firstName . '.';

foreach ($johnDoe->services as $service) {
echo 'Service ' . $service->domain . ' is based from the product ' . $service->product->name . '.';
}
</syntaxhighlight>

=Updating Records=

A model's <tt>save()</tt> method can also update existing records in addition to creating new records.

<syntaxhighlight lang="php">
<?php

use WHMCS\User\Client;

$clientId = 1234;

try {
$johnDoe = Client::findOrFail($clientId);

$johnDoe->address1 = '1234 Main Street';
$johnDoe->city = 'Anytown';
$johnDoe->state = 'TX';
$johnDoe->postcode = '12345';

$johnDoe->save();

echo "I've updated John Doe's address.";
} catch (Exception $e) {
echo "Uh oh. I couldn't update John Doe's address. {$e->getMessage()}";
}
</syntaxhighlight>

=Deleting Records=

Call a model object's <tt>delete()</tt> method to delete its associated table row. Deletions are permanent and cannot be undone.

<syntaxhighlight lang="php">
<?php

use WHMCS\User\Client;

$clientId = 1234;

try {
Client::findOrFail($clientId)->delete();
echo "So long, John!";
} catch (Exception $e) {
echo "Uh oh. I couldn't delete John Doe's client record. {$e->getMessage()}";
}
</syntaxhighlight>

It is also possible to delete an object's related properties.

<syntaxhighlight lang="php">
<?php

use WHMCS\User\Client;

$clientId = 1234;

try {
// Delete John Doe's first domain.
Client::findOrFail($clientId)->domains->first()->delete();
echo "Take that, domain!";
} catch (Exception $e) {
echo "Uh oh. I couldn't delete John Doe's first domain. {$e->getMessage()}";
}
</syntaxhighlight>

=Current Models=

Not every table in WHMCS has an associated model yet. These are the current model classes in WHMCS and their associated tables. This list is updated on new version releases. Please check here often for new functionality.

{| class="wikitable"
! Table
! Class
|-
| tblaccounts
| <tt>\WHMCS\Billing\Payment\Transaction</tt>
|-
| tbladmins
| <tt>\WHMCS\User\Admin</tt>
|-
| tbladminsecurityquestions
| <tt>\WHMCS\User\Client\SecurityQuestion</tt>
|-
| tblaffiliates
| <tt>\WHMCS\User\Client\Affiliate</tt>
|-
| tblannouncements
| <tt>\WHMCS\Announcement\Announcement</tt>
|-
| tblcancelrequests
| <tt>\WHMCS\Service\CancellationRequest</tt>
|-
| tblclients
| <tt>\WHMCS\User\Client</tt>
|-
| tblcontacts
| <tt>\WHMCS\User\Client\Contact</tt>
|-
| tbldomains
| <tt>\WHMCS\Domain\Domain</tt>
|-
| tbldomainsadditionalfields
| <tt>\WHMCS\Domain\AdditionalField</tt>
|-
| tbldownloadcats
| <tt>\WHMCS\Download\Category</tt>
|-
| tbldownloads
| <tt>\WHMCS\Download\Download</tt>
|-
| tblemailtemplates
| <tt>\WHMCS\Mail\Template</tt>
|-
| tblhosting
| <tt>\WHMCS\Service\Service</tt>
|-
| tblhostingaddons
| <tt>\WHMCS\Service\Addon</tt>
|-
| tblinvoices
| <tt>\WHMCS\Billing\Invoice</tt>
|-
| tblnetworkissues
| <tt>\WHMCS\Network\NetworkIssue</tt>
|-
| tblproductgroups
| <tt>\WHMCS\Product\Group</tt>
|-
| tblproducts
| <tt>\WHMCS\Product\Product</tt>
|-
| tblquoteitems
| <tt>\WHMCS\Billing\Quote\Item</tt>
|-
| tblquotes
| <tt>\WHMCS\Billing\Quote</tt>
|-
|}

=See Also=
* [[Interacting With The Database]]

Standard Order Form Templates

2016-03-28T13:59:03Z

Steven.Mueller: /* Standard Cart */ DOCS-6433: Clarify the Standard Cart Product Group Features capability

WHMCS includes a number of standard order form templates to choose from to provide the best ordering experience for your visitors. To select a template navigate to '''Setup > General Settings > Ordering tab'''. This page describes the various templates, for instructions customising them refer to [[Order Form Templates]].

=Templates=

==Standard Cart==

<div class="docs-alert-warning">
'''Supported Features'''

Headline: Yes<br />
Tagline: Yes<br />
Feature Highlights: Yes<br />
Featured Products: Yes<br />
Product Group Features: No<br />
Number of Products: For best results 3, supports unlimited.<br />
Compatible With: Six template/Bootstrap 3
</div>

The default shopping cart experience in Version 6.1 and later. Compatible with all types of products.

==Premium Comparison==
[[File:Premium-Comparison.png‎|thumb|Premium Comparison]]
<div class="docs-alert-warning">
'''Supported Features'''

Headline: Yes<br />
Tagline: Yes<br />
Feature Highlights: Yes<br />
Featured Products: Yes<br />
Product Group Features: Yes<br />
Number of Products: For best results 3, supports unlimited.<br />
Compatible With: Six template/Bootstrap 3
</div>

Perfect for comparing a number of products/services. You should utilise the product features functionality to define comparable features/values, and ensure you have the same format/order for all descriptions of products within the group for best results.

==Pure Comparison==
[[File:Pure-Comparison.png‎|thumb|Pure Comparison]]
<div class="docs-alert-warning">
'''Supported Features'''

Headline: Yes<br />
Tagline: Yes<br />
Feature Highlights: Yes<br />
Featured Products: Yes<br />
Product Group Features: Yes<br />
Number of Products: For best results 4, supports unlimited.<br />
Compatible With: Six template/Bootstrap 3
</div>

Perfect for comparing a number of products/services. You should utilise the product features functionality to define comparable features/values, and ensure you have the same format/order for all descriptions of products within the group for best results.

==Supreme Comparison==
[[File:SupremeComparisonOrderForm.png‎|thumb|Supreme Comparison]]
<div class="docs-alert-warning">
'''Supported Features'''
Headline: Yes<br />
Tagline: Yes<br />
Feature Highlights: Yes<br />
Featured Products: Yes<br />
Product Group Features: Yes<br />
Number of Products: For best results 6, supports unlimited.<br />
Compatible With: Six template/Bootstrap 3
</div>

Perfect for comparing a number of products/services. You should utilise the product features functionality to define comparable features/values, and ensure you have the same format/order for all descriptions of products within the group for best results.

==Universal Slider==
[[File:UniversalSliderOrderForm.png‎|thumb|Universal Slider]]
<div class="docs-alert-warning">
'''Supported Features'''
Headline: Yes<br />
Tagline: Yes<br />
Feature Highlights: Yes<br />
Featured Products: Yes<br />
Product Group Features: Yes<br />
Number of Products: For best results between 4 and 8, supports unlimited space permitting.<br />
Compatible With: Six template/Bootstrap 3
</div>

Allows you to showcase your products in a slider format that can work universally for any type of product. Includes support for comparison of product features with percentage bars as well as support for a free-form text description. For best results we recommend utilising the product feature functionality to define 4 or 8 comparable features/values and using the same product description format for all products within the group - this avoids page shifting on sliding between products.

==Cloud Slider==
[[File:Cloud-Slider.png‎|thumb|Cloud Slider]]
<div class="docs-alert-warning">
'''Supported Features'''

Headline: Yes<br />
Tagline: Yes<br />
Feature Highlights: Yes<br />
Featured Products: Yes<br />
Product Group Features: Yes<br />
Number of Products: For best results between 2 and 12, supports unlimited space permitting.<br />
Compatible With: Six template/Bootstrap 3
</div>

Perfect for comparing a number of products/services. You should utilise the product features functionality to define comparable features/values. For best results use 4 feature/value comparisons. and ensure you have the same format/order for all descriptions of products within the group for best results.

==Boxes==
[[File:Boxesthumb.gif‎|thumb|Boxes]]
<div class="docs-alert-warning">
'''Supported Features'''

Headline: No<br />
Tagline: No<br />
Feature Highlights: No<br />
Featured Products: No<br />
Product Group Features: No<br />
Number of Products: Unlimited<br />
Compatible With: Six template/Bootstrap 3
</div>

A flexible cart that is designed to work for most types of products.

==Modern==
[[File:Modernthumb.gif‎|thumb|Modern]]
<div class="docs-alert-warning">
'''Supported Features'''

Headline: No<br />
Tagline: No<br />
Feature Highlights: Yes<br />
Featured Products: No<br />
Product Group Features: No<br />
Number of Products: Unlimited<br />
Compatible With: Six template/Bootstrap 3
</div>

A flexible cart that is designed to work for all types of products.

=Using Feature Highlights=

Feature Highlights allow you to define features and their values for products in a way that WHMCS can interpret for comparison based display.

Feature Highlights are supported by most order form templates. See the above descriptions for exact details.

[[File:PremiumComparisonFeatureHighlights.png|right]]
==Usage==

Feature Highlights are specified as part of the product description. They must be entered in the following format, with one feature per line.

'''Feature: Value'''

For example, the description for a shared hosting product using Feature Highlights might look like this:

Disk Space: 1000MB
Bandwidth: 5GB
Email Accounts: 5
Subdomains: 3
Addon Domains: 1

The preview on the right shows how the above would be rendered in the Premium Comparison order form.

<div class="docs-alert-info">For best results we recommend that you use the same features and in the same order for all products within the same product group.</div>

==Disabling Feature Highlights==

There may be occasions when it's required to disable feature highlights, such as when wishing to use other markup in the product description. To do this, simply edit the /templates/orderforms/*your active template*/products.tpl template file and perform these two edits:

# Replace '''{$product.featuresdesc}''' with '''{$product.description}'''
# Remove/comment out:
<source lang="php">
{foreach from=$product.features key=feature item=value}

<span class="prodfeature"><span class="feature">{$feature}</span><br />{$value}</span>
{/foreach}
</source>

Save changes and upload the modified template file. Now product descriptions will be displayed as entered.

=Using Different Templates for Different Products=

It is possible to specify the template you want to use for a product in the URL you use to link to the order form. And therefore by doing that you can use multiple different templates concurrently and thus use the one that best suits each product or type of product you offer.

Details on how to do this can be found in the article: [[Linking_to_WHMCS#Order_Links|Linking to WHMCS - Order Links]]

=Discontinued Order Form Templates=

The following shopping carts are no longer shipped with releases and are provided for legacy users only.

==Cart==
[[File:Cartthumb.gif‎|thumb|Cart]]
<div class="docs-alert-warning">
'''Supported Features'''

Headline: No<br />
Tagline: No<br />
Feature Highlights: No<br />
Featured Products: No<br />
Product Group Features: No<br />
Number of Products: Unlimited<br />
Compatible With: Five template/Bootstrap 2
</div>

Replaced by the Standard Cart in 6.1. This cart is now deprecated and will no longer receive updates.

==Comparison==
[[File:Comparisonthumb.gif‎|thumb|Comparison]]
<div class="docs-alert-warning">
'''Supported Features'''

Headline: No<br />
Tagline: No<br />
Feature Highlights: Yes<br />
Featured Products: No<br />
Product Group Features: No<br />
Number of Products: For best results 4, supports unlimited.<br />
Compatible With: Five template/Bootstrap 2
</div>

Replaced by Premium Comparison/Supreme Comparison in 6.1 and 6.2. This cart is now deprecated and will no longer receive updates.

==Slider==
[[File:Sliderthumb.gif‎|thumb|Slider]]
<div class="docs-alert-warning">
'''Supported Features'''

Headline: No<br />
Tagline: No<br />
Feature Highlights: Yes<br />
Featured Products: No<br />
Product Group Features: No<br />
Number of Products: For best results between 2 and 12, supports unlimited space permitting.<br />
Compatible With: Five template/Bootstrap 2
</div>

Replaced by the Universal Slider in 6.2. This cart is now deprecated and will no longer receive updates.

==Verticalsteps==
[[File:Verticalstepsthumb.gif‎|thumb|Vertical Steps]]
<div class="docs-alert-warning">
'''Supported Features'''

Headline: No<br />
Tagline: No<br />
Feature Highlights: No<br />
Featured Products: No<br />
Product Group Features: No<br />
Number of Products: Unlimited<br />
Compatible With: Five template/Bootstrap 2
</div>

Replaced by the Standard Cart in 6.1. This cart is now deprecated and will no longer receive updates.

File:Client trans.png

2016-03-28T13:41:58Z

Steven.Mueller: Steven.Mueller uploaded a new version of "File:Client trans.png"

Clients:Transactions Tab

2016-03-28T13:40:33Z

Steven.Mueller: DOCS-6423: Clarify Documentation on Adding Transaction

<br/><br/>{{Client Management}}

[[File:client_trans.png|thumb|Client Transactions Tab]]
The Transactions tab is accessed via the '''Clients > View/Search Clients''' page, select a client, then click the tab marked "Transactions". It contains summary statistics of the transactions made by this client along with a paginated list of all their transactions, icons to edit or delete an existing quote and a link to record a new transaction.

The number of entries per page is determined under Setup > General Settings. Click the table headings to change the sorting order.

====Add New Transaction====
Clicking the '''Add New Transaction''' link will record a new transaction against this client's account.
{|class="table table-striped"
|-
| '''Date'''
| Enter the date of the transaction
|-
| '''Description'''
| Enter a description for this transaction (required if no Invoice ID specified)
|-
| '''Transaction ID'''
| Enter a transaction ID if relevant to the transaction
|-
| '''Invoice ID'''
| Enter an invoice ID to apply the transaction against (required if no description entered - single Invoice ID value only)
|-
| '''Payment Method'''
| Select the payment method this transaction was received by
|-
| '''Amount In'''
| Enter the amount that was received (no currency symbols)
|-
| '''Fees'''
| Enter the amount that the payment gateway charged for this transaction
|-
| '''Amount Out'''
| Enter the amount that was sent to the customer (for refund transactions)
|-
| '''Credit'''
| Check this box to apply the transaction against the client's credit balance (requires a description entered)
|}

<div class="docs-alert-info">
<strong>Did You Know?</strong>
<p>WHMCS provides an easy interface to add transactions for clients, including a way to apply a transaction across many invoices? To find out more check out the [[Transactions#Adding_a_Manual_Transaction|Adding a Manual Transaction]] section of our [[Transactions#|Transactions]] page.
</p>
</div>

Language Files

2016-03-28T13:26:37Z

Steven.Mueller: /* Default Languages */ Correct count of client area and admin area languages in use

WHMCS supports numerous languages, in both in the client and admin areas. To enable this, all text used throughout the system is stored within language files.

Language files are stored in the '''/lang/''' sub-folders of both the client and admin directories.

__TOC__
==Default Languages==

WHMCS includes 21 client area translations by default. These are:

'''Arabic, Catalan, Chinese, Croatian, Czech, Danish, Dutch, English, Farsi, French, German, Hungarian, Italian, Norwegian, Brazilian & Native Portuguese, Russian, Spanish, Swedish, Turkish & Ukranian'''

And for the admin area there are 13 translations included:

'''Arabic, Czech, Dutch, English, Farsi, French, Hebrew, Hungarian, Italian, Portuguese, Russian, Spanish & Turkish'''

We rely on the dedication and generosity of our users for contributing translations, as we find real life translations are a much higher quality compared with using automated translation systems as some softwares do. So if you have any suggestions for improvements, or a new language file you are willing to contribute, please get in touch.

==Adding a New Language==

If a language you operate in is not available as standard, then you can create your own translation. Here's how:

#Begin by opening an existing language file
#Save this file with a new name - the name you want to be shown in the language selection dropdown menu in WHMCS - the name should only consist of a-z0-9 characters and end with the extension ".php"
#Once the file has been created, you can then begin going through and translating the lines within it
#An example line is as follows - you should only change the part in bold:

<source lang="php">
$_LANG['accountinfo'] = "Account Information";
</source>

''Be careful not to delete any of the quotation marks (") around the text strings or the semi-colons on the ends of each line (;). Also should you want to use a quote character (") within your translated text, you must escape it - for example: \" The language files are written in PHP syntax so valid PHP code must be maintained.''

===Encoding===
By default the language files in WHMCS use the UTF-8 encoding without a Byter Order Marker character at the start. When modifying these files it is important to maintain the same encoding.

If you have chosen to change the system charset setting to something other than UTF-8 (eg. iso-8859-1) then the language files will need to be re-saved with ANSI encoding without a Byte Order Marker. Most text editors have this option (including Notepad).

==Overriding Language Strings==

{{:Language_Overrides}}

Language Files

2016-03-21T20:25:20Z

Steven.Mueller: DOCS-6297 - Update Language Document to Include Full List of Languages Support in Admin Area in 6.0

WHMCS supports numerous languages, in both in the client and admin areas. To enable this, all text used throughout the system is stored within language files.

Language files are stored in the '''/lang/''' sub-folders of both the client and admin directories.

__TOC__
==Default Languages==

WHMCS includes 20 client area translations by default. These are:

'''Arabic, Catalan, Croatian, Czech, Danish, Dutch, English, Farsi, French, German, Hungarian, Italian, Norwegian, Brazilian & Native Portuguese, Russian, Spanish, Swedish, Turkish & Ukranian'''

And for the admin area there are 6 translations included:

'''Arabic, Czech, Dutch, English, Farsi, French, Hebrew, Hungarian, Italian, Portuguese, Russian, Spanish & Turkish'''

We rely on the dedication and generosity of our users for contributing translations, as we find real life translations are a much higher quality compared with using automated translation systems as some softwares do. So if you have any suggestions for improvements, or a new language file you are willing to contribute, please get in touch.

==Adding a New Language==

If a language you operate in is not available as standard, then you can create your own translation. Here's how:

#Begin by opening an existing language file
#Save this file with a new name - the name you want to be shown in the language selection dropdown menu in WHMCS - the name should only consist of a-z0-9 characters and end with the extension ".php"
#Once the file has been created, you can then begin going through and translating the lines within it
#An example line is as follows - you should only change the part in bold:

<source lang="php">
$_LANG['accountinfo'] = "Account Information";
</source>

''Be careful not to delete any of the quotation marks (") around the text strings or the semi-colons on the ends of each line (;). Also should you want to use a quote character (") within your translated text, you must escape it - for example: \" The language files are written in PHP syntax so valid PHP code must be maintained.''

===Encoding===
By default the language files in WHMCS use the UTF-8 encoding without a Byter Order Marker character at the start. When modifying these files it is important to maintain the same encoding.

If you have chosen to change the system charset setting to something other than UTF-8 (eg. iso-8859-1) then the language files will need to be re-saved with ANSI encoding without a Byte Order Marker. Most text editors have this option (including Notepad).

==Overriding Language Strings==

{{:Language_Overrides}}