Installation

Requirements

Web ServerLinux and Apache 2.4+ with mod_rewrite and mod_headers
DatabaseMySQL 5.7.22+ or MariaDB 10.5.0+. InnoDB storage engine
Minimum PHP Version8.2.0 (currently tested up to 8.5.12)
PHP Extensionscurl, fileinfo, json, openssl, pdo, pdo_mysql, zip

Storage space and memory: Depends on the amount of products you want to list, and the potential traffic. A typical small-medium store on any standard shared or VPS hosting (4GB+ RAM, 1GB+ SSD storage space) should be sufficient. The more processing power and RAM, the better.

Email delivery: PHP's native mail() can be used as a fallback, but for reliable email delivery (avoiding spam folders and rejections) we strongly recommend using SMTP.

Orders: To test and start accepting orders, you will need a PayPal developer account, be able to create an app, and obtain sandbox / live API keys.

Install Wizard

xcms install step 1
xcms install step 2
xcms install step 3
xcms install step 4
xcms install step 5
  1. Download the XCMS Core distribution zip file from your account, or from your order confirmation email.
  2. Create a new (blank) MySQL database on your server and note the access credentials (hostname, database name, username, password).
  3. Upload all files from the zip file to your server, using FTP or via your hosting control panel.
  4. Where you uploaded the files, run /install in your browser and follow the instructions carefully.
  5. If all the steps were successful, you should have access to your site admin and front-end.
  6. The installer will be secured and no longer accessible. For extra security, you can rename or delete the /install directory.

SMTP Settings

As mentioned above, to avoid emails going into spam boxes, we strongly recommend using SMTP as the mail delivery method. The popular PHPMailer library is used for the job.

To configure SMTP, edit /includes/config_smtp.php

define('SMTP_FROM_NAME',   SITE_NAME); // Leave as-is

define('SMTP_FROM',        'mail@example.com');
define('SMTP_REPLY_TO',    'noreply@example.com');

define('SMTP_HOST',        'mail.example.com');
define('SMTP_USER',        'mail@example.com');
define('SMTP_PASS',        'password');
define('SMTP_PORT',        587); // Commonly 25, 465 or 587
define('SMTP_SECURE',      'tls'); // Commonly 'tls' or 'ssl'

Check with your host if you are unsure of the settings to use. After saving, test SMTP works correctly by navigating to your site contact form and submit the form.

If you would prefer to temporarily use PHP's native mail() sending method, rename the /vendor/phpmailer folder to anything else, e.g./vendor/phpmailer.disabled

PayPal Credentials

Your PayPal business account must have access to Expanded Checkout which involves completing their onboarding process form.

You won't be able to test orders, or take real orders until you have PayPal 'client' and 'secret' API keys. Go to the developer dashboard to get them (see Apps & Credentials).

Edit /includes/config_paypal.php

define('PAYPAL_CLIENT_ID',  'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
define('PAYPAL_SECRET',     'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
define('PAYPAL_MODE',       'sandbox'); // 'sandbox' or 'live'
define('PAYPAL_CURRENCY',   CURRENCY_CODE); // Leave as-is

For a list of test card numbers in sandbox mode, click here. An easy Visa test card number to remember is 4111 1111 1111 1111

Once you have confirmed that orders work correctly in 'sandbox' mode, you can change the PAYPAL_CLIENT_ID and PAYPAL_SECRET to the 'live' credentials and set the PAYPAL_MODE to 'live'.

SCA/3D Secure

PayPal uses two-factor authentication for online transactions, known as "Strong Customer Authentication" (SCA). For online transactions in Europe and the UK, this extra security is to help keep online card purchases more secure and prevent fraud. By default, SCA is triggered 'when required'. To make it mandatory, in /checkout.php replace...

                contingencies: ['SCA_WHEN_REQUIRED'],

With...

                contingencies: ['SCA_ALWAYS'],

Site Migration

If you are changing URL, or moving from a development URL to a live URL, there is a site migration SQL file included in the XCMS distribution zip file.

It will change all base URLs, everywhere they are stored in the database, including image paths, hyperlinks etc.

First make a database backup, then read and edit /install/sql/migrate-site-url.sql and apply it using a tool such as PHPMyAdmin.

SET @old_url = 'https://example.com/old';
SET @new_url = 'https://example.com/new';

You may also need to manually update the following...

Support

If you have any issues installing or configuring XCMS, feel free to contact us.