X-Cart:Config.php

X-Cart’s main configuration file config.php is located in the X-Cart root directory. config.php is a plain text file which keeps global definitions and directives for the installed copy of the X-Cart software. The values of the variables inside the config.php file must be edited very carefully, because these settings affect the general operating capability of your store.

The instructions below aim at helping you understand what each of the variables answers for, so that you could configure your store correctly.

SQL database details

$sql_host =’%SQL_HOST%’;
$sql_user =’%SQL_USER%’;
$sql_db =’%SQL_DB%’;
$sql_password =’%SQL_PASSWORD%’;

This section contains variables which keep the details of the MySQL database that you use for your X-Cart based store. X-Cart uses the values of these variables to connect to the database. If the variables contain incorrect values, X-Cart will not be able to connect to the database and open any of the store pages. Instead, you will see an error message saying that X-Cart cannot connect to the MySQL server.

With automatic installation via the Installation Wizard, you do not need to modify the values of these variables, because the installation script writes the new values of the variables according to the information that you provide at the third step of the Installation Wizard (Step 3: Preparing to install X-Cart database).

However, if you install X-Cart manually, you need to edit the values of the variables and provide correct access information for the database and the database server. You may also need to edit the values of these variables when you transfer/copy your store to a different server or when your MySQL server details change.

The variables in this section correspond to:

• $sql_host: The DNS name or the IP-address of your MySQL server (and, optionally, socket);
• $sql_user: The username for your MySQL user account;
• $sql_db: The name of your MySQL database;
• $sql_password: The password for your MySQL user account.

X-Cart HTTP & HTTPS host and web directory

$xcart_http_host =”$HTTP_HOST”;
$xcart_https_host =”$HTTP_HOST”;
$xcart_web_dir =”/xcart”;

This section contains variables which keep the information about the physical location of the X-Cart files. X-Cart uses the values of these variables to correctly address the scripts, templates and other X-Cart files. If the variables contain incorrect values, X-Cart will not be able to display pages correctly.

With automatic installation via the Installation Wizard, you do not need to modify the values of these variables, because the installation script writes the new values to the variables according to the information that you provide at the third step of the Installation Wizard (Step 3: Preparing to install X-Cart database).

However, if you install X-Cart manually, you need to edit the values of the variables and provide correct names of the host and the X-Cart root directory. You may also need to edit the values of these variables when you transfer/copy your store to a different server/location or when your change the DNS.

The variables in this section correspond to:

• $xcart_http_host: The host name of the server on which X-Cart is installed.
• $xcart_https_host: The host name of the secure server which provides access to X-Cart via the HTTPS protocol.
• $xcart_web_dir: The web accessible directory of your server/hosting account where X-Cart files are located.

The variables $xcart_http_host and $xcart_https_host must contain host names only (no protocol prefixes ‘http://’ or ‘https://’, no trailing slashes). If you are not sure what the host name of your secure server is, contact your hosting team for help. In most cases the names of your secure and non-secure servers will be the same.

The name of your X-Cart directory must represent how the directory can be accessed from the Web, not from the file system. The general rule here is to put a slash before the name of the directory and no slash at the end (for example, /xcart). An exception applies to the situation when you install X-Cart to the WWW root. In this case you must leave the variable empty.

Example 1:

If the store URLs are:

http://www.example.com/xcart and http://www.securedirectories.com/example.com/xcart

the variables must have the following values:

$xcart_http_host ="www.example.com";
$xcart_https_host ="www.securedirectories.com/example.com";
$xcart_web_dir ="/xcart";

Example 2:

If the store URLs are:

http://www.example.com/ and https://www.example.com/

the variables must have the following values:

$xcart_http_host ="www.example.com";
$xcart_https_host ="www.example.com";
$xcart_web_dir ="";

It is also possible that you use domain aliases for your store; however, your store visitors will be redirected to the primary domain if they open the store through an alias. For example, if the store is installed to a domain name example.com which has an alias www.example.com, store visitors will be redirected to http://example.com even if they open in their browsers http://www.example.com.

Storing Customers’ Credit Card Info

$store_cc = false;

The variable $store_cc allows you to define whether you wish to keep your customers' credit card information in the store database or not.

This variable must be set to true in case you enable 'Subscription' module or 'Credit Card' off-line payment method (manual credit card processing) in the 'Payment methods' section.

Customers provide their credit card details at the checkout. This info includes:

• cardholder’s name;
• card type;
• card number;
• "valid from" date (for certain types of cards);
• expiration date;
• card issue number (for certain types of cards).

The two possible values for the $store_cc variable are ‘true’ and ‘false’. By default the variable is set to ‘false’. It means that X-Cart does not keep in its database any credit card info that your customers provide when paying for products with their credit cards.

This variable must be set to true in case you enable 'Subscription' module or 'Credit Card' off-line payment method (manual credit card processing) in the 'Payment methods' section.

In this case, your customers' credit card info goes directly to the payment gateway which then processes the payment and sends the money to your merchant account. This way of accepting credit card payments online is common practice these days, because it allows you not to pay special attention to the advanced secure environment which is a must when it comes to keeping sensitive credit card info. Besides, keeping credit card info in a store database is not recommended by the major credit card authorities like VISA and MasterCard, because this task requires high security level of the environment that is used to operate the store (including servers and local computers) which can hardly be ensured by an individual or a medium-size business. Remember: when keeping credit card info in the store database, any possible vulnerability of the environment may result in data theft and potentially involves legal liability.

However, if your business model supposes keeping credit card info and you have adequate resources to ensure the required security level, you can allow X-Cart to keep credit card info in its database by changing the value of the variable $store_cc to 'true'. Or you can leave the value of the variable as 'false' and consider an alternative way of taking credit card info of your customers.

Also, the variable $store_cvv2 must be set to 'true' if you are planning to use the Subscriptions module which introduces the ability to use recurring billing where money for certain products is automatically withdrawn from customer's credit cards at scheduled periods of time. For details on how to use the Subscriptions module, study section Subscriptions.

Storing CVV2 codes

$store_cvv2 = false;

The variable $store_cvv2 allows you to define whether you wish to keep CVV2 codes of your customers’ credit cards in the store database or not.

The two possible values for the $store_cvv2 variable are ‘true’ and ‘false’. By default the variable is set to ‘false’. It means that X-Cart does not keep in its database the CVV2 codes that your customers provide when paying for products with their credit cards.

In this case, the CVV2 codes go directly to the payment gateway which then processes the payment and sends the money to your merchant account. This way of accepting credit card payments online is common practice these days, because it allows you not to pay special attention to the advanced secure environment which is a must when it comes to keeping sensitive credit card info including CVV2 codes. Besides, keeping CVV2 codes (especially with the other credit card info) in a store database is not recommended by the major credit card authorities like VISA and MasterCard, because this task requires high security level of the environment that is used to operate the store (including servers and local computers) which can hardly be ensured by an individual or a medium-size business. Remember: when keeping credit card info (including CVV2 codes) in the store database, any possible vulnerability of the environment may result in data theft and potentially involves legal liability.

However, if your business model supposes keeping CVV2 codes and you have adequate resources to ensure the required security level, you can allow X-Cart to keep the codes in its database by changing the value of the variable $store_cvv2 to 'true'. Or you can leave the value of the variable as 'false' and consider an alternative way of taking CVV2 codes of your customers' credit cards.

Also, the variable $store_cvv2 must be set to 'true' if you are planning to use the Subscriptions module which introduces the ability to use recurring billing where money for certain products is automatically withdrawn from customer's credit cards at scheduled periods of time. For details on how to use the Subscriptions module, study section Subscriptions further in this manual.

Storing Customers’ Checking Account Details

$store_ch = false;

The variable $store_ch allows you to define whether you wish to keep your customers' checking account details in the store database or not. Customers provide their checking account details at the checkout. This info includes:

• bank account number;
• bank routing number;
• fraction number.

The two possible values for the $store_ch variable are ‘true’ and ‘false’. By default the variable is set to ‘false’. It means that X-Cart does not keep in its database the checking account details that your customers provide when paying for the products with their personal checks.

In this case, the checking account details go directly to the payment gateway which then processes the payment and sends the money to your merchant account. This way of accepting credit card payments online is common practice these days, because it allows you not to pay special attention to the advanced secure environment which is a must when it comes to keeping sensitive data including checking account details. Along with keeping credit card details, keeping checking account details also requires high security level of the environment that is used to operate the store (including servers and local computers) which can hardly be ensured by an individual or a medium-size business. Remember: when keeping checking account details in the store database, any possible vulnerability of the environment may result in data theft and potentially involves legal liability.

However, if your business model supposes keeping checking account details and you have adequate resources to ensure the required security level, you can allows X-Cart to keep this data in its database by changing the value of the variable $store_ch to 'true'. Or you can leave the value of the variable as 'false' and consider an alternative way of taking checking account details from your customers.

Default images

$default_image = "default_image.gif";

The variable $default_image allows you to define what image file should be used as the default “No image available” placeholder. A placeholder here means the image that appears in place of any missing image in your store. The default value of the variable is “default_image.gif”. The image file default_image.gif is physically located in the X-Cart root directory.

If you wish to use a different placeholder image, you can either replace the default image file with a different file having the same name or change the value of the variable $default_image and specify the path to the image file and the image filename.

Note: You can upload your own image placeholders for missing X-Cart images of different types (product thumbnails, product images, category icons, detailed images, variant images, manufacturer logos, product class images). You can do it through the Images location section of the Admin area.

$shop_closed_file = "shop_closed.html";

The variable $shop_closed_file allows you to define what HTML page should be displayed in place of the Customer area when you store is temporarily closed for visitors. The default value of this variable is "shop_closed.html". The HTML file is physically located in the X-Cart root directory.

If you wish to use a different HTML page, you can either replace the default image file with a different file having the same name or change the value of the variable $shop_closed_file and specify the path to the HTML page and page filename.

Single Store mode (X-Cart PRO only)

$single_mode = true;

The variable $single_mode allows you to enable/disable the Single Store mode if your store is based on X-Cart PRO. The Single Store mode is an operating mode which represents your X-Cart PRO based store as a unified environment shared by multiple providers who can edit the products of other store providers. When the Single Store mode is enabled, shipping rates, discounts and discount coupons, taxes and other settings and components are the same for all the store providers.

The two possible values for the $single_mode variable are ‘true’ and ‘false’. Setting the value to ‘true’ enables the Single Store mode. Setting the value to ‘false’ restores the normal mode where your store providers can control their products only and can have their own shipping rates, discounts, taxes, etc.

Note: If your store is based on X-Cart GOLD, the value of $single_mode must always be set to ‘true’. Changing the value to ‘false’ will not turn your X-Cart GOLD into X-Cart PRO.

You should only change the value of the $single_mode variable 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 settings, these settings will be corrupted.

FedEx Rates directory

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

The variable $fedex_default_rates_dir keeps the location of the directory with files which control correct calculation of the FedEx shipping rates. By default the value of this variable is set to '$xcart_dir.”/shipping/FedEx/”', where $xcart_dir means the X-Cart root directory.

Log directory

$log_dir = ”/log”;

The variable $log_dir keeps the location of the directory with the X-Cart log files. By default the value of this variable is set to '/log'. The '/' sign means that the log directory is located inside the X-Cart root directory.

Cache directory

$data_cache_dir = ”/cache”;

The variable $data_cache_dir keeps the location of the directory with the X-Cart cache files. By default the value of this variable is set to '/cache'. The '/' sign means that the cache directory is located inside the X-Cart root directory.

Export directory

$export_dir = $log_dir;

The variable $export_dir keeps the location of the directory to which X-Cart exports CSV files with data. By default the value of this variable is set to '$log_dir' where $log_dir means the directory with the X-Cart log files.

Correcting debug mode

$debug_mode = 2;

The variable $debug_mode allows you to define the amount of the debugging information which can be displayed in the Customer area. By default the value of this variable is set to 3. Changing the value to 2 allows you to hide from your store visitors all the debugging information.

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 the X-Cart architecture. Tampering with these settings may cause considerable damage to your store.

However, sometimes it may be critical to know what the constants of this section mean.

define("USE_DATA_CACHE", true);

This constant defines whether your store should use data caching or not. The two possible values for the USE_DATA_CACHE constant are 'true' and 'false'. By default the value is set to 'true'. It means that caching is enabled.

Changing the value to 'false' is reasonable only if you experience problems in using the store with the enabled caching (e.g. if you keep getting error messages about the files in the /var/cache directory of your X-Cart installation).

define("SECURITY_BLOCK_UNKNOWN_ADMIN_IP", false);

This constant allows you to enable the functionality for blocking access to the Admin area of your store from unknown IP addresses. The two possible values for the SECURITY_BLOCK_UNKNOWN_ADMIN_IP constant are 'true' and 'false'. By default the value is set to 'false'. It means that the Admin area can be accessed from any IP address. Before changing the value of this constant, study section User Access Control further in this manual.

define("USE_SESSION_HISTORY", true);

This constant allows you to enable the functionality for synchronizing user sessions of the primary store domain and additional domain aliases. The two possible values for the USE_SESSION_HISTORY constant are 'true' and 'false'.

The value of this constant must be set to 'true' if you use domain aliases for the Customer area of your store and wish to be able to simultaneously work both with the Admin and Customer areas without losing your current user session.

define("FORM_ID_ORDER_LENGTH", 100);

The FORM_ID_ORDER_LENGTH constant defines the length of a list with unique form identifiers which are used in X-Cart to protect the store against CSRF (cross-site request forgery) attacks.

For each user session, the system generates an ordered list of unique identifiers and assigns them to every X-Cart’s page opened by the user which contains a submittable HTML form designed for sending input data using the POST method.

These identifiers are intended to ensure authenticity of every single form: each time the user is trying to submit a form, X-Cart checks whether the form identifier is in the list. If yes, the form is considered genuine (i.e. generated by X-Cart during the current session) and, thus, safe for sending input data. If the identifier is missing from the list, the form is treated as suspicious, and no input data can be submitted through it.

The number of identifiers in the list corresponds to the value of the FORM_ID_ORDER_LENGTH constant. By default the value is set to 100. It means that for every section the list can contain no more than 100 unique identifiers. And at one time X-Cart will consider as genuine no more than 100 forms. If the number of forms opened by the user during one section exceeds the value defined by FORM_ID_ORDER_LENGTH, X-Cart will remove from the list the earliest identifiers and replace them with new identifiers for the recently opened forms.

By editing the value of the FORM_ID_ORDER_LENGTH constant you can increase or decrease the number of forms that will be concurrently considered as genuine. If the value is not declared or is less than 1 or is set to a non-numeric value, it will be automatically set to 100.

define("FRAME_NOT_ALLOWED", true);

This constant allows you to prohibit opening X-Cart in an iFrame. If the value of the FRAME_NOT_ALLOWED constant is set to 'true', the system will detect any attempt to open X-Cart in an iFrame and force to open it in a main window instead.

Section marked "NEVER CHANGE THE SETTINGS BELOW THIS LINE MANUALLY"

The config.php file contain a section saying:

# ################################################################
# NEVER CHANGE THE SETTINGS BELOW THIS LINE MANUALLY
# ################################################################

You must never edit variables in this section, because it will apparently destroy your store.

For example, this section contains the variable $blowfish_key. This variable keeps your store's Blowfish key that was automatically generated during the X-Cart installation. This key is used to encrypt and decrypt all the sensitive data in your store database including user passwords, credit card info, etc. Since the data in already encrypted, editing the value of the $blowfish_key variable manually will corrupt all user passwords (including the administrator password) and you want be able to use the store. You must also be aware of the fact that a lost Blowfish key cannot be restored, and the X-Cart Support team will not be able to help you regain access to your store if you remove or change the value of the $blowfish_key variable.

If for some reason you need to re-generate the Blowfish key generated during the installation, use the built-in X-Cart facility described in the Re-generate the Blowfish Encryption Key section of this manual.