diff --git a/guides/hosting/index.md b/guides/hosting/index.md index 4572d28d1..d9c32c79d 100644 --- a/guides/hosting/index.md +++ b/guides/hosting/index.md @@ -8,3 +8,36 @@ nav: # Hosting Setting up an operating environment for Shopware can be hard, but it doesn't have to be if you follow some general guidelines in the subsequent sections. + +## Recommended stack and supported versions + +The following versions and configurations are officially supported for Shopware 6 development: + +| Component | Install | Minimum Version | Recommended | Required / Notes | +|:---------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------|:-------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **PHP** | [PHP installation guide](https://www.php.net/manual/en/install.php)
[Composer installation guide](https://getcomposer.org/download/) | 8.2+ | 8.4 | **Required.**
`memory_limit ≥ 512M`, `max_execution_time ≥ 30s`.
Required extensions: `ctype`, `curl`, `dom`, `fileinfo`, `gd`, `iconv`, `intl`, `mbstring`, `openssl`, `pcre`, `pdo_mysql`, `phar`, `simplexml`, `xml`, `zip`, `zlib`.
Optional: `amqp` (for message queues).
Composer 2.2+ recommended.
**macOS note:** If you install PHP with Homebrew, the `intl` extension may not be included by default. Install it separately:
`brew install php-intl` then verify with `php -m | grep intl`. | +| **SQL** | [MariaDB installation guide](https://mariadb.com/kb/en/getting-installing-and-upgrading-mariadb/)
[MySQL installation guide](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/) | MariaDB ≥ 10.11.6 or MySQL ≥ 8.0.22 | MariaDB 11.4 / MySQL 8.4 | **Required.**
`max_allowed_packet ≥ 32M` for optimal performance. | +| **Node.js / npm** | [Node.js downloads](https://nodejs.org/en/download) | Node 20.0.0+ | Node 24 / npm 10 | **Required.** | +| **Search** | [OpenSearch installation guide](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/index/) | OpenSearch 1.0+ or ElasticSearch 7.8+ | OpenSearch 2.17.1 | **Optional.** Used for product search and indexing.
**Note**: The search preview in the administration requires OpenSearch 2.12+ or Elasticsearch 8.8+.
Support for OpenSearch 3.1 was added in shopware v6.7.3.1 | +| **Cache / KV store** | [Valkey](https://valkey.io/)
[Redis](https://redis.io) / [Redict](https://redict.io) / [Dragonfly](https://www.dragonflydb.io) | Redis v7+ | Valkey 8.0 | **Optional.** Used for caching and session storage.
Redis-protocol compatible alternatives supported.
`maxmemory-policy: volatile-lfu`. | +| **Web server** | [Caddy setup guide](https://developer.shopware.com/docs/resources/references/config-reference/server/caddy.html)
[Apache](https://developer.shopware.com/docs/resources/references/config-reference/server/apache.html)
[Nginx](https://developer.shopware.com/docs/resources/references/config-reference/server/nginx.html) | Any | Caddy | **Required.** For local development, the [Symfony CLI server](https://symfony.com/doc/current/setup/symfony_cli.html) works out of the box. | +| **Queue** | [RabbitMQ downloads](https://www.rabbitmq.com/download.html)
[AWS SQS](https://aws.amazon.com/sqs/) | Any transport supported by the [symfony messenger component](https://symfony.com/doc/current/messenger.html#transport-configuration) | RabbitMQ | **Optional.** By default the SQL database will be used as a queue, however in production setups it is highly recommended to use a dedicated queue system for scalability and observability reasons. | + +See also: [PHP performance tweaks guide](https://developer.shopware.com/docs/guides/hosting/performance/performance-tweaks.html#php-config-tweaks) + +## Verifying your local environment + +Use the following commands to verify your local environment: + +::: info +On many systems or hosting environments, multiple PHP versions may be installed. +Make sure to use the correct PHP binary, as CLI and FPM often have different `php.ini` files. +Ask your hosting provider for the correct PHP binary and how to adjust `php.ini`. +::: + +- `php -v`: Show CLI PHP version +- `php -m`: List CLI PHP modules +- `php -i | grep memory_limit`: Show your CLI PHP memory limit +- `composer -V`: Show Composer version +- `node -v`: Show Node version +- `npm -v`: Show npm version diff --git a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md index 1ced473cc..08e4ec94f 100644 --- a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md +++ b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md @@ -19,7 +19,7 @@ Currently, the implementation for Elasticsearch/Opensearch works in the same way * A supported OpenSearch (or Elasticsearch) server - + * [Running message queue workers in the background](../message-queue) diff --git a/guides/installation/setups/docker-options.md b/guides/installation/advanced-options.md similarity index 56% rename from guides/installation/setups/docker-options.md rename to guides/installation/advanced-options.md index 2835078d0..4f64eb40a 100644 --- a/guides/installation/setups/docker-options.md +++ b/guides/installation/advanced-options.md @@ -1,95 +1,50 @@ --- nav: - title: Additional Docker Options - position: 40 + title: Advanced Options + position: 6 --- -# Additional Docker Options +# Advanced options -## Connecting to a remote database +This page covers optional and advanced Docker configuration for Shopware projects. You can refer to information here once your local environment is running and you want to customize your environment, mirror production more closely, or support advanced workflows. -If you want to use a database outside the Docker stack (running on your host or another server, for examples), set `DATABASE_URL` in `.env.local` in the standard form: +## Customizing the runtime environment -```bash -DATABASE_URL="mysql://user:password@:3306/" -``` - -Note: containers cannot always reach services bound only to the host's `localhost`. If `localhost` does not work you can try `host.docker.internal`, your host machine’s LAN IP, or add an `extra_hosts` entry in `compose.yaml`. - -## Enable profiler/debugging for PHP - -Once your Shopware environment is running, you may want to enable PHP debugging or profiling to inspect code execution, set breakpoints, or measure performance. The default setup doesn’t include these tools, but you can enable them using Docker overrides. - -### Enable Xdebug - -To enable [Xdebug](https://xdebug.org/) inside the web container, create a `compose.override.yaml` in your project root with the following configuration: - -```yaml -services: - web: - environment: - - XDEBUG_MODE=debug - - XDEBUG_CONFIG=client_host=host.docker.internal - - PHP_PROFILER=xdebug -``` - -After saving the file, apply the changes: - -```bash -docker compose up -d -``` - -This restarts the containers with Xdebug enabled. You can now attach your IDE (for example, PHPStorm or VS Code) to the remote debugger on the default Xdebug port `9003`. +### Image variations -Shopware’s Docker setup also supports other profilers, like [Blackfire](https://www.blackfire.io/), [Tideways](https://tideways.com/), and [PCOV](https://github.com/krakjoe/pcov). For Tideways and Blackfire, you'll need to run an additional container. For example: - -```yaml -services: - web: - environment: - - PHP_PROFILER=blackfire - blackfire: - image: blackfire/blackfire:2 - environment: - BLACKFIRE_SERVER_ID: XXXX - BLACKFIRE_SERVER_TOKEN: XXXX -``` +Shopware provides multiple Docker image variants so you can match your local setup to your project's PHP version, Node version, and preferred web server. The image tag format is `ghcr.io/shopware/docker-dev:php(PHP_VERSION)-node(NODE_VERSION)-(WEBSERVER)`. -## Image variations +Version matrix: -The Shopware Docker image is available in several variations, allowing you to match your local setup to your project’s PHP version, Node version, and preferred web server. Use the following pattern to select the right image tag: - -`ghcr.io/shopware/docker-dev:php(PHP_VERSION)-node(NODE_VERSION)-(WEBSERVER)` - -Here’s the version matrix: - -PHP versions: +PHP versions - `8.4` - PHP 8.4 - `8.3` - PHP 8.3 - `8.2` - PHP 8.2 -Node versions: +Node versions - `node24` - Node 24 - `node22` - Node 22 -Web server: +Web server - `caddy` - Caddy as web server - `nginx` - Nginx as web server -Example: +Examples - `ghcr.io/shopware/docker-dev:php8.4-node24-caddy` - PHP 8.4, Node 24, Caddy as web server - `ghcr.io/shopware/docker-dev:php8.3-node24-caddy` - PHP 8.3, Node 24, Caddy as web server - `ghcr.io/shopware/docker-dev:php8.4-node22-nginx` - PHP 8.4, Node 22, Nginx as web server - `ghcr.io/shopware/docker-dev:php8.3-node22-nginx` - PHP 8.3, Node 22, Nginx as web server -## Adding Minio for local S3 storage +Choose the variant that best matches your production stack. + +## Adding S3-compatible storage (Minio) -Some projects use Amazon S3 for file storage in production. If you want to mimic that behavior locally—for example, to test uploads or CDN-like delivery—you can add [Minio](https://www.min.io/), an open-source S3-compatible storage server. +Some projects use Amazon S3 for file storage in production. If you want to mimic that behavior locally—for example, to test uploads or CDN-like delivery—you can add [Minio](https://www.min.io/), which is an open-source, S3-compatible storage server. ### 1. Add the Minio service @@ -139,7 +94,7 @@ volumes: ### 2. Configure Shopware to use Minio -Create a new YAML file at `config/packages/minio.yaml` with the following content: +Create a `config/packages/minio.yaml`: ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/shopware/shopware/refs/heads/trunk/config-schema.json @@ -186,8 +141,7 @@ bin/console theme:compile ## Using OrbStack routing -If you're using [OrbStack](https://orbstack.dev) on macOS, you can take advantage of its built-in routing feature. -OrbStack automatically assigns local `.orb.local` URLs to your containers, so you don’t need to manage port mappings manually. This allows running multiple Shopware instances at the same time without port conflicts. +If you're using [OrbStack](https://orbstack.dev) on macOS, you can avoid manual port management by using its built-in routing feature. OrbStack automatically assigns local `.orb.local` URLs to your containers, which allows running multiple Shopware instances at the same time without port conflicts. To enable it, create a `compose.override.yaml` in your project root with the following content: @@ -213,16 +167,11 @@ The APP_URL environment variable follows this pattern: `web..orb.l You can also open `https://orb.local` in your browser to view all running containers and their assigned URLs. -## Proxy production images +## Working with production data locally -When you import a production database into your local environment, image URLs in the data may still point to production servers. As a result, your local store might show broken or missing images. You can fix this in two ways: +When importing production databases into your local environment, image URLs in the data may still point to production servers—leading to broken or missing images in your local store. You can proxy those images locally instead of downloading everything. -- **download all production images** and import them locally, or -- **set up a lightweight proxy service** that serves those images directly from the production server (recommended for quick testing). - -### 1. Add the image proxy service - -Add a `imageproxy` service to your `compose.override.yaml`: +Add the `imageproxy` service to your `compose.override.yaml`: ```yaml services: @@ -237,9 +186,7 @@ services: This starts a proxy server that fetches images from the production environment and caches them locally. For example, a request to `http://localhost:8050/assets/images.png` will be served from `https://[REMOTE_SERVER_HOST]/assets/images.png` and then stored in the local cache for faster reuse. -### 2. Point Shopware to the proxy - -Next, we need to configure Shopware to use the proxy server. To do this, create a new YAML file `config/packages/media-proxy.yaml` +Next, configure Shopware to use the proxy server. Create a new YAML file `config/packages/media-proxy.yaml`: ```yaml shopware: @@ -248,4 +195,4 @@ shopware: url: "http://localhost:8050" ``` -This tells Shopware to use the proxy server URL for all images. +Images are fetched from production on demand and cached locally. diff --git a/guides/installation/after-installation.md b/guides/installation/after-installation.md new file mode 100644 index 000000000..c94dd08af --- /dev/null +++ b/guides/installation/after-installation.md @@ -0,0 +1,237 @@ +--- +nav: + title: After installation + position: 5 + +--- + +# After installation + +You now have a running Shopware instance. This page explains what you typically do next, in the order most developers need it. + +## Start developing + +### Administration & Storefront + +- Storefront: [http://localhost:8000](http://localhost:8000) +- Administration: [http://localhost:8000/admin](http://localhost:8000/admin) *(default credentials: `admin` / `shopware`)* + +Most day-to-day work happens in: + +- `custom/`: your plugins and themes +- `bin/console`: application CLI (Symfony console) +- the Administration UI + +### Using the Shopware CLI + +To run CLI commands, open a shell inside the web container: + +```bash +make shell +``` + +This command drops you into the container’s terminal (you’ll see the prompt change). + +From inside the container, use: + +```bash +bin/console +``` + +Development and automation tasks are handled in the CLI, including: + +- installing and activating plugins +- clearing caches +- running migrations +- adjusting system configuration +- developing plugins and themes + +**Tip**: Inside the container, you only need `bin/console …`. But if you prefer to run commands from your host machine instead, you can use the full Docker prefix: `docker compose exec web bin/console cache:clear`. + +Please note that some setup tasks are done in the Administration UI, including: + +- Opening the **Admin** at +- Signing in or creating a Shopware account; necessary when you want to install Store extensions. +- Connecting to the **Shopware Store** +- Installing plugins or themes from the Store +- Connecting payment methods; not necessary for local development + +Basic shop settings such as shop name, default language, and currency can be changed later in the Admin under **Settings > Shop > Basic information**. + +## Frontend and Administration development + +When you modify Storefront or Administration code, or develop plugins that affect the UI, you’ll use these Makefile commands: + +```bash +# Build the administration (admin panel) +make build-administration + +# Build the storefront (shop frontend) +make build-storefront + +# Start a watcher to rebuild the Administration automatically when files change +make watch-admin + +# Start a watcher for Storefront +make watch-storefront +``` + +These will become part of your everyday development workflow. Watchers are typically used during active UI development. + +## Inspecting and debugging locally + +If you connect to the database from your host machine—for example, via Adminer or a local MySQL client—use `127.0.0.1` or `localhost` and the exposed port shown in `docker compose ps`. + +## Local services overview + +With Shopware running, your local setup includes a web service that serves both the storefront and the Administration. By default this uses Caddy with PHP-FPM, but you may use Nginx instead. Knowing which service does what helps when debugging or connecting external tools. + +### Accessing services + +Your local stack includes: + +- Database (MariaDB): runs on port 3306 inside Docker. + - Internal hostname: `database` + - Host access: `localhost:3306`, if you want to inspect the database directly. +- Mailpit local mail testing tool: available at [http://localhost:8025](http://localhost:8025). Use this to view emails sent by Shopware (e.g., registration or order confirmations) without needing an external mail server. +- Adminer (database UI): Lightweight web interface for viewing and editing your database, available at [http://localhost:8080](http://localhost:8080). + +Inspect ports and services with: + +```bash +docker compose ps +``` + +### Enable profiler/debugging for PHP + +Once your Shopware environment is running, you may want to enable PHP debugging or profiling to inspect code execution, set breakpoints, or measure performance. The default setup doesn’t include these tools, but you can enable them using Docker overrides. + +As an example, enable [Xdebug](https://xdebug.org/) inside the web container by creating a `compose.override.yaml` in your project root with the following configuration: + +```yaml +services: + web: + environment: + - XDEBUG_MODE=debug + - XDEBUG_CONFIG=client_host=host.docker.internal + - PHP_PROFILER=xdebug +``` + +Save the file and apply the changes: + +```bash +docker compose up -d +``` + +This restarts the containers with Xdebug enabled. You can now attach your IDE (for example, PHPStorm or VS Code) to the remote debugger on the default Xdebug port `9003`. + +Shopware’s Docker setup also supports other profilers, like [Blackfire](https://www.blackfire.io/), [Tideways](https://tideways.com/), and [PCOV](https://github.com/krakjoe/pcov). For Tideways and Blackfire, you'll need to run an additional container. For example: + +```yaml +services: + web: + environment: + - PHP_PROFILER=blackfire + blackfire: + image: blackfire/blackfire:2 + environment: + BLACKFIRE_SERVER_ID: XXXX + BLACKFIRE_SERVER_TOKEN: XXXX +``` + +## Adjusting your local environment + +### Environment variables + +You can create a `.env` file in the project root to override default environment variables. Most changes take effect automatically without restarting containers. Changes to `APP_ENV` require a restart: + +```bash +make up +``` + +### Docker overrides + +Use `compose.override.yaml` to: + +- change ports +- add services +- enable debugging +- adjust networking + +This keeps your changes local and out of version control. + +## Working with data & external systems + +### Store API access key + +During setup, an access key is automatically generated for your default Sales Channel, which is usually the Storefront. You’ll see an output similar to this: + +```bash +Access tokens: ++------------+----------------------------+ +| Key | Value | ++------------+----------------------------+ +| Access key | `string of capital letters` | +``` + +The access key for authenticating requests to the [Store API](../../../concepts/api/store-api)—for example, when fetching product or category data from an external app, headless storefront, or API client. Example usage: + +```bash +curl -H "sw-access-key: YOUR_ACCESS_KEY" \ + http://localhost:8000/store-api/product +``` + +You can view or regenerate this key in the Admin under Sales Channels → [Your Channel] → API Access. + +## Connecting to a remote database + +If you want to use a database outside the Docker stack, set `DATABASE_URL` in `.env.local` in the standard form: + +```bash +DATABASE_URL="mysql://user:password@:3306/" +``` + +Containers cannot always reach services bound only to the host's `localhost`. If `localhost` does not work, try `host.docker.internal` or your host machine’s LAN IP, or add an `extra_hosts` entry in `compose.yaml`. + +## Running and maintaining the environment + +### Linux file permissions and known issues + +On Linux hosts, your user ID must be 1000 for file permissions to work correctly inside the containers. Check your user ID with: + +```bash +id -u +``` + +Other IDs may cause permission errors when running `make up` or writing to project files. + +## Preparing for production + +If you're preparing to run Shopware in production using Docker, [this page](../../hosting/installation-updates/docker.md) covers production images, environment configuration, and deployment workflows. + +## Build and Watch the Administration and Storefront + +You only need to run this step if you’re developing or customizing the frontend (Administration or Storefront). It compiles JavaScript and CSS assets so your changes are visible immediately. + +The created project contains Bash scripts in the `bin/` folder to build and watch the Administration and Storefront. Run the following commands: + +```bash +./bin/build-administration.sh +./bin/build-storefront.sh +./bin/watch-administration.sh +./bin/watch-storefront.sh +``` + +Use these scripts to build the Administration and Storefront. The `watch` commands will watch for changes in the Administration and Storefront and rebuild them automatically. + +## Advanced Docker configuration + +For advanced topics like: + +- image variants +- Minio (S3) +- OrbStack routing +- production image proxy configuration +- service internals + +see [Advanced Options](advanced-options.md) diff --git a/guides/installation/docker-setup.md b/guides/installation/docker-setup.md new file mode 100644 index 000000000..a6ebf7681 --- /dev/null +++ b/guides/installation/docker-setup.md @@ -0,0 +1,130 @@ +--- +nav: + title: Docker Setup + position: 3 + +--- + +# Docker Setup + +This guide is for developing Shopware stores and extensions. By the end of this section, you will have an empty *running* Shopware instance and can immediately start developing. + +:::info +For information about using Docker in production, see [Docker for production](../../hosting/installation-updates/docker.md). To contribute to the Shopware platform itself, visit the [Contributing.md guide](https://github.com/shopware/shopware/blob/trunk/CONTRIBUTING.md). +::: + +## Prerequisites + +- Install and run either [Docker](https://docs.docker.com/get-started/get-docker/) or [OrbStack](https://docs.orbstack.dev/quick-start). OrbStack is a fast, Docker-compatible alternative for macOS (free for personal use). +- Ensure Docker has permission to bind to local ports (typically `:80` or `:8080`) and that no conflicting services are already using these ports. +- Install `make`: + +```bash +# Ubuntu +apt install make + +# macOS +brew install make + +This Docker setup includes the [Shopware CLI](../../../products/cli/index.md), which helps build, refactor, validate, and manage Shopware projects and extensions. It works with all setups and is used in most Shopware upgrade, build, and CI workflows. The CLI is available in the container shell. + +## Pre-pull the image (optional) + +If you haven’t yet downloaded the Shopware Docker image, pull it now: + +```bash +docker pull ghcr.io/shopware/docker-dev:php8.3-node24-caddy +``` + +If you skip this step, Docker will automatically download the image during project creation. That’s normal, but pre-pulling makes the process cleaner and enables you to avoid waiting for large image downloads. + +## Create a new Shopware project + +Create an empty directory for your project and navigate to it: + +```bash +mkdir my-project && cd my-project +`` + +Create a new project: + +```bash +docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup +``` + +To use a specific version of Shopware (optional), run: + +```bash +docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup 6.6.10.0 +``` + +This step creates your Shopware project using PHP and Composer inside the Docker image. It generates a ready-to-use setup including `compose.yaml` and a `Makefile`, so you don’t need to locally install PHP or Composer yourself. + +:::info +The Docker setup installs development dependencies (`require-dev`) and [`shopware/dev-tools`](https://github.com/shopware/dev-tools). This enables the Symfony profiler, [demo data](https://github.com/shopware/SwagPlatformDemoData), linting tools, and test tooling. +::: + +Project creation takes a few minutes to complete. When prompted in the terminal, you will see: + +`Do you want to use Elasticsearch? (y/N)` + +Shopware supports an Elasticsearch-compatible search engine for improved performance with large catalogs and advanced search features. + +If you choose `y`, the Docker setup starts an Elasticsearch-compatible search service (OpenSearch) as part of your stack. + +If you choose `N`, Shopware will use MariaDB for search, which is sufficient for local testing or small datasets. + +## Initial setup + +After creating your project, you must install Shopware inside your containers. Run the setup commands below to initialize the database, generate configuration files, and create the default admin user. + +First, start the containers: + +```bash +make up +``` + +This command starts Shopware and all required services (web server, database, search, Mailpit, etc.) in the background. Docker images already include all required PHP extensions and services, so the system-check step of the installer is always fulfilled. + +:::info +You can check the container status anytime with the below command: +::: + +```bash +docker compose ps +``` + +“Healthy” means the service passed its internal health check and is ready to use. + +Once the containers are running, install Shopware with this command: + +```bash +make setup +``` + +:::info +What happens during `make setup`: + +- The Makefile runs the Shopware installer inside the web container +- Shopware is installed automatically (no browser wizard required) +- A MariaDB database is created +- An admin user is created, with username `admin` and password `shopware` +- Required services (database, search, mail, etc.) are preconfigured and runs inside the Docker +- The Shopware project is configured to connect to the database via the Docker service name `database` +- Database credentials are defined in the `compose.yaml` +- If search was enabled during project creation, an Elasticsearch-compatible search service runs as part of the Docker stack +::: + +Verify that the installation completed successfully by opening . + +Use the following commands to manage the development environment: + +```bash +# Start the environment +make up + +# Stop the environment +make down + +# Fully reset the environment ( "-v" flag removes containers, networks, and volumes - all stored data will be lost) +docker compose down -v diff --git a/guides/installation/hardware-requirements.md b/guides/installation/hardware-requirements.md new file mode 100644 index 000000000..ec0bd865f --- /dev/null +++ b/guides/installation/hardware-requirements.md @@ -0,0 +1,35 @@ +--- +nav: + title: Hardware Requirements + position: 2 + +--- + +# Hardware Requirements + +Before setting up the Shopware 6 development environment, ensure your system meets the following basic requirements. + +- Unix-based system (macOS or Linux), or Windows with WSL 2 or Docker for full compatibility +- Administrative/root privileges (if required within the organization) +- At least 8 GB RAM (16 GB recommended) and 10 GB free disk space +- Reliable internet connection for dependency downloads + +## System requirements + +| Component | Recommended | +|:---------------------|:-------------------------------------------------------------| +| **CPU** | Quad-core or higher | +| **Memory (RAM)** | 8 GB minimum, 16 GB recommended (especially for Docker) | +| **Disk space** | ~10 GB free for Shopware + services | +| **Operating system** | macOS 13+, Windows 10/11 (Pro with WSL 2), or Linux (64-bit) | + +## Permissions and networking + +- Allow your system’s firewall to let containers or local web servers communicate internally. +- On Linux, you may need to add your user to the `docker` group using the below command: + +```bash +sudo usermod -aG docker $USER +``` + +Once your environment meets these requirements, proceed to [setup](./docker-setup.md). diff --git a/guides/installation/index.md b/guides/installation/index.md deleted file mode 100644 index 05292d81a..000000000 --- a/guides/installation/index.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -nav: - title: Installation - position: 10 - ---- - -# Overview — Shopware 6 Installation - -Welcome to the Shopware 6 Developer Installation Guide, which will help you set up a local Shopware 6 development environment whether you’re: - -- building a custom shop project -- developing a plugin, app, or theme -- contributing to the Shopware core - -You can choose from three supported setup options, each designed for specific use cases and development workflows. All setups start from the [Shopware Project Template](./template.md). - -## Shopware project template - -Every setup begins with the Project Template. It creates a new Composer project that includes Shopware as a dependency, allowing you to: - -- Extend the project with plugins, apps, or themes -- Customize configurations and services -- Align the environment with your development goals - -If you have downloaded the [shopware-installer.phar package](https://www.shopware.com/en/download/) instead of using Composer, skip the `composer create-project` step and follow the remaining instructions from the [Project Template](https://developer.shopware.com/docs/guides/installation/template.html) guide. - -## Supported setups - -| Setup | Description | Recommended For | -|:---------------------------------------------|:--------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------| -| [Docker Setup](./setups/docker.md) | A complete, containerized environment including all required services (database, search engine, cache, etc.). | Most developers — provides production-like conditions, consistent across teams and CI/CD. | -| [Symfony CLI Setup](./setups/symfony-cli.md) | Runs directly on your host system using local PHP and Composer. Lightweight and fast to start. | Quick plugin or theme development, or environments where Docker isn’t available. | -| [Devenv Setup](./setups/devenv.md) | A reproducible, Nix-based setup offering deterministic builds and cross-platform consistency. | Core contributors and advanced users managing multiple Shopware versions. | - -::: info -If you’re unsure which setup to choose, start with the Docker setup — it provides the smoothest onboarding experience. -::: diff --git a/guides/installation/installation-intro.md b/guides/installation/installation-intro.md new file mode 100644 index 000000000..752f807c8 --- /dev/null +++ b/guides/installation/installation-intro.md @@ -0,0 +1,48 @@ +--- +nav: + title: Shopware 6 Installation + position: 1 + +--- + +# Overview of Shopware 6 Installation + +Welcome to the Shopware 6 Developer Installation Guide, which will help you set up a local Shopware 6 development environment whether you’re: + +- building a custom shop project +- developing a plugin, app, or theme +- contributing to the Shopware core + +The Shopware 6 development environment is primarily supported and recommended to be used with [Docker](https://www.docker.com/). This platform enables developers to develop, ship, and run applications inside containers: lightweight, standalone, and executable packages. Docker enables production-like conditions consistent across teams and CI/CD, and makes it easy to reset or rebuild environments. Docker is especially useful when full service parity is required (e.g., caching, queues, search). + +The [Docker-based setup](./docker-setup.md) aims to provide a smooth onboarding experience aligned with modern development practices. It runs your entire Shopware environment in containers, including all backend services (PHP, MySQL, Node, an Elasticsearch-compatible search engine, Redis, Mailhog, etc.). No manual installation is required. + +The pages that follow assume that you're using Docker itself. + +The Shopware community has produced some related tooling for developers who prefer more automated or GUI-friendly ways to run Docker environments: [DDEV](#DDEV) and Dockware(#Dockware setup). Both are **community-maintained** and not officially supported by Shopware. + +## DDEV + +[DDEV](https://ddev.com/) is a developer-friendly wrapper around Docker that automates environment setup using simple CLI commands. Key features include: + +- Simplifies Docker configuration: no manual `docker-compose.yml` needed. +- One command (`ddev start`) to start your Shopware environment. +- Easy to switch PHP/MySQL/Node versions per project. +- Integrates well with VS Code and PHPStorm. + +For a DDEV-based Shopware example, see [DDEV with Shopware](https://github.com/ddev/test-shopware6) + +## Dockware + +[Dockware](https://www.dockware.io/) provides ready-to-run Docker images for quickly spinning up demo stores or full local environments in seconds. It emphasizes minimal setup over full customization. Key features include: + +- Pre-built images for Shopware 5, Shopware 6, and nightly builds. +- Includes all key services: PHP, DB, Elasticsearch, Mailhog, Adminer, etc. +- Great for testing specific versions or quick evaluation. +- Can be used standalone or integrated into CI pipelines. + +:::info +Looking for older installation methods that are no longer recommended? See our [Legacy Installation Guides](./legacy-setups/). +::: + +Next, check the [hardware requirements](./hardware-requirements.md) to prepare your system. diff --git a/guides/installation/project-overview.md b/guides/installation/project-overview.md new file mode 100644 index 000000000..b2d5bfcf7 --- /dev/null +++ b/guides/installation/project-overview.md @@ -0,0 +1,73 @@ +--- +nav: + title: Project overview + position: 4 + +--- + +# Understanding your Shopware project + +You’ve just installed Shopware. But what exactly did you get? This page is an explainer to guide you through fundamentals you'll use through the rest of your development workflow. + +## Development tooling included + +The Docker setup installs Shopware with development dependencies (`require-dev`) enabled, including: + +- [`shopware/dev-tools`](https://github.com/shopware/dev-tools) +- Symfony profiler +- [Demo data](https://github.com/shopware/SwagPlatformDemoData) +- Linting and testing tools + +Your local project is ready for debugging, profiling, and extension development out of the box. + +In day-to-day development, you’ll mostly interact with: + +- **Makefile**: shortcuts for Docker and Shopware commands (`make up`, `make setup`, etc.) +- **custom/**: where you build your own plugins and themes +- **bin/console**: the application CLI that ships with Shopware (Symfony console). It's used for tasks like running migrations, installing plugins, clearing caches, or managing configuration inside your project. + +Note: `bin/console` is different from the standalone [Shopware CLI](https://github.com/shopware/shopware-cli) tool used for extension builds and CI workflows. The Docker setup already includes the standalone Shopware CLI inside the container. + +Most other files in the project either configure the environment or support these core layers. + +## Project template + +All setups start from the Shopware Project Template: a Composer-based project that installs Shopware as a dependency. It serves as the foundation for new Shopware projects as well as for developing plugins, apps, or themes. This allows you to: + +- extend the project with plugins, apps, or themes +- customize configuration and services +- tailor the environment to your development needs + +### Components explained + +The following table explains the Docker-level components created when you start the project. Container names depend on your project folder name. + +| Name | Type | Purpose | +|---------------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| **Network `my-project_default`** | Docker network | A private virtual network so all containers can communicate (for example, the web container connects to the database). | +| **Volume `my-project_db-data`** | Persistent storage | Stores the MariaDB database files so your data isn’t lost when containers are stopped or rebuilt. | +| **Container `my-project-mailer-1`** | Mailpit service | Captures outgoing emails for local testing. View at [http://localhost:8025](http://localhost:8025). | +| **Container `my-project-database-1`** | MariaDB service | Runs the Shopware database. Inside the Docker network its host name is `database`. | +| **Container `my-project-web-1`** | PHP + Caddy web service | Runs Shopware itself and serves the storefront and Admin UI at [http://localhost:8000](http://localhost:8000). | +| **Container `my-project-adminer-1`** | Adminer (DB UI) | Lightweight web interface for viewing and editing your database. Available at [http://localhost:8080](http://localhost:8080). | + +### Project structure explained + +This table outlines the key directories and files in your Shopware project and what they are used for. + +| Item | Type | Purpose / what it contains | Notes | +|---------------------------|-----------------------------|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| +| **bin/** | Directory | Executable scripts (e.g., `bin/console` — the main CLI for Shopware/Symfony). | Think of it like `npm run` or `go run` scripts. Use `bin/console` to run commands inside the app. | +| **compose.yaml** | Docker | Defines the Docker services (web, database, mailpit, etc.). | Equivalent to your project’s “infrastructure recipe.” | +| **compose.override.yaml** | Docker | Local overrides for the default Docker Compose stack (e.g., port mappings, extra volumes). | Optional; used to customize or extend services locally. | +| **composer.json** | PHP dependency manifest | Lists PHP dependencies and metadata (like `package.json`). | `composer install` reads this. | +| **composer.lock** | Dependency lock file | Locks exact versions of PHP packages. | Don’t edit manually; committed to git. | +| **config/** | Directory | Symfony configuration files (framework, database, mail, etc.). | Similar to `config/` in many web frameworks. | +| **custom/** | Directory | Your plugins, themes, or app customizations. | This is where you add new extensions — your “src” for Shopware plugins. | +| **files/** | Directory | Uploaded media and temporary files. | Ignored by git; generated at runtime. | +| **Makefile** | Build helper | Shortcuts for Docker tasks (`make up`, `make setup`, etc.). | Replaces long Docker commands with memorable aliases. | +| **public/** | Web root | The actual web-server-accessible directory (contains `index.php`, assets, etc.). | Like `/dist` in JS frameworks or `/public_html`. | +| **src/** | Source code | Shopware’s core application source. | Where the main PHP codebase lives; not usually edited in a project clone. | +| **symfony.lock** | Symfony dependency snapshot | Records Symfony recipes applied during setup. | Used internally by Symfony Flex; no manual editing. | +| **var/** | Runtime data | Cache, logs, temporary files. | Can safely be deleted (Shopware rebuilds it). | +| **vendor/** | Dependency code | All installed PHP libraries from Composer. | Analogous to `node_modules/`. | diff --git a/guides/installation/requirements.md b/guides/installation/requirements.md deleted file mode 100644 index 205f83a65..000000000 --- a/guides/installation/requirements.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -nav: - title: Requirements - position: 1 - ---- - -# Requirements - -This page lists the system requirements and supported software versions for developing Shopware 6. Find installation steps for each setup method on their respective pages: - -- [Docker setup](./setups/docker.md); recommended for most users -- [Devenv setup](./setups/devenv.md) -- [Symfony CLI](./setups/symfony-cli.md) - -## Requirements for all setups - -Before setting up your Shopware 6 development environment, make sure your system is ready. Check these basics before installation: - -- You’re using a Unix-based system (macOS or Linux), or Windows with WSL 2 or Docker for full compatibility -- You have admin/root privileges (if required in your organization) -- [Git](https://git-scm.com/) installed and available in your `PATH` -- You have at least 8 GB RAM (16 GB recommended) and 10 GB free disk space -- Docker Desktop, PHP, or Nix are not already bound to conflicting ports -- You have a reliable Internet connection for dependency downloads - -## Hardware recommendations - -These recommendations ensure smooth local development regardless of setup: - -| Component | Recommended | -|:---------------------|:-------------------------------------------------------------| -| **CPU** | Quad-core or higher | -| **Memory (RAM)** | 8 GB minimum, 16 GB recommended (especially for Docker) | -| **Disk space** | ~10 GB free for Shopware + services | -| **Operating system** | macOS 13+, Windows 10/11 (Pro with WSL 2), or Linux (64-bit) | - -## Permissions and networking - -- Ensure Docker or Symfony CLI has permission to bind to local ports (typically:80 or:8080). -- Allow your system’s firewall to let containers or local web servers communicate internally. -- On Linux, you may need to add your user to the `docker` group: - -```bash -sudo usermod -aG docker $USER -``` - -## Recommended stack and supported versions - -The following versions and configurations are officially supported for Shopware 6 development: - -| Component | Install | Minimum Version | Recommended | Required / Notes | -|:---------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------|:-------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **PHP** | [PHP installation guide](https://www.php.net/manual/en/install.php)
[Composer installation guide](https://getcomposer.org/download/) | 8.2+ | 8.4 | **Required.**
`memory_limit ≥ 512M`, `max_execution_time ≥ 30s`.
Required extensions: `ctype`, `curl`, `dom`, `fileinfo`, `gd`, `iconv`, `intl`, `mbstring`, `openssl`, `pcre`, `pdo_mysql`, `phar`, `simplexml`, `xml`, `zip`, `zlib`.
Optional: `amqp` (for message queues).
Composer 2.2+ recommended.
**macOS note:** If you install PHP with Homebrew, the `intl` extension may not be included by default. Install it separately:
`brew install php-intl` then verify with `php -m | grep intl`. | -| **SQL** | [MariaDB installation guide](https://mariadb.com/kb/en/getting-installing-and-upgrading-mariadb/)
[MySQL installation guide](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/) | MariaDB ≥ 10.11.6 or MySQL ≥ 8.0.22 | MariaDB 11.4 / MySQL 8.4 | **Required.**
`max_allowed_packet ≥ 32M` for optimal performance. | -| **Node.js / npm** | [Node.js downloads](https://nodejs.org/en/download) | Node 20.0.0+ | Node 24 / npm 10 | **Required.** | -| **Search** | [OpenSearch installation guide](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/index/) | OpenSearch 1.0+ or ElasticSearch 7.8+ | OpenSearch 2.17.1 | **Optional.** Used for product search and indexing.
**Note**: The search preview in the administration requires OpenSearch 2.12+ or Elasticsearch 8.8+.
Support for OpenSearch 3.1 was added in shopware v6.7.3.1 | -| **Cache / KV store** | [Valkey](https://valkey.io/)
[Redis](https://redis.io) / [Redict](https://redict.io) / [Dragonfly](https://www.dragonflydb.io) | Redis v7+ | Valkey 8.0 | **Optional.** Used for caching and session storage.
Redis-protocol compatible alternatives supported.
`maxmemory-policy: volatile-lfu`. | -| **Web server** | [Caddy setup guide](https://developer.shopware.com/docs/resources/references/config-reference/server/caddy.html)
[Apache](https://developer.shopware.com/docs/resources/references/config-reference/server/apache.html)
[Nginx](https://developer.shopware.com/docs/resources/references/config-reference/server/nginx.html) | Any | Caddy | **Required.** For local development, the [Symfony CLI server](https://symfony.com/doc/current/setup/symfony_cli.html) works out of the box. | -| **Queue** | [RabbitMQ downloads](https://www.rabbitmq.com/download.html)
[AWS SQS](https://aws.amazon.com/sqs/) | Any transport supported by the [symfony messenger component](https://symfony.com/doc/current/messenger.html#transport-configuration) | RabbitMQ | **Optional.** By default the SQL database will be used as a queue, however in production setups it is highly recommended to use a dedicated queue system for scalability and observability reasons. | - -See also: [PHP performance tweaks guide](https://developer.shopware.com/docs/guides/hosting/performance/performance-tweaks.html#php-config-tweaks) - -## Verifying your local environment - -Use the following commands to verify your local environment: - -::: info -On many systems or hosting environments, multiple PHP versions may be installed. -Make sure to use the correct PHP binary, as CLI and FPM often have different `php.ini` files. -Ask your hosting provider for the correct PHP binary and how to adjust `php.ini`. -::: - -- `php -v`: Show CLI PHP version -- `php -m`: List CLI PHP modules -- `php -i | grep memory_limit`: Show your CLI PHP memory limit -- `composer -V`: Show Composer version -- `node -v`: Show Node version -- `npm -v`: Show npm version - -## Next steps - -Once your environment meets these requirements, proceed to your preferred installation method: - -- [Docker setup](./setups/docker.md) -- [Symfony CLI setup](./setups/symfony-cli) -- [Devenv setup](./setups/devenv.md) diff --git a/guides/installation/setups/docker.md b/guides/installation/setups/docker.md deleted file mode 100644 index 4ad665ff1..000000000 --- a/guides/installation/setups/docker.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -nav: - title: Docker - position: 10 - ---- - -# Docker - -::: info -This setup is intended for development. If you want to use Docker for production, please check out this [guide](../../hosting/installation-updates/docker.md). -::: - -Docker is a platform that enables developers to develop, ship, and run applications inside containers. These containers are lightweight, standalone, and executable packages that include everything needed to run an application: code, runtime, system tools, libraries, and settings. To get started with Docker, you can follow the official [Docker installation guide](https://docs.docker.com/get-started/get-docker/). - -The Docker setup automatically provides all backend services (PHP, MySQL, Elasticsearch, Redis, Mailhog, etc.) so you don’t need to install anything else manually. - -In this guide, we will run PHP, Node, and all required services in Docker containers. If you just want to run the services (MySQL/OpenSearch/Redis/...) in Docker, check out the [Docker](./docker.md) guide. - -## Prerequisites - -- [Docker](https://docs.docker.com/get-started/get-docker/) or [OrbStack](https://docs.orbstack.dev/quick-start) (macOS) is installed and running. OrbStack is a fast, free (for personal use) alternative to Docker. -- `make` is installed on your machine (`apt install make` on Ubuntu, `brew install make` on macOS) -- `Docker Compose` is installed on your machine. Docker Desktop provides it automatically. If you're using OrbStack or something else, you can follow the official [Docker Compose installation guide](https://docs.docker.com/compose/install/). -- Enough disk and network capacity to pull images (~500MB+ per image depending on tags) - -## Pre-pull the image (optional) - -If you haven’t yet downloaded the Shopware Docker image, pull it now: - -```bash -docker pull ghcr.io/shopware/docker-dev:php8.3-node24-caddy -``` - -If you skip this step, Docker will automatically download the image during project creation. That’s normal, but pre-pulling makes the process cleaner and enables you to avoid waiting for large image downloads. - -## Create a new project - -Create a new empty directory and navigate to it: - -```bash -mkdir my-project && cd my-project -``` - -Then create a new project (required): - -```bash -docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup -``` - -Or you can use a specific version of Shopware (optional), like so: - -```bash -docker run --rm -it -v $PWD:/var/www/html ghcr.io/shopware/docker-dev:php8.3-node24-caddy new-shopware-setup 6.6.10.0 -``` - -This step creates your new Shopware project in the current directory, along with a `compose.yaml` and a `Makefile`. The difference from regular `composer create-project` is that we run PHP and Composer from within the Docker image. This means you don’t need to have PHP or Composer installed on your local machine. - -The project creation currently takes several minutes to complete. - -During the process, this prompt will appear: `Do you want to use Elasticsearch? (y/N)`. Elasticsearch improves search performance for large catalogs. We recommend: - -- answering "yes" if you expect thousands of products or use Shopware's advanced search features. You'll need an `elasticsearch` container/service. [Go here](https://developer.shopware.com/docs/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.html) to learn more about Elasticsearch setup. -- answering "no" if you’re just testing locally or have a small dataset. In this case, Shopware will use the MariaDB database for search. - -Shopware projects include files that use a combination of Symfony, Composer, Docker, and Shopware-specific conventions. - -
-Project structure explained (click to expand) - -| Item | Type | Purpose / what it contains | Notes | -|---------------------------|-----------------------------|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| -| **bin/** | Directory | Executable scripts (e.g., `bin/console` — the main CLI for Shopware/Symfony). | Think of it like `npm run` or `go run` scripts. Use `bin/console` to run commands inside the app. | -| **compose.yaml** | Docker | Defines the Docker services (web, database, mailpit, etc.). | Equivalent to your project’s “infrastructure recipe.” | -| **compose.override.yaml** | Docker | Local overrides for the default Docker Compose stack (e.g., port mappings, extra volumes). | Optional; used to customize or extend services locally. | -| **composer.json** | PHP dependency manifest | Lists PHP dependencies and metadata (like `package.json`). | `composer install` reads this. | -| **composer.lock** | Dependency lock file | Locks exact versions of PHP packages. | Don’t edit manually; committed to git. | -| **config/** | Directory | Symfony configuration files (framework, database, mail, etc.). | Similar to `config/` in many web frameworks. | -| **custom/** | Directory | Your plugins, themes, or app customizations. | This is where you add new extensions — your “src” for Shopware plugins. | -| **files/** | Directory | Uploaded media and temporary files. | Ignored by git; generated at runtime. | -| **Makefile** | Build helper | Shortcuts for Docker tasks (`make up`, `make setup`, etc.). | Replaces long Docker commands with memorable aliases. | -| **public/** | Web root | The actual web-server-accessible directory (contains `index.php`, assets, etc.). | Like `/dist` in JS frameworks or `/public_html`. | -| **src/** | Source code | Shopware’s core application source. | Where the main PHP codebase lives; not usually edited in a project clone. | -| **symfony.lock** | Symfony dependency snapshot | Records Symfony recipes applied during setup. | Used internally by Symfony Flex; no manual editing. | -| **var/** | Runtime data | Cache, logs, temporary files. | Can safely be deleted (Shopware rebuilds it). | -| **vendor/** | Dependency code | All installed PHP libraries from Composer. | Analogous to `node_modules/`. | - -
- -You’ll mostly interact with these: - -- **Makefile**, which provides convenient shortcuts for common Docker and Shopware commands. It acts as a lightweight wrapper around standard `docker compose` commands. You can still use the underlying Docker commands directly, but it’s recommended to stick with the `make` targets where possible, as they ensure consistent behavior across setups. -- **`custom/`**, to build your own plugins. -- **`bin/console`**, to run Shopware CLI tasks. - -Everything else in your project either supports or configures those layers. - -## Initial setup - -After creating your project, you still need to install Shopware inside the containers. Run the setup commands below to initialize the database, generate configuration files, and create the default admin user. - -First, start the containers: - -```bash -make up -``` - -This command builds (if needed) and starts all required Docker services (web server, database, Mailpit, etc.) in the background. More details about what each component does: - -
-Components explained (click to expand) - -| Name | Type | Purpose | -|---------------------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------| -| **Network `my-project_default`** | Docker network | A private virtual network so all containers can communicate (for example, the web container connects to the database). | -| **Volume `my-project_db-data`** | Persistent storage | Stores the MariaDB database files so your data isn’t lost when containers are stopped or rebuilt. | -| **Container `my-project-mailer-1`** | Mailpit service | Captures outgoing emails for local testing. View at [http://localhost:8025](http://localhost:8025). | -| **Container `my-project-database-1`** | MariaDB service | Runs the Shopware database. Inside the Docker network its host name is `database`. | -| **Container `my-project-web-1`** | PHP + Caddy web service | Runs Shopware itself and serves the storefront and Admin UI at [http://localhost:8000](http://localhost:8000). | -| **Container `my-project-adminer-1`** | Adminer (DB UI) | Lightweight web interface for viewing and editing your database. Available at [http://localhost:8080](http://localhost:8080). | - -
- -**Tip:** You can check container status anytime with: - -```bash -docker compose ps -``` - -“Healthy” means the service passed its internal health check and is ready to use. - -Once the containers are running, you can install Shopware in one of two ways: - -- **Browser installer**: open to walk through the installation wizard. -- **CLI**: run the following command to perform a quick, non-interactive setup: - -```bash -make setup -``` - -Both methods install Shopware and prepare your environment. The CLI setup automatically creates the database and an admin user with username `admin`, password `shopware`. - -:::info -If you are installing inside the Docker containers (the default when using `make up` and `make setup`), set the database host to `database`. This is the internal service name of the MariaDB container on the Docker network. Inside the containers, `localhost` would refer only to the container itself, not to the database. - -If you connect to the database from your host machine (for example, via Adminer or a local MySQL client), use 127.0.0.1 or `localhost` and the exposed port shown in `docker compose ps`. -::: - -
-Access key explained (click to expand) - -During setup, you’ll see an output similar to this: - -```bash -Access tokens: -+------------+----------------------------+ -| Key | Value | -+------------+----------------------------+ -| Access key | `string of capital letters` | -``` - -This access key is automatically generated for your default Sales Channel (usually *Storefront*). It's used for authenticating requests to the [Store API](../../../concepts/api/store-api)—for example, when fetching product or category data from an external app, headless storefront, or API client. - -Example usage: - -```bash -curl -H "sw-access-key: YOUR_ACCESS_KEY" \ - http://localhost:8000/store-api/product -``` - -You can view or regenerate this key later in the Admin under Sales Channels → [Your Channel] → API Access. - -:::info -The access key is not for logging in to the Admin. It’s for programmatic access to your storefront’s data via the Store API. -::: -
- -If you want to stop the setup, run `make stop`. - -To start it again, use `make up`. - -To stop and remove all containers, run: - -```bash -make down -``` - -This command removes all containers and associated networks. - -If you also want to remove all data and volumes (for example, to perform a full reset of your environment), run: - -```bash -docker compose down -v -``` - -The `-v` flag will delete the containers, networks, and volumes, meaning all stored data will be lost. - -### Known issue on Linux hosts - -If you are using Docker on Linux, your host user id (UID) must be **1000** for file permissions to work correctly inside the containers. You can check your user ID with: - -```bash -id -u -``` - -If it’s not `1000`, you may encounter permission errors when running `make up` or writing to project files. - -## Development - -To run Shopware CLI commands, first open a shell inside the web container: - -```bash -make shell -``` - -This command drops you into the container’s terminal (you’ll see the prompt change). From there, you can execute any Shopware CLI command using `bin/console`. For example, to clear the application cache (not required right now): - -```bash -docker compose exec web bin/console cache:clear -``` - -**Tip**: When you’re inside the container, you only need `bin/console …`. If you prefer to run commands from your host machine instead, use the full Docker prefix: `docker compose exec web bin/console cache:clear`. - -You’ll use the following Makefile commands later on, when you modify frontend or admin code, or develop plugins that affect the UI: - -```bash -# Build the administration (admin panel) -make build-administration - -# Build the storefront (shop frontend) -make build-storefront - -# Start a watcher to rebuild the Administration automatically when files change -make watch-admin - -# Start a watcher for Storefront -make watch-storefront -``` - -These will become part of your everyday development workflow. - -## Verify your installation in the browser (optional) - -Now that Shopware is installed, you can confirm the storefront is working by visiting [http://localhost:8000](http://localhost:8000). - -Shopware’s CLI setup automatically installs a complete, preconfigured demo storefront with sample products and categories. It includes local, disposable demo data so you can explore features or test plugins immediately. - -You can also check out the Shopware Admin dashboard to verify that the Admin is accessible: - -- Log in to the **Admin** at [http://localhost:8000/admin](http://localhost:8000/admin) using `admin / shopware` (default credentials). -- Once logged in, you’ll see the Shopware Admin dashboard and merchant setup wizard. - -As a developer, you can skip the wizard and use the Admin to: - -- confirm your installation and database are running correctly. -- manage extensions or themes you install later. -- inspect system settings and logs. -- verify that changes from your code (for example, new entities or configuration options) appear in the UI. - -## Services - -With Shopware running, here are the services in your local stack and how to access them. Understanding what each one does helps you troubleshoot issues and connect external tools if needed: - -- **Web service (Caddy + PHP-FPM by default, or Nginx + PHP-FPM)**: serves both the storefront and the admin interface. The default image uses Caddy; you can choose Nginx in image variations. -- Storefront: [http://localhost:8000](http://localhost:8000) -- Admin: [http://localhost:8000/admin](http://localhost:8000/admin) *(default credentials: `admin` / `shopware`)* - -- **Database (MariaDB)**: runs on port **3306** inside Docker. The internal hostname is `database`. You can connect from your host using `localhost:3306` if you want to inspect the database directly. - -- **Mailpit**: local mail testing tool, available at [http://localhost:8025](http://localhost:8025). Use this to view emails sent by Shopware (e.g., registration or order confirmations) without needing an external mail server. - -### Changing environment variables - -You can create a `.env` file in the project root to override default environment variables. Changes take effect automatically without restarting containers **except for** the `APP_ENV` variable, which requires: - -```bash -make up -``` - -This command restarts the containers so that the updated environment variable takes effect. - -## Production environments - -If you're preparing to run Shopware in production using Docker, [this page](../../hosting/installation-updates/docker.md) covers production images, environment configuration, and deployment workflows. - -## Detailed configurations - -You can find more detailed configurations for your docker setup in the [Additional Docker Options](docker-options) article. diff --git a/guides/installation/setups/index.md b/guides/installation/setups/index.md deleted file mode 100644 index c1d5c57d1..000000000 --- a/guides/installation/setups/index.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -nav: - title: Setups - position: 10 - ---- - -# Setups - -Once your system meets the [requirements](../requirements.md), you can choose how you want to run your Shopware 6 development environment. This page helps you understand how each setup works in practice: What it’s best at, what to expect in daily use, and how to switch between them. - -## Docker setup (recommended) - -Docker runs your entire Shopware environment in containers, including PHP, MySQL, Redis, Elasticsearch, and Mailhog. It gives you a production-like stack with minimal manual setup. - -**What to expect** - -- All services run inside containers managed by Docker Compose. -- Great parity between development, CI, and production. -- Easy to reset or rebuild environments (`docker compose down -v`). -- Higher resource usage, but consistent results on any machine. - -**When it shines** - -- You want zero “works on my machine” issues. -- You collaborate with others or use CI/CD pipelines. -- You need full service parity (e.g. caching, queues, search). - -[Docker setup guide →](./docker.md) - -## Symfony CLI setup - -Symfony CLI runs Shopware locally using your host system’s PHP and Composer installation. -It’s lightweight, fast, and easy to debug using your local toolchain. - -**What to expect** - -- Uses your installed PHP, MySQL, and Node.js directly. -- Minimal overhead and startup time. -- Ideal for plugin, theme, or app developers who want rapid iteration. -- You manage local dependencies (e.g. PHP extensions, database) yourself. - -**When it shines** - -- You’re building or testing extensions, not full stacks. -- You prefer editing and debugging locally. -- You’re on a resource-limited machine. - -[Symfony CLI setup guide →](./symfony-cli.md) - -## Devenv setup - -Devenv uses [Nix](https://nixos.org/) to define a reproducible Shopware development environment. -It ensures everyone — across macOS, Linux, and CI — gets the same dependency versions and behavior. - -**What to expect** - -- You define all tools and services in `devenv.yaml`. -- Nix handles installation and version consistency automatically. -- Works well in multi-version or multi-project contexts. -- Slightly steeper learning curve but high reliability. - -**When it shines** - -- You contribute to Shopware core or maintain multiple versions. -- You want reproducibility between developers and CI. -- You value a declarative, version-controlled environment. - -[Devenv setup guide →](./devenv.md) - -## Community and alternative Docker tooling - -If you prefer a more automated or GUI-friendly way to run Docker environments, DDEV and Dockware are both popular within the Shopware community. **Note:** DDEV and Dockware are community-maintained and not officially supported by Shopware. - -### DDEV setup - -[DDEV](https://ddev.com/) is a developer-friendly wrapper around Docker that automates environment setup using simple CLI commands. - -**Why use DDEV** - -- Simplifies Docker configuration: no manual `docker-compose.yml` needed. -- One command (`ddev start`) to start your Shopware environment. -- Easy to switch PHP/MySQL/Node versions per project. -- Integrates well with VS Code and PHPStorm. - -**Use it when** - -- You want a pre-configured, easy-to-use Docker experience. -- You prefer to focus on code, not container details. - -[DDEV with Shopware example →](https://github.com/ddev/test-shopware6) - -### Dockware setup - -[Dockware](https://www.dockware.io/) provides ready-to-run Docker images for quickly spinning up demo stores or full local environments. - -**Why use Dockware** - -- Pre-built images for Shopware 5, 6, and nightly builds. -- Includes all key services: PHP, DB, Elasticsearch, Mailhog, Adminer, etc. -- Great for testing specific versions or quick evaluation. -- Can be used standalone or integrated into CI pipelines. - -**Use it when** - -- You need a running Shopware instance in seconds. -- You’re testing multiple Shopware versions or demos. -- You prefer minimal setup over full customization. - -[Dockware documentation →](https://docs.dockware.io/) - -## Switching between setups - -All setups share the same Shopware [Project Template](../template). Only the runtime environment differs. You can safely switch between setups as long as you keep separate environment configurations. - -To switch setups: - -1. Stop running services (e.g., `docker compose down`, or `symfony server:stop`). -2. Use separate directories for each setup. -3. Reuse the same project template if needed. Each setup has its own configuration files. - -You can always migrate between setups later. Your Shopware project remains the same. - -## Next step - -Choose your preferred setup and follow its related guide. Once your setup is running, you can start developing your shop, app, plugin, or theme. - -## Installing Shopware CLI - -Most developers install the [Shopware CLI](../../../products/cli/index.md), which helps with building, refactoring, validating, and managing Shopware projects and extensions. It works with all setups (Docker, Symfony CLI, Devenv, DDEV, Dockware) and is used in most Shopware upgrade, build, and CI workflows. If you're using the Docker setup, the CLI comes preinstalled and is available in the container shell. diff --git a/guides/installation/template.md b/guides/installation/template.md deleted file mode 100644 index 9b7a4eb59..000000000 --- a/guides/installation/template.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -nav: - title: Project Template - position: 2 - ---- - -# Project Template - -The Shopware project template is a Composer project that can be used as a starting point for new Shopware Projects, or if you want to develop extensions or themes for Shopware. - -Each official setup option—[Docker](./setups/docker.md), [Symfony CLI](./setups/symfony-cli.md), and [Devenv](./setups/devenv.md)—builds upon this project template, either directly or via a pre-configured environment. See [Installation Overview](./index.md) for a comparison of setup options. - -## Alternative: Using the installer package - -If you have downloaded the [shopware-installer.phar package](https://www.shopware.com/en/download/) instead of using Composer, skip the `composer create-project` step and follow the remaining instructions from the [Project Template](https://developer.shopware.com/docs/guides/installation/template.html) guide. - -This method is equivalent to creating a project using Composer but is suited for environments where Composer is not available (for example, shared hosting or limited enterprise servers). - -## Set up a new project - -To create a new Shopware project, run the following command: - -```bash -composer create-project shopware/production - -# or install a specific version -composer create-project shopware/production:6.6.10.5 -``` - -::: info -Composer `create-project` clones the latest tag from the [Template repository](https://github.com/shopware/template) and installs the dependencies. If you don't have Composer installed, you could also clone the repository itself and run `composer install` in Docker to proceed with the installation. -::: - -This creates a new project in the `` directory. - -The template contains all Shopware bundles like `shopware/administration`, `shopware/storefront` and `shopware/elasticsearch`. If you don't need any, then you can uninstall them with: - -```bash -composer remove shopware/ -``` - -## Installation - -After you have created the project, you have automatically a `.env` file in your project root. This file contains all the environment variables you need to run Shopware. - -If you want to adjust a variable, you should put the variable in a `.env.local` file. This file will override the variables in the `.env` file. - -::: info -The `.env` will be overwritten when the Shopware Web Installer is used for Shopware updates, so it's highly recommended to use a `.env.local` file. -::: - -After you have adjusted the `.env` file, you can run the following command to install Shopware: - -```bash -bin/console system:install --basic-setup -``` - -The flag `--basic-setup` will automatically create an admin user and a default sales channel for the given `APP_URL`. If you haven't created a MySQL Database yet, you can pass the `--create-database` flag to create a new database. - -The Shopware's default Administration credentials are: - -| Username | Password | -|:---------|:-----------| -| `admin` | `shopware` | - -Change these credentials after finishing the installation. - -### Optional packages - -The template is small and does not contain any dev-tooling or integrations like PaaS or Fastly. You can easily add them to your project with the following commands: - -```bash -# Install profiler and other dev tools, eg Faker for demo data generation -composer require --dev shopware/dev-tools - -# Or Install symfony dev tools -composer require --dev symfony/profiler-pack - -# Install PaaS integration -composer require paas --ignore-platform-req=ext-amqp - -# Install Fastly integration -composer require fastly -``` - -### Add Shopware packagist - -Using Shopware Packagist, you can manage all your Shopware Store plugins directly in the `composer.json`. Refer to ["Using Composer for plugin installation in Shopware"](https://www.shopware.com/en/news/using-composer-for-plugin-installation-in-shopware/) blog post for detailed information. - -## Building/watching Administration and Storefront - -The created project contains Bash scripts in `bin/` folder to build and watch the Administration and Storefront. You can run the following commands: - -```bash -./bin/build-administration.sh -./bin/build-storefront.sh -./bin/watch-administration.sh -./bin/watch-storefront.sh -``` - -Use these scripts to build the Administration and Storefront. The `watch` commands will watch for changes in the Administration and Storefront and rebuild them automatically. - -## Update Shopware - -For detailed instructions on performing Shopware updates, including preparation steps, the update process, and post-update verification, refer to the dedicated guide: - - - -## Migrate from the old zip installation to a new project template - -Before Shopware 6.5, we provided a zip file for installation. The zip file contained all dependencies required to run Shopware. This method has been deprecated and replaced with a Composer project template. The Composer project template is way more flexible and allows you to manage extensions together with Shopware itself using Composer. - -To migrate from the old zip installation to the new Composer project template, you can use `shopware-cli project autofix flex` command to migrate it automatically, or you can do it manually by following the steps below. - -### 1. Backup - -Start with a clean git state, stash everything, or make a backup of your files. - -### 2. Adjust root composer.json - -First, adjust your root `composer.json`. Add the following lines to your `composer.json`: - -```json -"extra": { - "symfony": { - "allow-contrib": true, - "endpoint": [ - "https://raw.githubusercontent.com/shopware/recipes/flex/main/index.json", - "flex://defaults" - ] - } -} -``` - -Next, replace all the existing scripts with the following: - -```json -"scripts": { - "auto-scripts": [], - "post-install-cmd": [ - "@auto-scripts" - ], - "post-update-cmd": [ - "@auto-scripts" - ] -} -``` - -Finally, remove the fixed platform as it will now be determined by the required packages. - -```diff -"config": { - "optimize-autoloader": true, -- "platform": { -- "php": "7.4.3" -- }, - "sort-packages": true, - "allow-plugins": { - "composer/package-versions-deprecated": true - } -}, -``` - -### 3. Cleanup the template - -After having installed the new Composer packages, you can clean up the template by removing the following files: - -```bash -rm -r .dockerignore \ - .editorconfig \ - .env.dist \ - .github \ - .gitlab-ci \ - .gitlab-ci.yml \ - Dockerfile \ - docker-compose.yml \ - easy-coding-standard.php \ - PLATFORM_COMMIT_SHA \ - artifacts \ - bin/deleted_files_vendor.sh \ - bin/entrypoint.sh \ - bin/package.sh \ - config/etc \ - src \ - config/secrets \ - config/services \ - config/services.xml \ - config/services_test.xml \ - license.txt \ - phpstan.neon \ - phpunit.xml.dist \ - psalm.xml - -touch .env -``` - -### 4. Install required Composer packages - -To install Symfony Flex, you need to have Composer installed. If you don't have Composer installed, please follow the [official documentation](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos). - -To install Symfony Flex, you need to run the following commands and allow both new Composer plugins. - -```bash -composer require "symfony/flex:*" "symfony/runtime:*" - -composer recipe:install --force --reset -``` - -### 5. Review changes - -Review the changes and commit them to your Git repository. All upcoming config changes can be applied with `composer recipes:update`. - -You may need to adjust some environment variables as the names have changed: - -| **Old name** | **New name** | -|-------------------|----------------| -| MAILER_URL | MAILER_DSN | -| SHOPWARE_ES_HOSTS | OPENSEARCH_URL | - -## Known issues - -### `APP_ENV=dev` web_profiler missing extension error - -Prior to Shopware 6.4.17.0, you have to install the Profiler bundle to get `APP_ENV=dev` working with: - -```bash -composer require --dev profiler -``` - -### framework:demo-data is missing faker classes - -Prior to Shopware 6.4.17.0, you have to install some packages to get `framework:demo-data` command working: - -```bash -composer require --dev mbezhanov/faker-provider-collection maltyxx/images-generator -``` diff --git a/guides/installation/setups/devenv-options.md b/guides/legacy-setups/devenv-options.md similarity index 100% rename from guides/installation/setups/devenv-options.md rename to guides/legacy-setups/devenv-options.md diff --git a/guides/installation/setups/devenv.md b/guides/legacy-setups/devenv-setup.md similarity index 99% rename from guides/installation/setups/devenv.md rename to guides/legacy-setups/devenv-setup.md index b7315b21f..7139cb134 100644 --- a/guides/installation/setups/devenv.md +++ b/guides/legacy-setups/devenv-setup.md @@ -1,11 +1,11 @@ --- nav: - title: Devenv + title: Setting up Shopware with Devenv position: 20 --- -# Devenv +# Setting up Shopware with Devenv [Devenv](https://devenv.sh) is a Nix-based tool for defining and managing fully reproducible development environments for local workstations or continuous integration (CI) systems. It works like a dependency manager for your entire development stack. diff --git a/guides/installation/setups/symfony-cli.md b/guides/legacy-setups/setup-symfony-cli.md similarity index 94% rename from guides/installation/setups/symfony-cli.md rename to guides/legacy-setups/setup-symfony-cli.md index 592147ff9..2a9eac0c6 100644 --- a/guides/installation/setups/symfony-cli.md +++ b/guides/legacy-setups/setup-symfony-cli.md @@ -1,11 +1,11 @@ --- nav: - title: Symfony CLI + title: Setting up Shopware with Symfony CLI position: 30 --- -# Symfony CLI Setup +# Setting up Shopware with Symfony CLI Symfony CLI lets you run Shopware 6 locally without Docker. It's a lightweight option that uses your system’s PHP, Composer, and Node.js installations. @@ -172,9 +172,3 @@ symfony php -i By keeping your `php.ini` in version control, you ensure consistent behavior across development environments and CI pipelines. Symfony CLI uses PHP’s built-in web server by default. For better performance, you can configure it to use Nginx or Caddy: see the [web server reference](../../../resources/references/config-reference/server/nginx.md). - -## Build and Watch the Administration and Storefront (Optional) - -You only need to run this step if you’re developing or customizing the frontend (Administration or Storefront). It compiles JavaScript and CSS assets so your changes are visible immediately. - - diff --git a/guides/legacy-setups/symfony-cli-setup.md b/guides/legacy-setups/symfony-cli-setup.md new file mode 100644 index 000000000..d7774b1aa --- /dev/null +++ b/guides/legacy-setups/symfony-cli-setup.md @@ -0,0 +1,182 @@ +--- +nav: + title: Setting up Shopware with Symfony CLI + position: 30 + +--- + +# Setting up Shopware with Symfony CLI + +Symfony CLI lets you run Shopware 6 locally without Docker. It's a lightweight option that uses your system’s PHP, Composer, and Node.js installations. + +Shopware recommends [Docker](../installation/docker-setup.md) as the default setup for most users because it mirrors production and includes all services out of the box. However, if you already have PHP and a database installed locally, or want a faster, low-overhead workflow, Symfony CLI is a solid alternative. + +## Prerequisites + +Before you begin, make sure your system meets the [Shopware 6 requirements](../installation/hardware-requirements.md). + +You’ll need the following software installed on your host machine: + +- [Symfony CLI](https://symfony.com/download) +- PHP 8.2 or higher with the required extensions; see our [recommended stack and supported versions](../hosting/index.md#recommended-stack-and-supported-versions) for the complete list +- [Composer 2.x](https://getcomposer.org/) +- [Node.js 20+](https://nodejs.org/en/download) and npm +- A running MySQL 8 or MariaDB 11 database (local or remote) + +You’ll also need a working web server. The Symfony CLI can provide one automatically for development. + +> **macOS note:** If you installed PHP via Homebrew, make sure the `intl` extension is enabled: `brew install php-intl` then verify with `php -m | grep intl`. + +Optional tools: + +- [Elasticsearch 8](https://www.elastic.co/elasticsearch/) for product search and indexing +- Docker (for running only the database while keeping PHP local) + +## Create a New Project + +Run this command to create a new Shopware production project: + +```bash +composer create-project shopware/production + +# or specify a version +composer create-project shopware/production:6.6.10.0 +``` + +During project creation, Symfony Flex asks whether you want to use Docker. Choose **Yes** if you want to run the database in a container, or **No** to use a local MySQL/MariaDB server. + +For more details about the Composer-based project template, see the [Shopware Production template](https://github.com/shopware/production). + +## Configure database connection + +After creating the project, define your database settings in a `.env.local` file in the project root: + +```dotenv +DATABASE_URL=mysql://username:password@localhost:3306/dbname +``` + +You can define other environment settings (like `APP_URL`, `MAILER_DSN`, or `SHOPWARE_ES_HOSTS`) in `.env.local` as needed. + +Git ignores `.env.local`, so you can safely define machine-specific settings here without affecting your team’s shared configuration. + +### Using Docker for the database (optional) + +Running the database in a Docker container helps keep your local system clean and ensures version consistency with production environments. If you prefer this instead of installing MySQL or MariaDB locally, start Docker with: + +```bash +docker compose up -d +``` + +This command starts the database container in the background. + +To stop and remove the containers, while preserving the database data, run: + +```bash +docker compose down +``` + +Run `docker compose down -v` to remove the containers and delete all stored data volumes. + +::: info +Tip - Use the `-v` flag only if you want to completely reset the database. +::: + +## Install Shopware + +::: info +Always prefix commands with `symfony` to ensure the correct PHP version and configuration are used. Skipping this can cause issues such as using the wrong PHP binary or failing to connect to the Docker-based MySQL database. +::: + +Run the following command to install Shopware: + +```bash +symfony console system:install --basic-setup +``` + +The `--basic-setup` flag initializes Shopware with sensible defaults. It automatically creates a database schema, an admin user, and a default sales channel for the specified `APP_URL` so you can start testing immediately without manual configuration. Optional: Add the `--create-database` flag if your database doesn’t already exist. + +If you encounter file-permission issues when installing or rebuilding caches, run `symfony console cache:clear` or check directory ownership. + +### Default Administration credentials + +Shopware creates a default Administration user during installation: + +| Username | Password | +|:---------|:-----------| +| `admin` | `shopware` | + +**Tip**: Change these credentials after installation for security. + +## Start the webserver + +The Symfony local web server automatically uses the correct PHP version, reads your `.env` configuration, and exposes HTTPS by default. This makes it more reliable than the built-in PHP server for local development. + +Start the local web server with: + +```bash +symfony server:start +``` + +By default, this starts the server on port `8000`. Access the Shopware Administration at [http://localhost:8000/admin](http://localhost:8000/admin) and the Storefront at [http://localhost:8000](http://localhost:8000). + +To run the server in the background, add the `-d` flag: + +```bash +symfony server:start -d +``` + +This frees up your terminal for other commands. + +### Stopping the Web Server + +To stop the server and all running processes, run: + +```bash +symfony server:stop +``` + +**Tip**: If port 8000 is already in use, start the server on a different port: `symfony server:start --port=8080` + +## Set the PHP version (optional, recommended) + +Specify a PHP version to ensure consistent environments across team members. + +To change the PHP version used by Symfony CLI, create a `.php-version` file in the project root and specify the desired version. For example, to use PHP 8.3, create `.php-version` and add: + +```dotenv +8.3 +``` + +Symfony CLI will now use PHP 8.3 for all commands in this project. Commit this file to your version control system so everyone on your team uses the same PHP version. + +To verify which PHP version is active, run: + +```bash +symfony php -v +``` + +## Adjust PHP configuration (Optional) + +Adjusting PHP settings like `memory_limit` or `max_execution_time` can prevent build or cache warm-up processes from failing, especially during large Administration builds or when working on plugins. + +You can override PHP settings for this project by adding a `php.ini` file in the project root. For example, to increase the `memory_limit` to 512 MB, add: + +```ini +memory_limit = 512M +``` + +To confirm your configuration, run: + +```bash +symfony php -i +``` + +By keeping your `php.ini` in version control, you ensure consistent behavior across development environments and CI pipelines. + +Symfony CLI uses PHP’s built-in web server by default. For better performance, you can configure it to use Nginx or Caddy: see the [web server reference](../../../resources/references/config-reference/server/nginx.md). + +## Build and Watch the Administration and Storefront (Optional) + +You only need to run this step if you’re developing or customizing the frontend (Administration or Storefront). It compiles JavaScript and CSS assets so your changes are visible immediately. + + diff --git a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md index f7d517cc7..0854a286b 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md @@ -7,139 +7,11 @@ nav: # Add Custom CLI Commands -To ease development tasks, Shopware contains the Symfony commands functionality. This allows \(plugin-\) developers to define new commands executable via the Symfony console at `bin/console`. The best thing about commands is, that they're more than just simple standalone PHP scripts - they integrate into Symfony and Shopware, so you've got access to all the functionality offered by both of them. +Shopware CLI commands are based on Symfony Console. This means that creating custom commands in Shopware plugins follows the standard Symfony approach. -Creating a command for Shopware 6 via a plugin works exactly like you would add a command to Symfony. Make sure to have a look at the Symfony commands guide: +See the [official Symfony documentation](https://symfony.com/doc/current/console.html) for the full guide. - - -## Prerequisites - -This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our plugin base guide to learn how to create a plugin at first: - - - -The main requirement here is to have a `services.xml` file loaded in your plugin. This can be achieved by placing the file into a `Resources/config` directory relative to your plugin's base class location. - -::: info -Refer to this video on custom **[Creating a CLI command](https://www.youtube.com/watch?v=OL_qNVLLyaI)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). -::: - -## Registering your command - -From here on, everything works exactly like in Symfony itself. Commands are recognised by Shopware, once they're tagged with the `console.command` tag in the [dependency injection](dependency-injection) container. So to register a new command, just add it to your plugin's `services.xml` and specify the `console.command` tag: - -```html - - - - - - - - -``` - -Here's a full example `services.xml` which registers your custom command: - -```xml -// /src/Resources/config/services.xml - - - - - - - - - - -``` - -Your command's class should extend from the `Symfony\Component\Console\Command\Command` class, here's an example: - -```php -// /src/Command/ExampleCommand.php -setDescription('Does something very special.'); - } - - // Actual code executed in the command - protected function execute(InputInterface $input, OutputInterface $output): int - { - $output->writeln('It works!'); - - return Command::SUCCESS; - } -} -``` - -This command is of course only a basic example, so feel free to experiment. As stated above, you now have access to all the functionality offered by Symfony and Shopware. - -::: info -For inspiration, maybe have a look at the Symfony documentation - you may for example use [tables](https://symfony.com/doc/current/components/console/helpers/table.html), [progress bars](https://symfony.com/doc/current/components/console/helpers/progressbar.html), or [custom formats](https://symfony.com/doc/current/components/console/helpers/formatterhelper.html). -::: - -### Running commands - -Commands are run via the `bin/console` executable. To list all available commands, run `bin/console list`: - -```text -$: php bin/console list -Symfony 4.4.4 (env: dev, debug: true) - -Usage: - command [options] [arguments] - -Options: - -h, --help Display this help message - -q, --quiet Do not output any message - -V, --version Display this application version - --ansi Force ANSI output - --no-ansi Disable ANSI output - -n, --no-interaction Do not ask any interactive question - -e, --env=ENV The Environment name. [default: "dev"] - --no-debug Switches off debug mode. - -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug - -Available commands: - about Displays information about the current project - help Displays help for a command - list Lists commands - feature - feature:dump Creating json file with feature config for js testing and hot reloading capabilities. - assets - assets:install - bundle - bundle:dump Creates a json file with the configuration for each active Shopware bundle. - cache - cache:clear Clears the cache - cache:pool:clear Clears cache pools - cache:pool:delete Deletes an item from a cache pool - cache:pool:list List available cache pools - cache:pool:prune Prunes cache pools - cache:warmup Warms up an empty cache - [...] -``` - -Each command usually has a namespace like `cache`, so to clear the cache you would execute `php bin/console cache:clear`. If you would like to learn more about commands in general, have a look at [this article](https://symfony.com/doc/current/console.html) in the Symfony documentation. +Commands registered as services in a Shopware plugin are automatically available via `bin/console`. ## More interesting topics diff --git a/index.md b/index.md index 2aab24c2a..194bb08bb 100644 --- a/index.md +++ b/index.md @@ -14,4 +14,6 @@ These two sections are complemented by the **References**, which contain structu Visit the [academy](https://academy.shopware.com/collections?category=developer-sw6) for video content. If you have any questions left, you can always ask them on [StackOverflow](https://stackoverflow.com/questions/tagged/shopware6?tab=Newest) or join our awesome community on [Discord](https://discord.com/channels/1308047705309708348/1309107911175176217). +To begin developing, [start here with our installation guide](guides/installation.md). + ![Readme](assets/readme-splash.png)