Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
169 lines (119 loc) · 7.41 KB

CONTRIBUTING.md

File metadata and controls

169 lines (119 loc) · 7.41 KB

Get involved

Shopware is available under the MIT license. If you want to contribute code (features or bug fixes), you have to create a pull request and include valid license information. Contribute your code under the MIT license.

If you want more details about available licensing or the contribution agreements we offer, you can contact us at contact@shopware.com.

Contributing to the Shopware code base

If you want to learn how to contribute code to Shopware, please refer to Contributing Code. Also, make sure that if you change something in a manner that is relevant to external developers please describe your change in a meaningful way. For more information refer to this document.

Local Docker Setup

The repository contains a Docker setup to run the application locally.

Checkout the repository and navigate to the directory. To start the containers run:

docker compose up -d

When the containers have started successfully you can call commands inside the container by adding docker compose exec web as a prefix to your command. You can now build Shopware by runnning:

docker compose exec web composer setup

This will download the necessary dependencies and set up the environment for development. After the setup is complete, you can access the application at http://localhost:8000.

The Administration can be accessed at http://localhost:8000/admin and the Username is admin with the Password shopware.

To run the Administration Watcher you can use:

docker compose exec web composer watch:admin

The watched Administration is available at http://localhost:5173.

To run the Storefront Watcher you can use:

docker compose exec web composer watch:storefront

The watched Storefront is available at http://localhost:9998.

To access the database you can go to http://localhost:9080 and use the following credentials:

  • Server: database
  • Username: root
  • Password: root

Configuring PHPStorm to Run in Docker

In PHPStorm you need to create a new PHP Interpreter from Docker Compose and select the web service. Make sure you set the Lifecycle to Connect to existing container to speed up test execution.

Running tools

You will need to prepend to all commands docker compose exec web to run the commands in the container. For example:

docker compose exec web composer setup

For all commands see Command Overview.

Using Dev Containers in VS Code

If you are using VS Code or other IDEs based on VS Code, like Cursor AI, you can use the Dev Containers feature to access the container with your IDE to get full terminal support and other improvements.

Usage

  • Make sure to install the Dev Containers extension in VS Code.
  • Open the repository in your IDE.
  • From the VS Code command palette (Ctrl + Shift + P), enter: Dev Containers: Reopen in Container.

The IDE should now restart the window with your environment set up for editing right within the container. It will also start the Docker container if you haven't done yet, so everytime you reopen the project as the container setup, the container will start automatically. The terminal and other tools, such as agent commands in Cursor, will now use the correct shell of the container. Also, PHP tools and other extensions should be set up for optimized use with Shopware.

Changing environment variables

You can create a .env file to override the default environment variables. These are loaded automatically without having to restart the containers. Except for the APP_ENV variable, which requires docker compose up -d to apply the changes.

Enable Profiler/Debugging for PHP

To enable XDebug, you will need to create a compose.override.yaml

services:
    web:
        environment:
            - XDEBUG_MODE=debug
            - XDEBUG_CONFIG=client_host=host.docker.internal
            - PHP_PROFILER=xdebug

and then run docker compose up -d to apply the changes.

It also supports blackfire, tideways and pcov. For tideways and blackfire you will need a separate container like:

services:
    web:
        environment:
            - PHP_PROFILER=blackfire
    blackfire:
        image: blackfire/blackfire:2
        environment:
            BLACKFIRE_SERVER_ID: XXXX
            BLACKFIRE_SERVER_TOKEN: XXXX

Using OrbStack Routing

Instead of using regular ports, you can also use the OrbStack URL generation feature. OrbStack generates for each running container a URL like https://web.orb.local and allows for easier access to your services without needing to manage port mappings. This allows running multiple Shopware instances at the same time without port conflicts.

Create a compose.override.yaml with:

services:
    web:
        ports: !override []
        environment:
            APP_URL: https://web.sw-trunk.orb.local
            SYMFONY_TRUSTED_PROXIES: 'private_ranges'
    database:
        ports: !override []
    adminer:
        ports: !override []
    valkey:
        ports: !override []
    mailer:
        ports: !override []
    opensearch:
        ports: !override []

The APP_URL environment variable always starts with web.<project-name>.orb.local and the rest of the URL is generated by the project name. The project name is the folder name of the project. So if you have a project called shopware, the URL will be https://web.shopware.orb.local. If you have a project called shopware-6, the URL will be https://web.shopware-6.orb.local.

You can also open https://orb.local in your browser and see all running containers and their URLs.

The SYMFONY_TRUSTED_PROXIES setting is required to access Shopware via HTTPS using OrbStack's .orb.local domains.

To run the Storefront Watcher you will need to set an additional PROXY_URL environment variable. This is needed to make the watcher work with the OrbStack routing.

docker compose run --rm -p 9998:9998 -p 9999:9999 -e PROXY_URL=http://localhost web composer watch:storefront

and for the admin watcher accordingly:

docker compose run --rm -p 5173:5173 -e PROXY_URL=http://localhost web composer watch:admin

Command Overview

  • composer phpstan to run PHPStan
  • composer ecs-fix to run PHP CS
  • composer storefront:unit to run Jest for the Storefront
  • composer admin:unit to run Jest for the Administration
  • composer stylelint:storefront:fix to run Stylelint for the Storefront
  • composer stylelint:admin:fix to run Stylelint for the Administration
  • composer eslint:storefront to run ESLint for the Storefront
  • composer eslint:admin to run ESLint for the Administration

Documentation

Developer documentation for Shopware is available here. You can also contribute to the documentation by submitting your pull requests to this repository.

Translations

Shopware translations are done by the community and can be installed from the plugin store. If you wish to improve Shopware's translations, you can do so in our Crowdin project page.