قالب وردپرس درنا توس
Home / Tips and Tricks / How to create a GitLab CI pipeline to statically analyze PHP projects – CloudSavvy IT

How to create a GitLab CI pipeline to statically analyze PHP projects – CloudSavvy IT



Image with the logos of GitLab and PHPStan

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̵

7;re using it locally, you’ve only come this far. You trust that your other team members are just as disciplined as you are. By integrating static analysis into a CI / CD workflow, you ensure that code cannot be merged if it breaks the main branch of your project.

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:

vendor/bin/phpstan analyse

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.

Screenshot of the Pipelines menu item in GitLab

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.

Screenshot of enabling Pipelines in GitLab

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.

Screenshot of enabling GitLab's MR-required pipelines

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 .tmp and 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 tmpDir to .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.

The --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

Commit your .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.

Screenshot of PHPStan GitLab CI pipelines

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.

Screenshot of GitLab Code Quality Merge Request widget

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.

Conclusion

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.


Source link