Developer getting started guideEdit on GitHub
Welcome to the Spryker Commerce OS getting started guide.
We structured this page as a step-by-step checklist for you to follow through all the stages of working with Spryker.
1. Install Spryker
The typical Spryker installation process includes installing a proper starting point for your project. The best option to start projects is to use Demo Shops. A Demo Shop is a set of Spryker Commerce OS components selected for a specific type of business and project. They are fully functional and can be used both for demonstration purposes and as a boilerplate for your project. Even if a shop does not provide all the capabilities you need, you can install the necessary components later.
You can choose from the following options:
- B2B Demo Shop - a boilerplate for B2B commerce projects.
- B2C Demo Shop - a starting point for B2C implementations.
- Separate Features and modules - you can also expand both Demo Shops with separate features and modules.
Installing Spryker with Docker
We recommend starting with a Docker SDK environment. This option includes Docker and related tools to build images and run containers that match your requirements.
It features a lightweight environment that is closer to production implementation.
To start developing your Spryker in Docker, see Installing Spryker with Docker.
For the local environment, use the deploy.dev.yml file.
In the default deploy file, change the following attributes:
- Namespace: We recommend specifying the name for your project, as this helps to avoid issues when you have two or more projects with the same names.
- Domains for the local environment.
- Domains for the services (RabbitMQ, Jenkins): Optional, but this can help to keep all project links together.
Vagrant clean up
If you use Docker and not the Development Virtual Machine (DevVM), you don’t need the DevVM’s configs. Therefore, remove the following files:
Installing Spryker with the Development Virtual Machine
Spryker Commerce OS comes with a Virtual Machine that has all the prerequisites to run Spryker. It provides a full-featured development environment that will help you customize Spryker per your project requirements. The Development Virtual Machine (DevVM) is based on VirtualBox and Vagrant, and can be used to install Spryker on any Operating System.
Choose an installation guide that suits your needs best:
|Operating system||B2B Shop or B2C Shop|
|DevVM on Linux / Mac OS||B2B or B2C Demo Shop installation: Mac OS or Linux, with Development Virtual Machine|
|DevVM on Windows||B2B or B2C Demo Shop installation: Windows, with Development Virtual Machine|
Alternatively, you can install Spryker on an operating system that fulfills Spryker DevVM system requirements without the virtual machine or Docker images. See B2B or B2C Demo Shop installation: without Development Virtual Machine for details.
After installing, make sure to have a look at Post-Installation steps and additional info for tips on fine-tuning Spryker.
Adjusting the readme file
After you install the project, adjust the readme.md file as follows:
- Update the project installation description.
- Update the repository link.
- Remove the unused information, for example, Vagrant installation instructions if you don’t use the DevVM.
- Consider moving the production information down, as this can help new developers easily understand how to use the project.
2. Manage your modules
Once you have completed the installation, you can start managing modules. A module is a single functional unit that has well-defined dependencies, and can be used and updated independently.
To define your strategy of taking Spryker updates, learn about our module and feature release process.
We use Composer to install and manage module dependencies. Run the following Composer commands depending on what you want to do:
- To install the dependencies you listed in the
composer.jsonfile of the project:
- To update all the modules for your project:
composer update "spryker/*".
We recommend running this command weekly to assert you have the latest fixes. We also recommend subscribing to our release notes newsletter to stay up-to-date with the improvements.
- To update a particular module:
composer update "spryker/module-name". You can easily keep track of new module versions using the composer-versions-check addon for your local Composer tool.
- To add a new module to your project:
composer require "spryker/module-name"
See Semantic Versioning: Major vs. Minor vs. Patch Release to learn about the module versioning approach in Spryker.
3. Configure the environment
To configure and customize your Spryker Commerce OS, do the following:
- To define how to manage and configure the settings in configuration files, see Configuration management.
- Configure your environment:
- Configure stores to have one or multiple stores in your online shop.
- Schedule tasks (Cron jobs).
Store clean up
This step depends on the store setup which you plan to have. If you start with one store, consider cleaning up the remaining stores right away in the following files:
Data import clean up
data/import folder, there are many files related to each store. Define the stores you need and remove all the unused files.
Keep in mind that you should also change the default config in
To allow stores, edit
4. Configure CI
Continuous integration (CI) is a development practice where each part of the code can be verified by an automated build and automated tests. This allows to have a good code quality and be sure that each new feature does not break the existing functionality. The following documents will help you to enable CI in different repositories:
- Deployment pipelines
- Customizing deployment pipelines
- GitHub Actions
- Configuring GitLab pipelines
- Azure Pipelines
- Configuring Bitbucket Pipelines
5. Configure checkers
To keep your code clean, we recommend using the code checkers.
Before running the code sniffer, we recommend updating it to the latest version, as it introduces new checks that increase the code quality even more. When updating, keep in mind that you also need to change the
composer update spryker/code-sniffer slevomat/coding-standard --with-dependencies
On the project level, you may decide to use your own rules or exclude some that are enabled in Spryker by default.
To enable a new rule, check out the full list of rules at Slevomat Coding Standard.
To disable a rule, you can use configuration. The following example excludes a rule that makes annotation for constructor and method required:
<rule ref="vendor/spryker/code-sniffer/Spryker/ruleset.xml"> <exclude name="Spryker.Commenting.DocBlock"/> </rule>
For PHPStan, we recommend using version 1.2.* or later. These versions help you avoid memory and other issues.
On a project level, you can enable rule level 6:
vendor/bin/phpstan analyze -l 6 -c phpstan.neon src/
6. PhpStorm configuration
We recommend configuring your PhpStorm properly to speed up your work.
Configure the following plugins:
- Symfony Support
Speed up indexation
In the beginning of the project, you need to reset your project quite often. PhpStorm indexing is annoying and takes too much of the resources. To avoid this, you can disable cache indexing.
To disable cache indexing, in the PhpStorm, right click on the folder and select Mark Directory As->Excluded.
It is safe to disable cache indexing in the following files:
Before you start developing, set up and get to know your debugging environment. To learn how to configure debugging, see one of the following:
8. Familiarize yourself with the Spryker architecture
As a developer, the Spryker structure is the first thing you need to know to extend the core functionality. To familiarize yourself with the Spryker architecture, different parts of the Client, Shared, Zed and Yves folders and their different layers, see the following articles:
- Conceptual overview: to learn about application layers and code structure.
- Modules and layers: to learn about layers and how various functionality is encapsulated in modules.
- Programming concepts: to learn about the Spryker building blocks contained in the application layers.
- Technology stack: to learn about the technologies we use.
For submitting the form