Install OXID eShop compilation

There are two ways to install the shop which are graphical and command-line tools. In graphical tools, shop can be installed via wizard setup process in browser, and with command-line tools a provided command can be run to install the shop quickly.

More information can be found in the User documentation.

On this page, additional developer specific information is provided.

Providing shop files

Composer will automatically download the source files of the specified version and edition of OXID eShop.

In a second step it will install fixed versions of the project dependencies as defined in the meta package of the installed edition of OXID eShop.

After Composer installed all dependencies, it executes several tasks. One of them is to generate the classes of the unified namespace \OxidEsales\Eshop.

Watch out for error messages during the installation process.

See our troubleshooting section for solutions.

If by any reason you are not able to use Composer to install OXID eShop or one of its modules on a specific application server, please skip this step and read these instructions to learn how to deploy the source code using an alternative way.

Known issue on MacOS

If you get the following error in the migrations while installing the OXID eShop on a MAMP [PDOException] SQLSTATE[HY000] [2002] No such file or directory

Look at this blog entry and do the following steps:

sudo mkdir /var/mysql
sudo ln -s /Applications/MAMP/tmp/mysql/mysql.sock /var/mysql/mysql.sock
sudo chown _mysql /var/mysql/mysql.sock
sudo chmod 777 /var/mysql/mysql.sock

Always use Composers’ –no-plugins switch

It is a best practice to run all Composer commands, which update components with the –no-plugins option and to run update action in a separate command. Like this it is ensured, that the latest versions of the plugins are used.

Examples:

# Update all components including Composer plugins to their latest version
composer update --no-plugins

# execute plugins in their latest version
composer update

# Install new component and update dependencies including Composer plugins to the required version
composer require --no-plugins monolog/monolog
composer install # execute the plugins in their required version

Temporarily add Composer dependencies

In general you should extended the functionality of OXID eShop by writing modules, which provide there own dependency management. See module section for details. Nevertheless, for a quick hack or a proof of concept, additional dependencies could be added via the composer.json file in the project root directory.

For example, if there is a need to add runtime library like monolog run:

composer require --no-plugins monolog/monolog
composer install

Resolving Composer dependency conflicts

The meta package defines, which exact versions of the components will be installed by Composer. These versions have been tested by OXID eSales to ensure, that OXID eShop works as expected and to avoid security issues. There might be situations, where a 3rd party dependency conflicts with the version defined in the meta package. You may resolve this version conflict by adding an alias in the project composer.json file in the project root directory like this:

{
    "require": {
        "doctrine/cache":"v1.6.0 as v1.6.1"
    }
}

This lowers doctrine cache version to v1.6.0 even while the meta package requires v1.6.1.

See the documentation or this issue in GitHub for details

Building your own compilation

A meta package defines the kind and versions of components of a compilation. You may want build your own compilation for two reasons:

To re-define the components of a compilation:

  • Create a new meta package by using the existing one as a template

  • Re-define the components and their versions

    • Require different versions of existing components

    • Remove predefined components

    • Require new components

To add new components to the compilation:

  • Create a new meta package

  • Require new components

  • Require the existing meta package in the newly created meta package

Make this new meta package available through Packagist, GitHub, file system or any other supported way.

Edit the composer.json file in the project root directory and require the new meta package instead of default one.