- Introduction
- Prerequisites
- Setting up Continuous Integration (CI) for PHP Project
- Testing the CI Workflow
- Visualizing the CI Process in GitHub
- Pre-Merge Checks and Bypassing CI Checks
- Troubleshooting and Advanced Configuration
- Sample Repository
- Conclusion
The purpose of this document is to provide a step-by-step guide for setting up a Continuous Integration (CI) workflow for a PHP project in GitHub. The CI workflow will automate the linting and code analysis processes to ensure code quality and reliability.
This document covers the basic setup of a CI workflow for a PHP project in GitHub, focusing on linting and code analysis steps. More advanced topics, such as deployment and additional steps, are outside the scope of this guide.
- A GitHub account with access to your target repository
- An existing or new repository with the PHP project hosted on GitHub
- All required configurations done as per PHP coding standards' Enforcing tools and config
-
Open your project repository and click on the Actions tab
-
A new page Choose a workflow will open, click on the set up a workflow yourself link
Note: In case the project already has some other workflows set up, click on the New workflow button on the left side. This will take you to the above page.
-
A new page will open, which will by default create a new file
.github/workflows/main.ymland allow editing it. For the purposes of this guide, we will rename the file tophp-lint.yml, though it can be named as seemed fit.
-
Follow the steps from Defining
onEvents and onwards to understand the creation and configuration of this file. Alternatively, paste the configuration in Complete Workflow Configuration and make changes as required. -
Finally, click on the Commit changes... button on the right and add the required commit message and description. The file should now be created in the project with the path
.github/workflows/php-lint.yml.
- Create or clone the repository on your system. Alternatively, open the repository on GitHub.
- In the root of your project, create a folder structure
.github/workflows/if it does not already exist. - Inside this folder, add a new file
php-lint.yml. File can be named as required, but it should be a.ymlfile. - Follow the steps from Defining
onEvents and onwards to understand the creation and configuration of this file. Alternatively, paste the configuration in Complete Workflow Configuration and make changes as required. - Commit and push this file to the main branch of your repository. The workflow file should now be created in your project.
Assign a name to your workflow.
name: PHP Coding StandardsTo automatically trigger a workflow, we use on to define which events can cause the workflow to run.
on:
push:
branches: [ main, dev ]
pull_request:
branches: [ main, release ]By specifying the above on events, this workflow will run whenever there is a push to the branches 'main' or 'dev', or a Pull Request is created for the branches 'main' or 'release'.
Branches can be added or removed as per the project needs. Addition of new branches can be done as follows:
push:
branches: [ main, dev, feature ]
pull_request:
branches: [ main, release, dev ]We can use permissions to modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required.
For our purposes, performing linting and code analysis can be achieved using just the contents: read permission, though this section can be modified as required by the project.
permissions:
contents: readDefine the job to perform the linting and code analysis tasks.
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout app
uses: actions/checkout@v3
- name: Cache Composer packages
id: composer-cache
uses: actions/cache@v3
with:
path: vendor
key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
restore-keys: |
${{ runner.os }}-php-
- name: Install dependencies
run: composer install --prefer-dist --no-progress
- name: Install PHP extensions
run: sudo apt install php-ast
- name: Run code quality checks
run: composer lint
- name: Run code analysis checks
run: composer phanHere is the complete configuration for the php-lint.yml workflow file:
name: PHP Coding Standards
on:
push:
branches: [ main, dev ]
pull_request:
branches: [ main, release ]
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout app
uses: actions/checkout@v3
- name: Cache Composer packages
id: composer-cache
uses: actions/cache@v3
with:
path: vendor
key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
restore-keys: |
${{ runner.os }}-php-
- name: Install dependencies
run: composer install --prefer-dist --no-progress
- name: Install PHP extensions
run: sudo apt install php-ast
- name: Run code quality checks
run: composer lint
- name: Run code analysis checks
run: composer phan- While on the 'main' or 'dev' branch, make changes to your code.
- Commit and push the made changes to GitHub.
- Create a new branch in your PHP project repository.
- Make necessary changes to your code and push the branch to GitHub.
- Create a Pull Request (PR) targeting the 'main' or 'release' branch.
- Navigate to your Pull Request/commit on GitHub.
- Check and observe the workflow run details for linting and code analysis.
- Check the job logs for any errors or warnings.
- Ensure that the workflow status reflects the success or failure of the workflow job.
In this section, we will visually explain the Continuous Integration (CI) process in GitHub and how it works for your PHP project.
When a developer works on a feature or bug fix, they create a new branch in the GitHub repository. They then make changes to the code and create a Pull Request (PR) for code review.
Developers may also make pushes to branches that are covered by the on event push as described in the CI workflow.
Upon PR creation/push, GitHub's CI workflow is automatically triggered. The php-lint.yml configuration file you've set up defines the triggers for and jobs to be executed in the workflow.
The defined steps will install the required dependencies using composer and PHP extensions. It then runs the linting process, followed by code analysis on the codebase to check for any coding standards violations or errors.
If job fails
- The CI workflow reports issues in the job logs.
- The Pull Request/commit status is updated to indicate that the workflow failed.
- Developers review the errors in the job logs and make necessary code changes and fixes.
If job succeeds
- The Pull Request/commit status is updated to indicate that the workflow succeeded.
All the Workflow runs can be seen and reviewed under the Actions tab of GitHub:
The maintainer can now review the workflow results in the Pull Request itself. If the workflow indicates success, it signifies that the code adheres to coding standards and no violations or errors were found. This reduces the risk of merging code that may cause errors or disrupt the application.
Before merging any changes into the main codebase, it's essential to ensure that the Continuous Integration (CI) checks have been successfully completed. These checks verify that code changes adhere to coding standards, pass tests, and no error is encountered. To enforce this, follow these steps:
-
Review workflow status: When a Pull Request (PR) is created or a push is made, monitor the workflow's progress and results. Ensure that the job(s) complete successfully.
-
Merge only after success: As a maintainer, it's crucial to enforce the policy of merging changes only when the workflow passes without errors. If the workflow fails, work with the contributor to address the issues before proceeding with the merge.
-
Bypass workflow check: In certain scenarios, there may be valid reasons for bypassing the CI checks temporarily. It's recommended that leads add a comment in the PR describing the reason for bypassing the CI checks. This helps maintain a record of the decision and the context behind it.
Please note that bypassing CI checks should be used sparingly and only in exceptional cases. The goal is to maintain code quality and ensure that the CI process is an integral part of our development workflow.
If your Pull Request encounters merge conflicts during the auto-merge stage, manual intervention may be required to resolve the conflicts before the workflow can proceed.
Modify the job steps in the php-lint.yml file to match your specific linting and code analysis commands and any additional requirements of your PHP project.
Explore this for practical demonstration of CI setups.
Setting up a CI workflow for your PHP project offers several benefits:
- Improved code quality through automated linting and code analysis
- Early detection of errors and issues
- Streamlined collaboration through automated testing of Pull Requests and code pushes
Consider enhancing your CI workflow by adding additional jobs and/or steps such as unit testing, integration testing, and deployment to further improve the quality and reliability of your PHP project.