WHMCS Documentation - User contributions [en]

Installing WHMCS

2017-04-24T13:09:33Z

NickHudson: /* Creating a Database */

==Downloading WHMCS==

#Visit http://download.whmcs.com/
#Click the Download button under the Full Release heading - this will be the latest release version

<div class="docs-alert-info">
<span class="title">Reseller Customers</span><br />
If your license key was obtained via a reseller and you therefore do not have a login for our members area, your reseller will be able to provide the latest WHMCS files to you''
</div>

==Installing Ioncube==

WHMCS is encrypted using Ioncube to protect the source code. These days most servers/webhosts have Ioncube support compiled into the PHP build by default so you don't normally need to do anything extra for it. However if you find you do need to install Ioncube on your server, then you can find out how to do this in our [[Ioncube Installation Tutorial]]

==Creating a Database==
WHMCS uses a MySQL database to store all settings and data. You will be asked to create one during the installation process, so best to create one beforehand. Technical information is detailed on the [[Database Setup]] page.

* [https://documentation.cpanel.net/display/1152Docs/MySQL+Database+Wizard Creating databases in cPanel]
* [https://docs.plesk.com/en-US/17.0/customer-guide/advanced-website-databases.69535/ Created databases in Plesk]

==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

==Installing WHMCS==

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

Installing WHMCS is very simple. The following steps will guide you through the process:

#Unzip the contents of the zip file to a folder on your computer
#Rename the file configuration.php.new to configuration.php
#Upload the entire whmcs folder to your website - if you experience problems, try uploading in binary mode
#Next you can rename the folder to whatever you like (billing, clients, etc...)
#Now visit the installation script at http://www.yourdomain.com/whmcs/install/install.php to run the installer process - if you get an Ioncube related error message, see the installation Ioncube steps above
#Follow the instructions on screen to install which will involve setting file permissions as listed below, entering your license key and setting up your primary admin account
<div class="docs-alert-warning">
<span class="title">Acceptable Password Characters</span><br />
The following characters should not be used in an administrator password & " ' < > (ampersand, double quotes, single quotes, less than or greater than). Any other symbols such as # ! £ $ % ^ * ( ) . , / etc… are perfectly acceptable.
</div>

When complete, delete the install folder from your web server and CHMOD the configuration.php file back to 644.

<div class="docs-alert-warning">
<span class="title">Required file & folders permissions</span><br /><br />
/configuration.php CHMOD 400 Readable<br />
/attachments CHMOD 777 Writeable<br />
/downloads CHMOD 777 Writeable<br />
/templates_c CHMOD 777 Writeable<br /><br />
The above applies unless your php is suPHP or PHPSuExec. If using DSO as your php handler, you must use 644 permissions.
</div>

==Post Installation Suggested Steps==

After installation is completed, we recommend that you go through and configure your new WHMCS system in the following order:

#Perform the recommended [[Further Security Steps]]
#Login to the Admin Area and configure your General Settings (Setup > [[Configuration|General Settings]])
#Setup your Payment Gateways (Setup > [[Payment Gateways]])
#Setup your Products & Services (Setup > [[Products and Services]])
#Configure your Domain Pricing (Setup > [[Domains_Configuration|Domain Pricing]])
#Setup your Support Ticket Departments (Setup > [[Support_Center|Support Departments]])
#Setup email piping so you can manage tickets using the WHMCS Support Desk - for full instructions on this please see the [[Email Piping]] article
#Ensure the WHMCS Cron Job is setup and configure automated tasks (Setup > [[Automation Settings]])
#Place some test orders on your website to check everything works as expected

[[File:Videotutorial.png‎|center|link=https://www.whmcs.com/get-support/video-tutorials/|Watch Video Tutorial]]

For further guidance, you can watch video tutorials we have prepared for the above tasks @ [https://www.whmcs.com/get-support/video-tutorials/ www.whmcs.com/get-support/video-tutorials/]

Updating

2017-04-18T15:00:51Z

NickHudson: /* We're here to help */

We always recommend staying up-to-date with WHMCS in order to benefit from the latest development and improvements, and you can do that either by [https://www.whmcs.com/services/upgrade-service/ having us perform the update for you] or by updating as per the steps below.

==Automatic Updating==

If you are running WHMCS 7.0 or later, you can use the built-in Automatic Update utility.

Simply navigate to '''Utilities > Update WHMCS''' to begin the process.

<div class="docs-alert-info"><i class="fa fa-info-circle fa-fw"></i>  If the update was released recently, you may need to click the Check for Updates button before the update will show as available.</div>

For more information about the Automatic Updater and troubleshooting please refer to http://docs.whmcs.com/Automatic_Updater

==Performing a Manual update==

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

To update WHMCS manually, follow the steps below. Some updates may require steps in addition to the standard update steps provided below. Should these be required you will find them in the [[Release Notes]]. Please always refer to the release notes for a version before attempting any update.

A '''Full Release''' distribution contains all the files of a WHMCS product installation. It can be used to perform a new install or update an existing installation (regardless of previous version).

'''Patch Sets''' contain only the files that have changed between the immediate, previous version and the latest version, (ie. a patch set for version 1.1.2 is valid for a 1.1.1 installation and nothing else). We provide these to make updating both quicker and easier for those of our customers who stay current and up-to-date with the latest WHMCS releases. By including only the changed files, patch sets have less files to upload which makes the update process quicker and simpler for you to perform.

More information on our release types and distribution types can be found on our [[Releases]] page.

==Update Steps==

===For a Full Release Version===

A full release version is denoted by the presence of _full within the zip folder filename and "Distro Type: Full Version" within the included README.txt file. If the zip file you have instead contains _patch, please refer to the below [[Updating#For_a_Patch_Set|Patch Set update Steps]] instead.

'''Make a Full Backup - We cannot stress enough how important it is to *always* take a full backup before attempting any kind of update. Both for WHMCS and any other software you use. A full backup should be taken of both the WHMCS files and the database.'''

#Begin by making sure your server meets the [[System_Requirements|system requirements]],
#Obtain the latest full release download of WHMCS either from http://download.whmcs.com/ or from your license provider (if using a reseller)
#Unzip the contents of the WHMCS zip file download to a folder on your computer<div class="docs-alert-danger"><span class="title">Custom Admin Directory?</span><br />If you have renamed your "admin" directory, be sure to rename the /whmcs/admin directory in the new files to match. </div><div class="docs-alert-warning"><span class="title">Custom Cron Directory?</span><br />Similarly, if you have customised the location of the /crons/ directory, be sure to upload that to the custom location.</div><div class="docs-alert-success"><span class="title">Custom File Permissions?</span><br />If you have customised the permissions on any of the files eg. /crons/pipe.php. These changes will need to be re-applied once the update is complete.</div>
#Upload the new files to your existing installation folder replacing any existing folders & files
#Visit your WHMCS installation and you should then be automatically redirected to the update process. If you see a message saying WHMCS is not installed, this indicates you have overwritten the configuration.php file for your installation. Stop and restore that file from your backup before continuing.
#Agree to the WHMCS End User License Agreement and follow the steps on screen to update your database.
#When prompted, delete the install folder from your server.
#Your update is now complete.

We recommend now that you check the release notes for the version you just installed [[Release_Notes|here]]. And if you have custom template files you will also need to review and make any necessary changes to your custom templates using the information provided in the Template Changes section of the [[Release_Notes|Release Notes]].

===For a Patch Set===

A patch set version is denoted by the presence of _patch within the zip folder filename and "Distro Type: Patch Set" within the included README.txt file.

'''IMPORTANT:''' Before you begin please ensure you are running the version required by the patch. Patch Sets contain only the files that have changed between the previous release and the Patch Set Version. Therefore they should only be applied if you are running the immediately previous version.

The previous release version that these patch sets are designed for is clearly indicated as the first and smaller number in release notices providing the patch set download link.

#Download the patch set from http://download.whmcs.com/
#Unzip the patch set files<div class="docs-alert-danger"><span class="title">Custom Admin Directory?</span><br />For patches that have updates for the “admin” directory: If you have renamed your "admin" directory, then make sure you rename the /whmcs/admin directory to match</div>
#Upload the files from the /whmcs/ directory to the root directory of your WHMCS installation
#Visit the admin area of your WHMCS installation to trigger the version number bump and complete the process

No install or update process is required.

==Confirming a Successful Update==

To confirm an update has been successfully applied, login to your WHMCS admin area and check to make sure that the Version Number displayed either on the admin homepage (in the sidebar of all default templates) or in '''Help > System Health Status''' is the version you attempted to apply. If it has not incremented, then one or more of the files has not uploaded successfully. You should double check file permissions and attempt the steps again from the beginning.

==Helpful Hints==

'''Database Privileges'''

Updating requires that the database user have access to the following privileges:

*ALTER
*CREATE
*DROP
*INDEX

Additionally, you will want to ensure that the database user have access to all privileges listed on the [[Further_Security_Steps#Restrict_Database_Privileges|Further Security Steps]] page.

'''Customisations'''

If you have customised templates, please ensure you always follow the recommended method for [[Client_Area_Template_Files#Creating_a_Custom_Template|creating a custom template folder]] to ensure your changes aren't overwritten during updates. Similarly for language file customisations please ensure you use the [[Language Overrides]] feature vs editing the language files directly.

'''Bad Formatting'''

If when you first login you see a display where formatting is mixed or unclear, this can indicate your browser cache has not updated. Try clearing your browser cache or performing a hard refresh (typically Ctrl + F5) and delete the contents of the template cache directory (''templates_c'' by default) to ensure you see the new templates and styling.

'''What to do if you get a Down for Maintenance or update in Progress message after uploading a patch set'''

If after uploading the files from a Patch Set you see a "Down for Maintenance" or "update in progress..." warning message then this indicates that the patch set files you attempted to apply are not compatible with the version of WHMCS you were previously running. To complete the update you will need to download the latest [[Updating#For_a_Full_Release_Version|Full Release]] version and update using the regular update process as described above.

==We're here to help==

We offer a professional update service where our staff will update your WHMCS installation for you. Please refer to https://www.whmcs.com/services/upgrade-service/ for more information and to order.

And of course our support team is always available to answer any questions or concerns you might have when performing the update process yourself. Simply open a ticket @ http://www.whmcs.com/get-support/ and a member of our team will get back to you..

Client Area Template Files

2016-12-19T12:28:47Z

NickHudson: /* Intro */

=Intro=
WHMCS always endeavours to make the system as customisable as possible so that users can always tailor it to their exact needs. With that in mind, all pages of the WHMCS client area use templates. This allows a user to add/remove and change the look and feel of everything. In WHMCS, use of the powerful [[Template Syntax|Smarty template system]] allows you to:

*Customise the layout and content of the client area fully.
*Make use of file includes for common elements shared between pages.
*Make use of many other powerful features Smarty has to offer.

Most pages use three templates that combine to make up the output. These combine in this order:

#'''Header Template (header.tpl)'''
#'''Main Content Template (homepage.tpl, clientareahome.tpl, etc...)'''
#'''Footer Template (footer.tpl)'''

The header and footer are common to every page displayed as a wrapper around the content. Within the template folders you will see many other template files. These take the place of 'The Page Template' above. These templates define the output on each page. The templates are also named so that you can identify which relates to which page. For example, the template that defines the WHMCS homepage at (yoursite.com/whmcs/) is homepage.tpl. The main client area page is clientareahome.tpl and so on.

'''Before starting''', please refer to the '''[[Template Syntax]]''' section of the docs. This provides information on how to work with the templates in WHMCS.

==Creating a Custom Template==

When customising any WHMCS templates, the first step is to create another template folder. The default templates should never be edited directly. To do this, perform the following steps:

#Duplicate one of the standard folders in the templates folder (six, five) and rename it to a custom name.
#The directory name should be all one word and consist of just lowercase letters and numbers.
#Now make your customisations and changes as desired. See section below for more details on this.
#Once complete, upload the new templates folder to the templates directory of WHMCS.
#Preview the new template by specifying it using an URL "on the fly". For example, www.yourdomain.com/whmcs/?systpl=xxxxx where xxxxx is the name of the new template. See [[Linking to WHMCS]] for more information.
#Once happy with it, set it live by going to '''Setup > General Settings'''. On the first tab, choose the new custom template name from the Template's dropdown menu.

The template selected here will be referred to throughout the documentation as the active template folder. Likewise, the order form template selected in Setup > General Settings > Ordering.

==Customising to Match Your Website==

What most people want to do with customisation is integrate WHMCS to match the rest of their website. This can be a daunting task but it is fairly straightforward. Following on from the above, begin by copying the HTML which controls the top of your website design. Paste this into the header.tpl file of your custom template folder. Make sure to preserve the <head> section of code in the default WHMCS template. This contains the necessary CSS, Javascript Code & File Includes for WHMCS to function. Then copy and paste the footer code from your website design into footer.tpl.

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

===Customising how payment gateways are displayed===
There may be occasion where it's desirable to customise the way payment gateways display. For example, you may wish to add formatting, display images such as card logos, or any other code of your own.

Due to security considerations, it isn't possible to enter HTML into the display name or payment instruction fields. Instead, you can customise the relevant template to display your desired code.

For example, to display credit card logos when the PayPal is the payment method on the printable invoice, use the following code. This will be in /templates/*your active template*/'''viewinvoice.tpl''':

<source lang="php">
{if $paymentmodule eq 'paypal'}
<img src="/images/creditcardlogos.png">
{/if}
</source>

The image tag could be replaced with any code you wanted to display there. Replace 'paypal' with the name of your payment module. The exact value can be obtained from the tblpaymentgateways table.

==Customising the Six theme==

Six is the name of the default client area template that ships with WHMCS 6.0 and later. With this template we have introduced a number of new resources that you can use to further customise your WHMCS installation. Two of these new features are briefly addressed below and detailed information on how to customise the Six theme can be found in the [[Customising the Six Theme]] documentation.

===Navigation and Sidebar Customisation===

In the Six theme the look and feel of the navigation bar and sidebar elements can customised via the header.tpl and sidebar.tpl (located in /includes/) template files.

To make changes to the layout of the menus (i.e. adding, removing, and modifying items) please refer to the [[Editing Client Area Menus|Editing Client Area Menus]] documentation.

===Using GitHub===

The Six theme is made available via GitHub and provides version-by-version changes of the “Six” template as published in WHMCS. The WHMCS "Six" template repository can be found at [[https://github.com/WHMCS/templates-six]].

Client Area Template Files

2016-12-19T12:28:27Z

NickHudson:

=Intro=
WHMCS2 always endeavours to make the system as customisable as possible so that users can always tailor it to their exact needs. With that in mind, all pages of the WHMCS client area use templates. This allows a user to add/remove and change the look and feel of everything. In WHMCS, use of the powerful [[Template Syntax|Smarty template system]] allows you to:

*Customise the layout and content of the client area fully.
*Make use of file includes for common elements shared between pages.
*Make use of many other powerful features Smarty has to offer.

Most pages use three templates that combine to make up the output. These combine in this order:

#'''Header Template (header.tpl)'''
#'''Main Content Template (homepage.tpl, clientareahome.tpl, etc...)'''
#'''Footer Template (footer.tpl)'''

The header and footer are common to every page displayed as a wrapper around the content. Within the template folders you will see many other template files. These take the place of 'The Page Template' above. These templates define the output on each page. The templates are also named so that you can identify which relates to which page. For example, the template that defines the WHMCS homepage at (yoursite.com/whmcs/) is homepage.tpl. The main client area page is clientareahome.tpl and so on.

'''Before starting''', please refer to the '''[[Template Syntax]]''' section of the docs. This provides information on how to work with the templates in WHMCS.

==Creating a Custom Template==

When customising any WHMCS templates, the first step is to create another template folder. The default templates should never be edited directly. To do this, perform the following steps:

#Duplicate one of the standard folders in the templates folder (six, five) and rename it to a custom name.
#The directory name should be all one word and consist of just lowercase letters and numbers.
#Now make your customisations and changes as desired. See section below for more details on this.
#Once complete, upload the new templates folder to the templates directory of WHMCS.
#Preview the new template by specifying it using an URL "on the fly". For example, www.yourdomain.com/whmcs/?systpl=xxxxx where xxxxx is the name of the new template. See [[Linking to WHMCS]] for more information.
#Once happy with it, set it live by going to '''Setup > General Settings'''. On the first tab, choose the new custom template name from the Template's dropdown menu.

The template selected here will be referred to throughout the documentation as the active template folder. Likewise, the order form template selected in Setup > General Settings > Ordering.

==Customising to Match Your Website==

What most people want to do with customisation is integrate WHMCS to match the rest of their website. This can be a daunting task but it is fairly straightforward. Following on from the above, begin by copying the HTML which controls the top of your website design. Paste this into the header.tpl file of your custom template folder. Make sure to preserve the <head> section of code in the default WHMCS template. This contains the necessary CSS, Javascript Code & File Includes for WHMCS to function. Then copy and paste the footer code from your website design into footer.tpl.

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

===Customising how payment gateways are displayed===
There may be occasion where it's desirable to customise the way payment gateways display. For example, you may wish to add formatting, display images such as card logos, or any other code of your own.

Due to security considerations, it isn't possible to enter HTML into the display name or payment instruction fields. Instead, you can customise the relevant template to display your desired code.

For example, to display credit card logos when the PayPal is the payment method on the printable invoice, use the following code. This will be in /templates/*your active template*/'''viewinvoice.tpl''':

<source lang="php">
{if $paymentmodule eq 'paypal'}
<img src="/images/creditcardlogos.png">
{/if}
</source>

The image tag could be replaced with any code you wanted to display there. Replace 'paypal' with the name of your payment module. The exact value can be obtained from the tblpaymentgateways table.

==Customising the Six theme==

Six is the name of the default client area template that ships with WHMCS 6.0 and later. With this template we have introduced a number of new resources that you can use to further customise your WHMCS installation. Two of these new features are briefly addressed below and detailed information on how to customise the Six theme can be found in the [[Customising the Six Theme]] documentation.

===Navigation and Sidebar Customisation===

In the Six theme the look and feel of the navigation bar and sidebar elements can customised via the header.tpl and sidebar.tpl (located in /includes/) template files.

To make changes to the layout of the menus (i.e. adding, removing, and modifying items) please refer to the [[Editing Client Area Menus|Editing Client Area Menus]] documentation.

===Using GitHub===

The Six theme is made available via GitHub and provides version-by-version changes of the “Six” template as published in WHMCS. The WHMCS "Six" template repository can be found at [[https://github.com/WHMCS/templates-six]].