By performing a static analysis on your code, you save time by uncovering hidden problems. PHPStan is a static analysis tool for PHP that allows you to increase the quality of your codebase. Here’s how to run PHPStan within your GitLab CI pipelines.
It is good to run PHPStan regularly while developing new features. However, if you̵
Adjust with PHPStan
You must first add PHPStan to your project. We already have a detailed guide on how to install and configure PHPStan, so we’ll cover just the basics here.
First, use Composer to install PHPStan:
composer require --dev phpstan/phpstan
Then make a basic
phpstan.neon configuration file in your project:
parameters: level: max paths: - src - tests tmpDir: .tmp
The temporary folder is overwritten to aid in GitLab CI cache, set below.
You can now run PHPStan locally to make sure your configuration is working:
At this stage, it doesn’t matter if the tests pass.
Configure GitLab for CI
Make sure you’ve pushed your code to a project on your GitLab server. You need to make sure the Pipelines feature is enabled for your project – if you see “CI / CD” in the left sidebar, you’re good to go.
To enable your project’s CI system, click the “Settings” button in the sidebar. Expand the “Visibility, Project Features, Permissions” section and enable the “Pipelines” feature.
If you use GitLab’s Merge Requests (MRs) in a disciplined way, you can now configure GitLab to prevent MRs from merging unless they have a successful pipeline. Expand the ‘Merge Requests’ settings section and check the ‘Pipelines must pass’ toggle button. Click on “Save” to confirm. This prevents you from accidentally merging an MR when PHPStan fails against the changes.
To use GitLab CI, you must have a GitLab Runner defined at the instance, group, or project level. Runners are responsible for performing the CI jobs created by the GitLab system.
We are going to use the PHPStan Docker image to run PHPStan in our CI pipeline. This requires the use of a GitLab Runner using the Docker executor. If you’re using a self-managed instance and need to configure a new Runner, follow the guidelines in our article on setting up GitLab CI.
Create a GitLab CI pipeline
GitLab CI is configured with a
.gitlab-ci.yml file in the root of your project. CI pipelines support multiple consecutive stages. The tasks of each phase are performed in parallel. To run PHPStan, we need a single stage that performs one task.
stages: - phpstan cache: key: $CI_COMMIT_REF_SLUG paths: - .tmp/ - vendor/ phpstan: stage: phpstan image: ghcr.io/phpstan/phpstan script: - analyse --no-progress --error-format gitlab > phpstan.json artifacts: when: always reports: codequality: phpstan.json
This GitLab CI file contains everything we need to run PHPStan within our pipeline. We define a stage,
phpstan, with a task that does too
phpstan. The task uses the official PHPStan Docker image from the GitHub container registry.
The GitLab CI cache is configured to handle the
vendor folders. This will improve the performance of subsequent runs on the same branch. The cache will be restored automatically. Back in our
phpstan.neon, we set the
.tmp for this reason – it means that we can now confidently refer to it in the cache configuration of the CI pipeline.
We also cache
vendor to avoid unnecessary reinstallation of Composer dependencies on every run. Note that you don’t have to run
composer install manually – the official PHPStan Docker image automatically invokes it.
--error-format flag is passed to PHPStan’s
analyse order. This configures PHPStan to create a JSON file in the format accepted by GitLab’s code quality report. Down in the
artifacts section, this file will be uploaded to GitLab after the job is completed.
Using the pipeline
.gitlab-ci.yml and push to your GitLab server. The CI system should now start and create your first pipeline. Use the “CI / CD” link in the left navigation bar to view the progress of the pipeline.
If you get a green check mark, PHPStan’s tests have passed! Your branch is in good condition and ready to merge. If a red cross appears, you have more work to do. PHPStan and GitLab CI just stopped you from merging potentially faulty code.
You can get the list of errors by clicking the download icon to the right of the pipeline. Select the PHPStan code quality artifact to get the JSON report of errors that PHPStan found.
Use with merge requests
Reading the JSON manually does not provide a great experience. However, GitLab’s Merge Requests automatically display the contents of the report. Because the report is tagged as a GitLab code quality artifact, GitLab knows how to present the information in it.
Merge requests with a failing pipeline should display an extensible “Code Quality” section. This indicates the number of errors that occurred. Expand the section to view a complete list of issues found by PHPStan.
Once you’ve addressed the issues, push your changes to GitLab. The pipeline is running again. Once completed, you will see the new status on the Pipelines screen and in the code quality widget of your merge request.
PHPStan helps you write better PHP that is less prone to hidden problems. To get the most out of it, the tool must be incorporated into your development workflow in such a way that it cannot be ignored or bypassed.
Using PHPStan with GitLab CI gives you the consistency you need to be sure of your code. Configuring GitLab to block MRs with a failed pipeline means that changes cannot make it to your main branch without passing a PHPStan run. PHPStan’s full support for GitLab’s code quality reports makes it easy to assess errors without leaving the web interface, allowing you to quickly fix any issues that are discovered.