Developer getting started guide

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.

Deploy file

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

If you use Docker and not the Development Virtual Machine (DevVM), you don’t need the DevVM’s configs. Therefore, remove the following files:

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

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:

Independent installation

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.

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.

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.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". 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:

1. To define how to manage and configure the settings in configuration files, see Configuration management.
2. Configure your environment:
   • Database
   • Redis
   • Queue
3. Configure stores to have one or multiple stores in your online shop.
4. 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:

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

Data import clean up

In the data/import folder, there are many files related to each store. Define the stores you need and remove all the unused files.

To allow stores, 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 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.

Code sniffer

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.json file.

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>

PhpStan

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.

Plugins

Configure the following plugins:

• PYZ
• 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:

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

7. Debugging

Before you start developing, 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 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.