Important

You are browsing documentation for version 5.1 of OroCommerce, supported until March 2026. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Set Up Development Environment for OroPlatform Based Application

Please follow the steps outlined in the sections below to set up the development environment for Oro application customization tasks.

Business Tip

Are you searching for the best B2B eCommerce solution? Utilize our platform comparison chart to weigh your alternatives.

Meet the Hardware and OS Requirements

Operating System

The recommended OS for Oro applications is Oracle Linux. However, it is possible to set up the development environment on any Linux, Mac, or Windows with WSL2.
Disk Drive

A solid-state drive (SSD) is recommended. As the Oro application uses many files (vendors, cache), an SSD speeds up everyday development operations much faster than an HDD.
Available RAM

The recommended amount of available RAM is 8Gb for most development operations (e.g., upgrading the application or updating Composer dependencies). However, 2Gb of available RAM is usually enough to run the application.

Prepare Development Tools

Install Git.
Install PHPStorm as the recommended IDE.

Note

Although PHPStorm is recommended, it is not the required IDE for Oro application development. If you use a different IDE, skip the PHPStorm configuration steps below.
Configure PHPStorm:
- Install and configure Symfony plugin and Oro plugin by following the official PHPStorm plugin management instructions.
- Exclude the following directories in PhpStorm (to avoid class duplication and indexation overhead) by right-clicking on the directory and selecting Mark Directory As > Excluded:
  - var/cache
  - public/bundles
- Enable code quality checks in PHPStorm:
  - Enable PHP Code Sniffer (use PSR2 or Symfony2 code standards)
  - Enable PHP Mess Detector, making sure that:
    - Cyclomatic complexity DOES NOT exceed the limit of 15.
    - The limit of the NPath complexity is set to 200 (the default PHPMD limit).
  - Enable PHP CS Fixer (use PHP CS Fixer settings )
- Configure xDebug
  - Integrate a debugging tool into your IDE that provides a range of features to improve the PHP development experience. See how to set up integration between PhpStorm and xDebug for more information.
- Configure PhpUnit
  - If you write tests for your code, integrate PhpUnit with PhpStorm and use it for actual testing.
  Note
  
  You can also set the default configuration for the PhpUnit test runner (path to phpunit.xml, the working directory, etc.). Then you can right-click a test file and select Run <file> to run all tests from the file.

Create a Custom Application

Fork Oro application repository.

Use the Github guide on forking a repo as an illustration of how to fork the Oro application repository.

Note

Pay attention to the Keep your fork synced section of this Github guide. You have to set the original Oro application repository as the remote upstream in order to be able to pull improvements and fixes from the original Oro application.
(optional) Change the README.md file in your repo to describe your application.
(optional) Change the package name of your application in the composer.json file.

Important

Please be aware that in accordance with the Oro PHP Application structure, you have to use only the following folders and files to place your code in your custom application:

src: the main folder for your customization code
templates: the folder for template files
config: folder the folder for config files
translations: the folder for translation files
README.MD: the file for the description of your custom application
composer.json: the file which you can change if you want to make a package from your custom application

Set Up Application Environment

We recommend using Docker and Symfony Server to set up the environment for your custom Oro application.

Hint

There are quick guides to set up the Docker and Symfony Server development stack:

Alternatively, to have a fully dockerized environment, you can use Docker images and stacks for OroPlatform based applications by the Kiboko team.

To check that the environment meets the application requirements, use the oro:check-requirements command:

php bin/console oro:check-requirements

By default, this command shows only errors, but you can increase the verbosity to see warnings and informational messages too:

php bin/console oro:check-requirements -v

php bin/console oro:check-requirements -vv

The command will return 0 on exit if all application requirements are met and 1 if some of the requirements are not fulfilled.

Install Your Application

When the environment is set up, follow the instructions in the Installation Guide to install your application.

Note

If you use Docker and Symfony Server, follow this guide.

Create a Custom Bundle

All OroPlatform-based applications have unique features that facilitate smooth development routines, like autoregistration of bundles and configuration files, for example.

However, these features assume that all application code is organized in bundles. For this reason, you have to create your own bundle for your custom code to perform customization tasks.

Please, follow the How to Create a New Bundle cookbook article to create a bundle in your custom application.

Note

A priority parameter of your bundle should be greater than 210 to make the bundle loaded after all Oro application bundles and to allow override of configuration files from Oro bundles.