Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 30 ยท Getting Started

Setting Up a Development Environment

Set up a local Shopware 6 shop for plugin development: Docker or a native stack, composer create-project, system:install, debug mode and watch scripts.

Before you write a plugin you need a shop to put it in. A development shop is a normal Shopware installation with debug features switched on, a database you can break freely and a way to rebuild the administration and storefront quickly. This lesson walks through the choices and the commands. As in the rest of the track, the real commands appear in read-only blocks (they need a machine with PHP, a database and Node), and a runnable stand-in at the end checks an environment against a requirements list.

Version numbers move quickly. Instead of memorising them, learn where to look: the require section of Shopware's composer.json, which Composer enforces, and the official system-requirements page for the version you target.

Choose how to run it

There are three common setups:

  1. A ready-made Docker image for development. The community project dockware publishes images with PHP, a web server, MySQL, Node, Xdebug and the Shopware tools already installed. You start a container and open the shop in the browser. This is the fastest start.
  2. The official project template with a Docker or devenv setup. Shopware's production template (the Composer project you will create below) ships with tooling for running the shop in containers or with a Nix-based development environment. Read the README of the template version you install, because this part changes between releases.
  3. A native stack. PHP with the required extensions, MySQL or MariaDB, and Node on your own computer (Laravel Herd, XAMPP, a Linux package set). This works well if you already have such a stack, but you are responsible for matching versions and extensions.

Whichever you choose, the commands from the next sections are the same; the only difference is whether you type them inside a container or on your machine.

flowchart LR
    A["Pick PHP + DB + Node<br/>(Docker or native)"] --> B["composer create-project<br/>shopware/production"]
    B --> C["bin/console system:install"]
    C --> D["Open /admin<br/>and the storefront"]
    D --> E["Add your plugin<br/>under custom/plugins"]

From an empty folder to a shop that is ready for a plugin.

Requirements to check

Recent Shopware 6 versions need:

  • A supported PHP version. Newer Shopware releases require newer PHP; the project's composer.json states the exact range.
  • PHP extensions such as ctype, curl, dom, fileinfo, gd, iconv, intl, json, mbstring, openssl, pdo_mysql, simplexml, xml, zip and zlib. Composer refuses to install if one is missing, and the message names it.
  • A database server, MySQL or MariaDB in a version the release supports.
  • Node.js and npm to build the administration and the storefront. Without them the shop installs but the front end assets cannot be rebuilt.
  • Composer 2.
  • Enough PHP memory for the admin build and for Composer (a memory_limit of 512 MB is a comfortable starting point on development machines).

Run php -v, php -m, composer -V and node -v before you install. Five seconds of checking saves an hour of puzzling over a half-finished install.

Create the project

Shopware recommends installing through its production template with Composer. The folder name is yours:

Terminal
composer create-project shopware/production my-shop
cd my-shop

This creates a Symfony-style project with composer.json, bin/console, config/, custom/ (where plugins and apps live), public/ and var/. The shop itself is in vendor/shopware, and you rarely edit it.

Configuration comes from environment variables. In development the important ones are in .env (or .env.local, which you should keep out of version control):

Terminal
APP_ENV=dev
APP_SECRET=change-me-in-real-life
APP_URL=http://localhost:8000
DATABASE_URL=mysql://root:root@127.0.0.1:3306/shopware

Check the template's own .env for the exact variable list, because the template may be set up differently from this example (some templates generate the file for you).

Install the shop

The system:install command prepares the database and basic data:

Terminal
bin/console system:install --create-database --basic-setup

--create-database creates the schema if it does not exist, and --basic-setup creates a default administrator, a first sales channel and basic data. It prints the credentials it created. On a development machine these default credentials are fine; never leave them on a public server. If you want to look at all options, run bin/console system:install --help.

Then start a web server. If you use dockware or the template's tooling, a server is already running. With a native setup you can point Apache or nginx at the public/ folder, or use Symfony's local web server if you have it. The two addresses you care about:

URL What you see
/ The storefront
/admin The administration login

Debug mode and caches

In APP_ENV=dev Symfony shows detailed error pages, writes more logs to var/log/ and recompiles parts of the container when files change. Many Shopware caches still need an explicit clear after certain changes:

Terminal
bin/console cache:clear

You will run this after changing services.xml, config.xml, routes and similar files. If a change "does not work", clearing the cache is the first thing to try.

A few bin/console commands to know right away:

Terminal
bin/console list                 # every command, grouped by namespace
bin/console list plugin          # only the plugin: commands
bin/console plugin:list          # known plugins and their state
bin/console debug:container      # services (Symfony)
bin/console debug:router         # routes (Symfony)

The console is a regular Symfony console, so Console Commands explains the mechanics in depth.

Building the front ends

The administration and the storefront both have JavaScript and SCSS that is compiled by tools. In production you build once. In development you run watch scripts that rebuild when you save a file and refresh the browser. The Shopware template provides helper scripts for this (exposed as Composer scripts in recent templates, shell scripts in bin/ in older ones; look at the scripts section of your composer.json). The usual pairs are:

  • build everything once, for a quick check or a deployment: a build:js style script;
  • watch the administration while you develop an admin module;
  • watch the storefront while you develop templates, styles or JavaScript.

The storefront watcher typically runs on its own port and proxies your shop. Use the address it prints, not the plain one, to get live reload. We use these scripts in The Administration at a Glance and Styling and JavaScript in the Storefront.

Check the environment in code

The two stand-ins below imitate what Composer does when you install: they compare a machine's facts to a requirements list. The first uses version_compare, and the second checks for missing PHP extensions. The numbers here are example values chosen for the demonstration, not Shopware's official requirements.

PHP A requirements checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Missing PHP extensions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Real: php -m, Composer's platform checks and the extension names. Stand-in: the hard-coded requirement and machine tables.

Habits that save time

  • Keep the shop in version control, but only your own plugin folders under custom/plugins need to be tracked if the project is a throwaway sandbox.
  • Create one sandbox shop for experiments and delete it freely; use a separate one for client work.
  • Read var/log/ when something fails quietly. Most background problems are logged there.
  • Update the template deliberately. A shop that jumps between major versions while you develop makes it hard to tell your bug from theirs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command prepares the database and basic data of a new Shopware shop?

    system:install creates the schema and, with --basic-setup, a default administrator and sales channel. cache:clear only clears caches.
  2. 2. Where do you place plugins in a project created from the production template?

    The custom folder is reserved for your own plugins and apps; vendor and var are managed by Composer and the framework.
  3. 3. Why do you need Node.js in a development environment?

    PHP serves the shop, but the Vue administration and the storefront JavaScript and SCSS are compiled with Node-based tools.
  4. 4. You changed a services.xml file and nothing happens. What is a sensible first step?

    Container configuration is compiled and cached, so a cache clear is the usual first step after changing service definitions.

Summary

  • Pick a setup: a ready-made development Docker image, the official template's tooling, or a native stack; the commands are the same.
  • Check PHP, PHP extensions, Node, Composer and the database version against the release you install.
  • composer create-project shopware/production makes the project, and bin/console system:install --create-database --basic-setup prepares the shop.
  • Use APP_ENV=dev, read var/log/, and run bin/console cache:clear after config changes.
  • Watch scripts rebuild the administration and storefront while you work; their exact names depend on the template version.
  • The requirement checkers here are stand-ins that use example numbers.

Next: Your First Plugin