Installing and Configuring X-Cart > 

Configuration Files

The majority of tasks related to configuring your store and adjusting the store settings can be done via your store’s Admin area. However, some low-level 'static' settings (i.e. those that define the system behavior of X-Cart and that you aren't going to change often) are stored in X-Cart configuration files, and in some cases you might want to edit the configuration files to adjust these settings.

At present X-Cart has two configuration files:

• /config.php

• /top.inc.php

Warning: We strongly recommend you refrain from changing the configuration files, where possible. If, however, you decide to edit config.php or top.inc.php, be sure to make a backup copy of the file before you change anything.

config.php configuration file

X-Cart’s main configuration file is config.php. It is a plain text file that resides in the root directory and provides global definitions. Following is a list of the most important settings contained in the file config.php of which you should know.

SQL database details

$sql_host =’%SQL_HOST%’;

$sql_user =’%SQL_USER%’;

$sql_db =’%SQL_DB%’;

$sql_password =’%SQL_PASSWORD%’;

This section of config.php sets up a connection between X-Cart shopping cart software and your MySQL database. If you install X-Cart via the Web, X-Cart Installation Wizard asks you to provide your MySQL server information and automatically enters it into this section. However, if you install X-Cart manually, or if, after X-Cart has been installed, your MySQL server information changes, you are supposed to provide database access information by assigning values to the variables of this section manually.

The variables are supposed to have the following values:

X-Cart HTTP & HTTPS host and web directory

$xcart_http_host =”$HTTP_HOST”;

$xcart_https_host =”$HTTP_HOST”;

$xcart_web_dir =”/xcart”;

This section defines the location of your X-Cart installation. If you install X-Cart via the Web, X-Cart Installation Wizard asks you to specify your web server details and automatically enters them into this section. However, if you install X-Cart manually, you are supposed to provide this information manually.

The variables are supposed to have the following values:

Important: The variables $xcart_http_host and $xcart_https_host must contain host names only (no ‘http://’ or ‘https://’ prefixex, no trailing slashes).

Tip: If you are not sure what the host name of your secure server is, contact your hosting provider. In most cases the names of your secure and non-secure servers will be the same.

Important: You are supposed to provide the name of your X-Cart installation directory as seen from the Web, not from the file system. The general rule is to put a slash before the name of the directory and no slash at the end (for example, /xcart). An exception to this rule is when you install X-Cart in the site root, in which case you need to leave the variable empty.

Example 1:

Setting the web server details as follows:

$xcart_http_host ="www.yourhost.com";

$xcart_https_host ="www.securedirectories.com/yourhost.com";

$xcart_web_dir ="/xcart";

will result in the following URLs:

http://www.yourhost.com/xcart

https://www.securedirectories.com/yourhost.com/xcart

Example 2:

Setting the web server details as follows:

$xcart_http_host ="www.yourhost.com";

$xcart_https_host ="www.yourhost.com";

$xcart_web_dir ="";

will result in the following URLs:

http://www.yourhost.com/

https://www.yourhost.com/

Storing Customers’ Credit Card Info

$store_cc = false;

The variable $store_cc defines whether you want the credit card info provided by your customers at checkout to be stored in the database or not. The credit card info that can be stored includes:

- Cardholder’s name;

- Card type;

- Card number;

- Valid from (for certain card types);

- Exp. date;

- Issue No (for certain card types).

Admissible values for the $store_cc variable are ‘true’ and ‘false’. By default, the value of this variable is set to ‘false’, which means that your customers’ credit card info is not stored. Precisely speaking, this means that, when a customer submits his payment details at checkout, his credit card data is not entered into the order details and not saved to his user profile. If the payment method being used presupposes credit card processing via a payment gateway, the credit card data entered by your customer goes directly to the payment gateway, leaving no trace in your database tables. This approach spares you the necessity of having to address security issues associated with storing credit card data and is common practice for online stores accepting credit card payments via payment gateways.

Important: If you use any payment method involving manual processing of credit cards, setting $store_cc to ‘false’ will prevent you from getting credit card data of the customers who use that method. To be able to perform manual credit card processing, set the value of $store_cc to ‘true’ or think of an alternative way of getting credit card data from customers. Also, mind that X-Cart ‘Subscription’ module needs your customers’ credit card info to be able to automatically charge the credit cards used for paying for subscription products. Accordingly, if you are going to use ‘Subscription’ module, set the value of $store_cc to ‘true’.

By setting the $store_cc variable value to ‘true’ you agree to allow X-Cart to store your customers’ credit card info in order details and user profiles.

Warning: Storing credit card info is not recommended as being associated with the risk of making your customers’ credit card accounts vulnerable to those who might wish to use them illegally. If you decide to accept the responsibility of storing credit card info, make sure the database that will be used for this purpose is properly secured to protect sensitive cardholder data. Failure to provide adequate security may result in data theft and potentially involves legal liability.

Storing CVV2 codes

$store_cvv2 = false;

The variable $store_cvv2 defines whether you want the CVV2 codes of your customers’ credit cards to be stored in the database or not.

Admissible values for the $store_cvv2 variable are ‘true’ and ‘false’. By default, the value of this variable is set to ‘false’, which means that your customers’ CVV2 codes are not stored. Precisely speaking, this means that, when a customer submits his payment details at checkout, the CVV2 code of his credit card is not entered into the order details and not saved to his user profile. If the payment method being used presupposes credit card processing via a payment gateway, the CVV2 code entered by your customer goes directly to the payment gateway, leaving no trace in your database tables. This approach spares you the necessity of having to address security issues associated with storing CVV2 codes with the rest of credit card data.

Important: If you use any payment method involving manual processing of credit cards, setting $store_cvv2 to ‘false’ will prevent you from getting the CVV2 codes of the customers who use that method. To be able to perform manual credit card processing, set the value of $store_cvv2 to ‘true’ or think of an alternative way of getting CVV2 codes from customers. Also, mind that X-Cart ‘Subscription’ module needs your customers’ CVV2 codes to be able to automatically charge the credit cards used for paying for subscription products. Accordingly, if you are going to use ‘Subscription’ module, set the value of $store_cvv2 to ‘true’.

By setting the $store_cvv2 variable value to ‘true’ you agree to allow X-Cart to save and store CVV2 codes in the order details and in the user profiles of the customers who provide them.

Warning: Storing CVV2 codes (especially, with the rest of credit card data) is not recommended as being associated with the risk of making your customers’ credit card accounts vulnerable to those who might wish to use them illegally. If you decide to accept the responsibility of storing CVV2 codes, make sure the database that will be used for this purpose is properly secured. Failure to provide adequate security may result in data theft and potentially involves legal liability.

Storing Customers’ Checking Account Details

$store_ch = false;

The variable $store_ch defines whether you want your customers’ checking account details to be stored in the database or not. The checking account details that can be stored include:

- Bank account number;

- Bank routing number;

- Fraction number.

Admissible values for the $store_ch variable are ‘true’ and ‘false’. By default, the value of this variable is set to ‘false’, which means that your customers’ checking account details are not stored. Precisely speaking, this means that, when a customer submits his payment details at checkout, his checking account data is not entered into the order details. If the payment method being used presupposes check processing via a payment gateway, the checking account data entered by your customer goes directly to the payment gateway, leaving no trace in your database tables. This approach spares you the necessity of having to address security issues associated with storing checking account data in the database.

Important: If you use any payment method involving manual processing of checks, setting $store_ch to ‘false’ will prevent you from getting the checking account details of the customers who use that method. To be able to perform manual check processing, set the value of $store_ch to ‘true’ or think of an alternative way of getting checking account details from customers.

By setting the $store_ch variable value to ‘true’ you agree to allow X-Cart to save and store your customers’ checking account details in the order details.

Warning: Storing checking account details is not recommended as being associated with the risk of making your customers’ checking accounts vulnerable to those who might wish to use them illegally. If you decide to accept the responsibility of storing your customers’ checking account details, make sure the database that will be used for this purpose is properly secured. Failure to provide adequate security may result in data theft and potentially involves legal liability.

Default images

$default_image = "default_image.gif";

The variable $default_image defines which image file should be used as the default “No image available” picture (a picture that will appear in the place of any missing image in your X-Cart-based store if no other “No image available”-type picture is defined for that case). By default, the value of this variable is set to “default_image.gif”. You can find the file default_image.gif in X-Cart root directory.

default_image.gif

Note: You can upload your own default images to be used in place of missing X-Cart images of different types (product thumbnails, product images, category icons, detailed images, variant images, manufacturer logos, product class images) via the section ‘Images Location’.

$shop_closed_file = "shop_closed.html";

The variable $shop_closed_file defines which HTML page should be displayed to anyone trying to access the Customer zone of your store when the store is closed for maintenance. By default, the value of this variable is set to "shop_closed.html". You can find the file shop_closed.html in X-Cart root directory.

shop_closed.html (fragment).

Single Store mode (X-Cart PRO only)

$single_mode = true;

The variable $single_mode allows you to enable/disable Single Store mode if your store is based on X-Cart PRO. Single Store mode is an operation mode in which your store represents a unified environment shared by multiple providers in such a way that any provider can edit the products of the other providers, and shipping rates, discounts, taxes, discount coupons, etc are the same for all the providers.

Admissible values for the $single_mode variable are ‘true’ and ‘false’. Setting the variable to ‘true’ enables Single Store mode. Setting the variable to ‘false’ allows your store to function in normal mode so that each of your providers will be able to control his own products only and to have shipping rates, discounts, taxes, etc different from those of the other providers.

Important: If your store is based on X-Cart GOLD, the value of $single_mode must be set to ‘true’ at all times. Setting the variable to ‘false’ will not turn your GOLD shop into PRO.

Please be aware that the value of the $single_mode variable should be changed before any products, destination zones, shipping and tax rates are configured in the store. If you try to change the value of this variable after some providers have adjusted their store settings, these settings are highly likely to be corrupted.

FedEx Rates directory

$fedex_default_rates_dir = $xcart_dir.”/shipping/FedEx/”;

The variable $fedex_default_rates_dir defines the location of the directory where files for the calculation of FedEx shipping rates are stored. By default, the value of this variable is set to $xcart_dir.”/shipping/FedEx/”, where $xcart_dir is a variable representing the root directory of your X-Cart.

Log directory

$log_dir = ”/log”;

The variable $log_dir defines the location of the directory where X-Cart log files are stored. By default, the value of this variable is set to ”/log”, a directory within the root directory of your X-Cart.

Cache directory

$data_cache_dir = ”/cache”;

The variable $data_cache_dir defines the location of the directory where X-Cart cache files are stored. By default, the value of this variable is set to ”/cache”, a directory within the root directory of your X-Cart.

Export directory

$export_dir = $log_dir;

The variable $export_dir defines the location of X-Cart export directory (a directory on X-Cart server to which the CSV files of export packs are stored). By default, the value of this variable is set to $log_dir, a variable representing X-Cart log directory.

Correcting debug mode

$debug_mode = 2;

The variable $debug_mode defines the amount of debugging information which is visible on the customer side. By default, the value of this variable is set to 3. Make sure you set this variable value to 2 so that all the debugging information is hidden from the customer.

SECTION MARKED "DO NOT CHANGE ANYTHING BELOW THIS LINE UNLESS YOU REALLY KNOW WHAT YOU ARE DOING"

We strongly recommend you do not change any configuration settings that go below the line that says:

# DO NOT CHANGE ANYTHING BELOW THIS LINE UNLESS

# YOU REALLY KNOW WHAT ARE YOU DOING

Editing the settings below this line requires profound knowledge of X-Cart architecture. Considerable damage may be done to your store if these settings are tampered with.

However, please be aware that this section contains the following important constants:

This constant defines whether data caching should be used in your store or not. Admissible values for USE_DATA_CACHE are 'true' and 'false'. By default, the value of this constant is set to 'true'. You can set it to 'false' if you experience problems using the store with caching enabled (for example, if you get some kind of error regarding a file in the /var/cache directory of your X-Cart installation).

define("USE_DATA_CACHE", true);

This constant allows you to enable a functionality that will prevent usage of your store's back-end from IP addresses unknown to the system. Admissible values for SECURITY_BLOCK_UNKNOWN_ADMIN_IP are 'true' and 'false'. By default, the value of this constant is set to 'false'. For more information about SECURITY_BLOCK_UNKNOWN_ADMIN_IP, please refer to the chapter User Access Control.

define("SECURITY_BLOCK_UNKNOWN_ADMIN_IP", false);

This constant allows you to enable synchronization of user sessions on the main website of your store and on domain aliases. Admissible values for USE_SESSION_HISTORY are 'true' and 'false'.

Note: This constant needs to be set to 'true' if you use a domain alias for your store's Customer zone and need to be able to keep working in your store's back-end without losing your user session after you open the Customer zone of your store in another window of the same browser.

define("USE_SESSION_HISTORY", true);

This constant sets the length for the list of unique form identifiers.

Note: Unique form identifiers are used in X-Cart as a means of protection from CSRF (cross site request forgery) attacks. Unique form identifiers are unique identifiers generated within a user session and assigned to each X-Cart's page that is loaded in the user's browser and contains an HTML form intended for submitting input data via the POST method. The main purpose of form identifiers is to ensure authenticity of the form when the form is submitted by the user: if the submitted form contains a valid form identifier, the form is believed to be generated by X-Cart in the current user's session and, thus, valid and safe for use; if there is no valid form identifier, the form is treated as suspicious and the submit process is canceled. X-Cart keeps an ordered list of identifiers of forms opened by a user successively within one user session. All the form identifiers stored in this list are considered valid. The length of the list (the number of form identifiers that can be stored in the list) corresponds to the value of the constant FORM_ID_ORDER_LENGTH. As the number of forms opened by the user in one session exceeds the value defined by FORM_ID_ORDER_LENGTH, the form identifiers that were entered into the list earliest are removed from the list giving way to the identifiers of the most recently opened forms. Thus, even the forms that were originally valid lose validity after the user opens a number of form pages defined by the constant FORM_ID_ORDER_LENGTH. In this sense, the constant FORM_ID_ORDER_LENGTH determines, how many form pages a user should be able to open in one user session before X-Cart refuses to submit the very first form he opened in this session, should he try to submit it after opening a number of other forms.

By default, the value of FORM_ID_ORDER_LENGTH is set to 100. If FORM_ID_ORDER_LENGTH is not declared or is set to a non-numeric value or a value less than 1, it's value will be set to 100.

A unique form identifier ensures that a form is valid.

define("FORM_ID_ORDER_LENGTH", 100);

FRAME_NOT_ALLOWED

This constant allows you to prohibit opening X-Cart in an iFrame. If it is set to 'true' X-Cart will detect that it is being opened in an iFrame and open as the main page instead.

define("FRAME_NOT_ALLOWED", true;

SECTION MARKED "NEVER CHANGE THE SETTINGS BELOW THIS LINE MANUALLY"

In config.php, there is a section that says:

#################################################################

# NEVER CHANGE THE SETTINGS BELOW THIS LINE MANUALLY

#################################################################

Under no circumstances should you try to edit this section, as it will most probably destroy your store.

For example, this section contains the variable $blowfish_key. This variable stores your Blowfish encryption key automatically generated by X-Cart during installation. This key is used to encrypt all the sensitive data in your store including user passwords, credit card data, etc.

NEVER try to change your Blowfish encryption key by editing the value of the $blowfish_key variable in config.php: your data is already encrypted with this key and X-Cart needs exactly the same key to be able to decrypt it. Changing $blowfish_key manually will corrupt all the user passwords (including the administrator's password), so you will not be able to use the store.

Please be aware that a lost Blowfish key cannot be restored, so X-Cart team will not be able to help you regain access to your store if you remove or change the value of $blowfish_key.

It is quite safe to use X-Cart with the Blowfish key generated during installation; however, if you still wish to change it, use the utility for re-generation of the Blowfish encryption key provided with X-Cart tools (For details, refer to the chapter 'Tools' in the 'Maintaining Your Store' section of this manual).

Note: The SALT & CODE encryption method which was used for user password and credit card protection in the previous X-Cart versions has been removed in X-Cart 4.1.x and is now fully replaced by the Blowfish Encryption Algorythm. 

top.inc.php configuration file

Directories structure definitions

$xcart_dir = realpath(dirname(__FILE__));

The variable $xcart_dir defines the location of the directory where X-Cart is installed. By default, the value of this variable is set to ‘realpath(dirname(__FILE__))’, where __FILE__ is a PHP constant representing the absolute filepath to top.inc.php. On certain operating systems the __FILE__ constant is defined in ways which make it impossible to define the location of your X-Cart installation directory.

For example, on SunOS, the __FILE__ constant for included files contains a relative filepath instead of an absolute one. This causes the value of the $xcart_dir variable to be defined as “/”, which is wrong.

If a similar problem causes errors on your server (you get error messages that say “Cannot include file”), redefine the value of the $xcart_dir variable manually: replace the string ‘realpath(dirname(__FILE__))’ by the actual path to your X-Cart installation.

Example:

$xcart_dir = ‘/home/user/public_html/xcart’;

Directories location definition

define ('DIR_CUSTOMER', '');

define ('DIR_ADMIN', '/admin');

define ('DIR_PROVIDER', '/provider');

define ('DIR_PARTNER', '/partner');

This section allows you to define the location of the directories corresponding to the major areas (zones) of your X-Cart. By default, the scripts of X-Cart Customer zone are located in X-Cart root directory, the scripts of X-Cart Admin and Provider zones – in the ‘/admin’ and ‘/provider’ directories respectively; in stores where X-Affiliate add-on module is installed there is also a directory named ‘/partner’ for the scripts of X-Cart Partner zone. If, for some reason, you want to change the location of your major X-Cart zones, edit the values of the corresponding constants.

Example:

If your X-Cart is installed in /home/user/public_html/xcart (seen from the Web as http://www.example.com/xcart), setting DIR_CUSTOMER as follows:

define (’DIR_CUSTOMER’, ’’);

will result in the placement of your X-Cart Customer zone scripts into X-Cart root directory (/home/user/public_html/xcart), so that your customers will be able to access the Customer zone at http://www.example.com/xcart.

Setting DIR_CUSTOMER as follows:

define (’DIR_CUSTOMER’, ’/customer’);

will result in the placement of your X-Cart Customer zone scripts into the directory /home/user/public_html/xcart/customer, so that your customers will be able to access the Customer zone at http://www.example.com/xcart/customer.