X-Cart Developer Documentation

Version: 5.5.0

You can find samples of the nginx and apache setup in the /docs folder of the X-Cart software package.

Since X-Cart is a Symfony 5.4-based application, the general software setup is similar to Symfony despite minor alterations. Hence you can refer to the Symfony 5.4 official documentation in addition to this article.

The public directory

The public directory is the home of your application's public and static files, including images, stylesheets, and JavaScript files. It is also where the front controller (index.php) lives.

The server document root must be configured in the /public subfolder of your X-Cart root. You must also ensure both index.php and service.php are executable.

If you upgraded your software from X-Cart 5.4.1.x and need to reconfigure the server, don't forget to adjust the XCART_PUBLIC_DIR variable in the .env.local file on the server.

XCART_PUBLIC_DIR=0

After that, redeploy the store on the System → Cache Management page of your store's Admin area or use the ./bin/service xcst:rebuild operation in the console.

Apache

Below is the example configuration to get your application running under Apache 2.4 with PHP-FPM.

If you have X-Cart installed into a web directory, see the web directory example configuration.

## X-Cart 5 apache 2.4 sample configuration
#
# Replace placeholders:
# {{public-full-path}} - real full path of public dir
#
# Example
#
# Xcart installation path: /var/www/xcart
# Expected URL: https://localhost/
#
# public-full-path: /var/www/xcart/public
#

LoadModule proxy_module lib/httpd/modules/mod_proxy.so
LoadModule proxy_fcgi_module lib/httpd/modules/mod_proxy_fcgi.so
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so

ServerName xcart.test

<VirtualHost *:80>
    ServerAdmin admin@example.com

    DocumentRoot {{public-full-path}}

    <Directory {{public-full-path}}>
        DirectoryIndex index.php

        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
        FallbackResource /index.php

        <IfModule mod_rewrite.c>
            Options -MultiViews

            RewriteEngine On

            RewriteRule ^sitemap.xml(\?.+)?$ /?target=sitemap [NC,L,QSA]

            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [QSA,L]
        </IfModule>

    </Directory>

    <FilesMatch ".php$">
        SetHandler "proxy:fcgi://127.0.0.1:9000"
    </FilesMatch>

</VirtualHost>

Web directory

## X-Cart 5 apache 2.4 sample configuration
#
# Replace placeholders:
# {{web-dir}} - web dir value
# {{root-full-path}} - real full path of host handler app
# {{public-full-path}} - real full path of public dir (must not be a subdir of root-full-path)
#
# Example
#
# Host handler app path: /var/www/http
# Xcart installation path: /var/www/xcart
# Expected URL: https://localhost/some/dir
#
# web-dir: some/dir
# root-full-path: /var/www/http
# public-full-path: /var/www/xcart/public
#

LoadModule proxy_module lib/httpd/modules/mod_proxy.so
LoadModule proxy_fcgi_module lib/httpd/modules/mod_proxy_fcgi.so
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so

DocumentRoot {{root-full-path}}

ServerName xcart.test

<VirtualHost *:80>
    ServerAdmin admin@example.com

    Alias /{{web-dir}} {{public-full-path}}

    <Directory {{public-full-path}}>
        DirectoryIndex index.php

        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
        FallbackResource /index.php

        <IfModule mod_rewrite.c>
            Options -MultiViews

            RewriteEngine On

            RewriteRule ^sitemap.xml(\?.+)?$ /?target=sitemap [NC,L,QSA]

            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteRule ^ index.php [QSA,L]
        </IfModule>

    </Directory>

    <Directory {{root-full-path}}>
        AllowOverride All
        Require all granted
    </Directory>

    <FilesMatch ".php$">
        SetHandler "proxy:fcgi://127.0.0.1:9000"
    </FilesMatch>

</VirtualHost>

Please carefully check the above configuration sample and adapt it to your server environment.

You can find the sample of an Apache server configuration for a store located in a subfolder but not in the domain root in the /docs folder of the software package.

Nginx

Below is the example configuration to get your application running under Nginx with PHP-FPM.

If you have X-Cart installed into a web directory, see the web directory example configuration.

## X-Cart 5 nginx sample configuration
## Copy this file to your /etc/nginx directory
## and include it to your nginx.conf

#
# Replace placeholders:
# {{projects-dir}} - real full path of projects dir
#
# Example
#
# Projects dir installation path: /var/www/projects
# Some X-Cart store installation path (git clone root): /var/www/projects/xcart1
# Some other X-Cart store installation path (git clone root): /var/www/projects/xcart2
# Expected URL of first store: https://localhost/xcart1/src/public/
# Expected URL of second store: https://localhost/xcart2/src/public/
#

upstream fastcgi_xcart {
   # use tcp connection
   server  127.0.0.1:9000;
   # or socket
   # server   unix:/var/run/php5-fpm.sock;
   # server   unix:/var/run/php/php7.0-fpm.sock;
}

server {
    server_name xcart.test;

    root {{projects-dir}};

    index index.php;
    charset UTF-8;

    location ~ /service\.php/ {
        try_files $uri $uri/ @handler2;
    }

    location @handler2 {
        rewrite ^/(.*src)\/service\.php\/(.*)$ /$1/service.php?$query_string last;
    }

    location / {
        try_files $uri $uri/ @handler;
    }

    location @handler {
        rewrite ^/(.*src)\/(.*)$ /$1/index.php?$query_string last;
    }

    location ~ \.php(/|$) {
        fastcgi_pass                fastcgi_xcart;
        fastcgi_split_path_info     ^(.+\.php)(/.*)$;

        fastcgi_read_timeout                300;

        fastcgi_param   CONTENT_LENGTH      $content_length;
        fastcgi_param   CONTENT_TYPE        $content_type;
        fastcgi_param   DOCUMENT_URI        $document_uri;
        fastcgi_param   QUERY_STRING        $query_string;
        fastcgi_param   REDIRECT_STATUS     200;
        fastcgi_param   REQUEST_METHOD      $request_method;
        fastcgi_param   REQUEST_URI         $request_uri;
        fastcgi_param   SCRIPT_NAME         $fastcgi_script_name;

        fastcgi_param   SCRIPT_FILENAME    $realpath_root$fastcgi_script_name;
        fastcgi_param   DOCUMENT_ROOT      $realpath_root;

        internal;
    }

    location ~ \.(jpg|jpeg|png|gif|woff|woff2|ttf)$ {
        try_files $uri =404;
        break;
    }
}

Web directory

## X-Cart 5 nginx sample configuration
## Copy this file to your /etc/nginx directory
## and include it to your nginx.conf
##
## This configuration is prepared for the following server setup:
## Wordpress in the root of the domain
## XCart in web-dir

#
# Replace placeholders:
# {{web-dir}} - XCart web dir value
# {{root-full-path}} - real full path of host handler app (Wordpress)
# {{public-full-path}} - real full path of XCart public dir
#
# Example
#
# Host handler app path (Wordpress) : /var/www/http
# XCart installation path: /var/www/xcart
# Expected XCart URL: https://localhost/shop
#
# web-dir: /shop
# root-full-path: /var/www/http
# public-full-path: /var/www/xcart/public
#

upstream fastcgi_xcart {
   # use tcp connection
   server  127.0.0.1:9000;
   # or socket
   # server   unix:/var/run/php5-fpm.sock;
   # server   unix:/var/run/php/php7.0-fpm.sock;
}

upstream fastcgi_other {
   # use tcp connection
   server  127.0.0.1:9000;
   # or socket
   # server   unix:/var/run/php5-fpm.sock;
   # server   unix:/var/run/php/php7.0-fpm.sock;
}

# To use virtual web_dir with symfony routing and service-tool is is required to move web_dir from prefix to suffix
map $request_uri $real_request_uri {
    ~^{{web-dir}}(?:/service.php)([^?]*)(\?.*)?$ "/service.php{{web-dir}}$1";
    ~^{{web-dir}}(?:/\w+\.php)?([^?]*)(\?.*)?$ "{{web-dir}}$1";
    default $request_uri;
}

# Determinate real file path
map $request_uri $real_file {
    ~^{{web-dir}}(?:/\w+\.php)?([^?]*)(\?.*)?$ $1;
    default $request_uri;
}

server {
    listen 80 default_server;
    server_name xcart.test;
    root {{root-full-path}};

    index index.php;
    charset UTF-8;

    # Static files must not be processd trough fastcgi handler
    location ~ {{web-dir}}(/.*\.(jpg|jpeg|png|gif|woff|woff2|ttf))$ {
        alias {{public-full-path}};

        try_files $1 =404;
        break;
    }

    # Route index.php and service.php to the fastcgi handler
    location ~ ^{{web-dir}}/(index|service)\.php {
        alias {{public-full-path}};

        try_files $real_file @handler;
    }

    # Route cleanurls to index.php
    location ~ ^{{web-dir}}/ {
        alias {{public-full-path}};

        rewrite ^{{web-dir}}(.*)$ {{web-dir}}/index.php$1;
    }

    # XCart 5.5 handler (web-dir)
    location @handler {
        fastcgi_pass            fastcgi_xcart;

        fastcgi_split_path_info ^{{web-dir}}/(.+\.php)?(.*)$;

        include fastcgi_params;

        # Set real FS path
        fastcgi_param SCRIPT_FILENAME {{public-full-path}}/$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT {{public-full-path}};

        fastcgi_param REQUEST_URI {{web-dir}}/$fastcgi_script_name$fastcgi_path_info?$query_string;

        # Prevents URIs that include the front controller. This will 404:
        # http://domain.tld/index.php/some-path
        # Remove the internal directive to allow URIs like this
        internal;
    }

    # host handler (w/o web-dir)
    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php(/|$) {
        include fastcgi_params;
        fastcgi_intercept_errors on;
        fastcgi_pass fastcgi_xcart;
        #The following parameter can be also included in fastcgi_params file
        fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Please carefully check the above configuration sample and adapt it to your server environment.

You can find the sample of an Nginx server configuration for a store located in a subfolder but not in the domain root in the /docs folder of the software package.

The public directory​

Apache​

Web directory​

Nginx​

Web directory​

The public directory

Apache

Web directory

Nginx

Web directory