Developer getting started guide

This document guides you into getting started with the Spryker Commerce OS. It has been structured as a step-by-step checklist to help get you through all of the stages involved in working with Spryker. After following these instructions, if you still have any questions, you can access our Spryker Community Slack group.

1. Install Spryker

For the starting point of any project, it is good to start from one of the Spryker Demo Shops that are available. They act as a typical Spryker installation and help to establish different types of the Spryker Commerce OS. A Demo Shop includes different sets of components that have been selected for a different type of business or project. Each of these options is fully functional and can be used for both demonstrative purposes as well as working as a boilerplate for your new project. Though each shop comes with its own pre-selected components, Spryker also offers hundreds of additional modules which can be chosen 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.

Both Demo Shops can also be expanded with separate features and modules.

Install Spryker with Docker

When installing Spryker, we recommend starting with a Docker SDK environment. It features a lightweight environment that is closer to production implementation. This option includes Docker and related tools to build and run containers that match your requirements.

To start developing your Spryker in Docker, see Installing Spryker with Docker. Spryker can be run on MacOS, Linux, and Windows with WSL1 or WSL2.

• Make sure you have all of the necessary prerequisites before installing docker.
• Once you have the necessary prerequisites set up, you can then choose your installation mode with your OS. You can install docker in modes for Development, Demo, or add it to an existing project.

The deploy file

When working with a local environment, you should 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
• Regions
• Stores
• 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

When you use Docker and not the Development Virtual Machine (also called DevVM), you do not need the DevVM’s configuration files. Therefore, you can remove the following files:

• config/install/development.yml
• config_default-development_*.php

Install Spryker with the Development Virtual Machine

The Spryker Commerce OS offers a Virtual Machine, which includes all of the prerequisites needed to run Spryker. It provides a full-featured development environment, which helps you customize Spryker based on your project’s requirements. The Development Virtual Machine (DevVM) is based on VirtualBox and Vagrant and can be used to install Spryker on any operating system.

We offer a number of installation guides that may suit your needs:

Independent installation

Alternatively, you can install Spryker without the Docker images. See Installing Spryker without Docker for details.

Adjust the readme.md file

Once your project has been installed, you need to adjust the readme.md file in the following ways:

• Update the project installation description.
• Update the repository link.
• Remove any unused information, such as Vagrant installation instructions if a DevVM was not used.
• Consider moving the production information further done in the file so that new developers can more readily understand how to use the project.

2. Manage modules

Once the installation of your new project has been completed, you may start to manage the modules you want to use. A module within Spryker is a single-function unit that has well-defined dependencies and can be updated independently.

When installing and managing module dependencies, we use Composer. Depending on what you want to do, you can run one of the following Composer commands:

• To install the dependencies you listed in the composer.json file of the project: composer install.
• To update all the modules for your project: composer update "spryker/*".

• To update a particular module: composer update "spryker/module-name".

• To add a new module to your project: composer require "spryker/module-name".

To learn about the module versioning approach in Spryker, see Semantic Versioning: Major vs. Minor vs. Patch Release.

3. Configure the environment

The next step to take once installation has finished and modules set up, you need to configure and customize your Spryker Commerce OS. For this, you can do the following:

1. Define how to manage the settings in the configuration files with Configuration management.
2. Configure your environment:
   • Database
   • Redis
   • Queue
3. Configure stores depending on your need for one or multiple stores in your online shop.
4. Schedule tasks (Cron jobs).

Store clean-up

This step depends on the store setup you came up with during your configuring. For example, if you choose to start with just one store, you should clean up the remaining stores in the following files:

• config/install/*
• data/import/*
• deploy.dev.yml
• config_default.php
• src/SprykerConfig/CodeBucketConfig.php

Modules clean-up

• Analyze modules that you have in the desired Demoshop.
• Analyze modules that you need to have.
• Remove unnecessary modules (to do that, you can use the migration guide backward).

Data import clean-up

Located in the data/import folder, you may find additional files related to these other stores. As with cleaning up stores, you must define the stores you intend to use and remove unused files of the rest.

For those stores that you wish to allow, don’t forget to edit CodeBucketConfig::getCodeBuckets().

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 for good code quality and 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 code checkers. To keep your code clean, we recommend using the code checkers.

Code Sniffer

Before running any code sniffer, we recommend that you update it to its latest version. There are often changes that introduce new checks which help to increase the quality of code. When updating, be sure to keep in mind that you will also need to make changes to the composer.json file.

composer update spryker/code-sniffer slevomat/coding-standard --with-dependencies

At the project level, you may choose to use your own rules or to exclude rules enabled in Spryker by default.

• To activate 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>

PHPStan

When using PHPStan, we recommend version 1.2.* or later. These versions help you avoid memory and other issues.

This can be toggled at the project level by enabling rule level 6:

vendor/bin/phpstan analyze -l 6 -c phpstan.neon src/

6. Configure PhpStorm

If you wish to speed up your work, we recommend configuring PhpStorm.

Plugins

Make sure to configure the following plugins:

Speed up indexation

At 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 the folder and select Mark Directory As > Excluded.

It is safe to disable cache indexing for the following files:

• data/cache
• data/tmp
• public/(Yves/Zed/Marketlace)/assets

7. Configure debugging

Before you start developing, you should set up and get to know your debugging environment. To learn how to configure debugging, see one of the following:

• Configuring debugging in Docker
• Configuring debugging in DevVM

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 documents:

• 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.