Write better code with PHPStan and PHP CodeSniffer
A step-by-step-guide

1. Why this is important

That’s why a standardized code style in your project(s) is important.
In Shopware 6 projects, it’s common to work in teams or collaborate with other developers. Without standardized coding practices code becomes difficult to understand, onboarding is slower and merging changes becomes difficult and error-prone.

By using PHPCS, you enforce consistent coding standards across the project, making it easier for multiple developers to work together seamlessly.

And money matters.

Have you run into issues that only showed up in production? PHPStan helps prevent that by catching bugs early in development. Bugs found in live production environments can disrupt business operations, damage your reputation (or your employer’s reputation) as a developer, and takes significantly more time (= higher cost) to fix than bugs that are caught earlier during your development cycle.

PHPStan helps by identifying issues during development. PHPStan is a static analysis tool designed to identify potential issues in your code without actually executing it. Unlike traditional debugging, which relies on running the code to expose problems, PHPStan analyzes your codebase to find errors, inconsistencies, or inefficiencies before they ever cause issues in production.

In the context of Shopware 6 development, PHPStan is particularly useful because it catches subtle mistakes that can easily go unnoticed. For example, it checks whether you’re using the correct data types, accessing properties or methods that actually exist, or following Shopware’s framework conventions. It also highlights unused variables, unreachable code, or situations where your assumptions about a variable’s type might lead to unexpected behavior.

By addressing these issues early, you not only improve code reliability but also reduce long-term maintenance costs.

Developers are often judged not only by the functionality of the software they create but also, especially by other developers, by the quality of the code they write. Writing good code goes beyond just making it work. It’s about creating solutions that are clean, maintainable, and - very important in the Shopware ecosystem - easy for others to understand and extend. Tools like PHPCS and PHPStan play a vital role in this process, helping - or almost forcing - developers to improve their skills and deliver higher-quality projects.

These tools work like a safety net and a helpful guide. They give developers the confidence to try new ideas and make changes without worrying about hidden mistakes. Using PHPCS and PHPStan regularly helps developers improve their coding skills naturally, as the tools teach good habits by pointing out potential mistakes in real-life project code.

2. Setting up PHPStan and PHPCS for Shopware 6

In a Shopware 6 project installed through the “composer template”, PHPStan and PHPCS will not be installed by default. By running the following composer command in your project, you can install the necessary requirements. Since the tooling is part of the development cycle, the flag ‘--dev’ will make sure that the tools are added to the “require-dev” part of your composer configuration, and will thus not impact your production environment in any way.

During the installation, composer will ask to “trust” the PHPStan extension installer. Answer “y” to this question.

The packages and versions are borrowed from the Shopware platform repository and are used by Shopware to use these tools when developing the Shopware core.

Additionally, to make running PHPStan and PHPCS easier, add the following Composer scripts to the “scripts” section of the composer.json file:

"phpstan": [
            
    "Composer\\Config::disableProcessTimeout",
    "@php vendor/shopware/core/DevOps/StaticAnalyze/phpstan-bootstrap.php",
    "phpstan analyze --memory-limit=2G -v"
],
"ecs": "php-cs-fixer fix --dry-run --diff --config .php-cs-fixer.dist.php",
"ecs-fix": "php-cs-fixer fix --config .php-cs-fixer.dist.php",

This will add run-commands to composer, which can be executed by running `composer run-script xyz` in your command line, where xyz is the name of the command you want to run.

3. Configuration

Before running PHPStan and PHPCS, we need to tell them what to check, where to look, and which rules to follow. To do that we can add some configuration files to our project that will point the tools in the right direction.
By installing the tools using composer, the files will have already been added to your project. The original content can be removed, and replaced with the configuration files from this blog post.

These configuration files are again based on the configuration used by the Shopware platform repository. This means that by using these configuration files you will follow the CS and PHPStan rules as recommended by Shopware, and as used by Shopware themselves.

Before running the commands, you will need to add both files to your project.

PHPStan

The ‘parameters’ section in the configuration file lets you define essential details like the PHP version, reporting level, and the cache path. But more importantly, also the directories in which php files are tested are defined here under ‘paths’. The configuration file as-is will test all custom code in the folder ‘custom’. This includes ‘plugins’, ‘apps’, ‘static-plugins’, and even other custom locations if they exist.
If necessary, tweak the parameters to fit to your project.

PHPCS

At the bottom of the configuration file, the setFinder function specifies which files PHPCS should check. Also here, the configuration file matches all PHP files in the `custom` folder.

4. Running tests

Running the CS and PHPStan tests is luckily very simple. By using the composer scripts we added previously, we can easily run the tools like this:

Quite obviously, the first command will run phpstan, the second command will run ecs and show you the code style mistakes and how to fix them. The third command will also run phpcs, but then automatically fix the mistakes. Unfortunately, no such command exists for phpstan.

Now that you’ve added the configuration files, try running phpstan on your project. Notice any immediate issues? Congratulations - you’re already improving your code quality.
Don’t be surprised though if the tools point out a lot of mistakes. And I mean it: a lot. In an unoptimized project where PHPStan and PHPCS have never been run, they can easily find hundreds of errors.
By adding a path to the commands, you can search for errors in more narrow locations. For example just for 1 plugin you have just been working on:

This works for all the 3 commands. This way you can gradually fix your project, without having the huge overload (and merge issues if you work in a team) of fixing everything at once.

5. Conclusion

Writing clean, maintainable, and reliable code is essential for successful Shopware 6 development, especially when working in teams or creating extensions for the Shopware Store. Tools like PHPCS and PHPStan are essential for ensuring consistent coding standards, catching potential issues early, and aligning with Shopware’s best practices. By incorporating these tools into your workflow, you not only improve the quality of your projects but also take every chance you get to grow as a developer.

In this post, we’ve covered how to set up and use PHPCS and PHPStan to follow Shopware’s rules, and you can start using it in your local development workflow.
In part two of this blog series, I’ll show you how to optimize them to run checks only on changed files using Git, and dive into integrating these tools into a CI/CD pipeline.

• X (@runelaenen)
• the Shopware Community Slack (@Rune Laenen)
• the Shopware Community Hub (@rune)
• Or come say "Hi 👋" if you see me at a Shopware event!