This tutorial shows you how to set up a basic PHP project with Composer, write tests using PHPUnit, and automate test execution with GitHub Actions. It’s intended for developers who want a clean starting point for building and testing PHP code.
You’ll create the project structure, configure Composer, add a simple test case, and define a GitHub Actions workflow to run tests on each push or pull request. By the end, you'll have a fully working setup for local and automated testing.
Setting Up a PHP Project
Before you begin, ensure that PHP and Composer are installed on your computer.
php --version
composer --version
Initialise Your PHP Project
Create a folder for your project.
mkdir conditional-test-execution
cd conditional-test-execution
Initialize a new PHP project by running composer init in your project directory.
composer init
This will create a composer.json file. Ensure that your composer.json has the following structure.
{
"name": "software-witchcraft/conditional-test-execution",
"description": "A small demo project for showcasing conditional PHP test execution in GitHub Actions, created to support a tutorial.",
"type": "project",
"license": "mit",
"autoload": {
"psr-4": {
"SoftwareWitchcraft\\ConditionalTestExecution\\": "src/"
}
},
"authors": [
{
"name": "Software Witchcraft",
"email": "info@softwarewitchcraft.com"
}
],
"require": {}
}
Add PHPUnit as a Dependency
Add PHPUnit via Composer. Run the following command in your project's root directory.
composer require --dev phpunit/phpunit ^12
This command installs PHPUnit and its dependencies. The --dev flag indicates that PHPUnit is a development dependency, not required for the production environment.
Configure PHPUnit
Create a phpunit.xml file in your project root. This file will hold your PHPUnit configuration. Here's a basic example.
<phpunit bootstrap="vendor/autoload.php" colors="true">
<testsuites>
<testsuite name="My Test Suite">
<directory>tests</directory>
</testsuite>
</testsuites>
</phpunit>
In this file, bootstrap points to Composer's autoloader, and the tests directory is where your test files will reside.
Write Your First Test
Create file Greeter.php in your src folder ...
touch ./src/Greeter.php
... with following content
<?php
namespace SoftwareWitchcraft\ConditionalTestExecution;
class Greeter
{
public function greet(string $name): string
{
return 'Hello, ' . $name . '!';
}
}
Create a tests directory in your project root.
mkdir tests
Inside this directory, create a test file, for example, GreeterTest.php ...
touch ./tests/GreeterTest.php
... with a simple PHPUnit test class.
<?php
use PHPUnit\Framework\TestCase;
use SoftwareWitchcraft\ConditionalTestExecution\Greeter;
class GreeterTest extends TestCase
{
public function testGreetsWithName(): void
{
$greeter = new Greeter();
$greeting = $greeter->greet('Alice');
$this->assertSame('Hello, Alice!', $greeting);
}
}
Running Tests Locally
To run your tests, execute the following command in your project root:
./vendor/bin/phpunit --testdox
This command runs all the tests defined in your tests directory. PHPUnit will look for any files ending in Test.php and execute them.
Setup Git Repository and Push Your Project to GitHub
Init you git repository.
git init
Create .gitignore file ...
touch .gitignore
... with following content
/vendor/
/composer.lock
/.phpunit.result.cache
/.idea/
.DS_Store
Add and commit all your changes to your repository.
git add .
git commit -m "initial commit"
Create a repository on GitHub, and link it to your local repository.
git remote add origin git@github.com:yourusername/your-repository-name.git
Don't forget to update yourusername/your-repository-name!
Push your local repository to GitHub.
git push -u origin main
Now that we have our PHP project and PHPUnit setup complete, let's move on to the next section where we will set up GitHub Actions to automate our testing process.
Setting Up the GitHub Actions Environment
To start leveraging GitHub Actions, you need to set up a workflow. A workflow is a set of automated procedures and tasks that are executed based on defined events, like a push or a pull request.
Create a GitHub Actions Workflow File
In your project repository, create directory .github/workflows.
mkdir -p ./.github/workflows
Inside this directory, create a new file named RunTests.yml (or any other name you prefer, but keep the .yml extension).
touch ./.github/workflows/RunTests.yml
Define the Workflow
Start the YAML file with a name for the workflow and specify the trigger events. Commonly, workflows are triggered on push or pull request events. For example:
name: Run unit tests
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Check out repository code
uses: actions/checkout@v4
- name: Install PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.5' # Specify the PHP version
tools: composer:v2, phpunit:v9.6
coverage: none
- name: Check PHP Version
run: php -v
- name: Install dependencies
run: composer install # Install PHP dependencies
- name: Run PHPUnit tests
run: ./vendor/bin/phpunit --testdox # Execute PHPUnit tests
Commit and Push the Workflow File
After setting up the RunTests.yml file, commit it to your repository and push it to GitHub:
git add .github/workflows/phpunit.yml
git commit -m "Add GitHub Actions workflow"
git push origin main
Once you push these changes to GitHub, the Run PHPUnit Tests workflow will be triggered on the next push or pull request to the main branch, automatically running your PHPUnit tests in the specified environment.
You've now set up a complete PHP project with local testing using PHPUnit and automated test execution via GitHub Actions. This setup helps ensure your code stays reliable by catching issues early with every push or pull request. From here, you can continue building features, adding more tests, and extending your CI workflow as needed.
The complete code for this project is available in the GitHub repository. You can explore the structure, test setup, and workflow configuration in one place and use it as a reference or starting point for your own projects.
Top comments (0)