CI/CD Pipeline and Cross-Version Testing

Purpose and Scope

This document describes the Continuous Integration and Continuous Deployment (CI/CD) infrastructure for the php-bolt-driver library, focusing on the GitHub Actions workflows that validate the library across multiple database versions and PHP versions. The testing strategy ensures compatibility with Neo4j versions 4.4 through 2025, alternative graph databases (Memgraph, NornicDB), and PHP versions 8.2 through 8.5.

For information about the test architecture and organization, see Test Architecture and Organization. For details about specific test types, see Unit and Protocol Testing and Integration Testing.

GitHub Actions Workflow Architecture

The CI/CD pipeline consists of six GitHub Actions workflows that execute in parallel when pull requests are opened or updated. Each workflow targets specific database environments and PHP version combinations.

Sources: .github/workflows/no-db.yml3-6 .github/workflows/neo4j.4.4.yml3-6 .github/workflows/neo4j.5.yml3-6 .github/workflows/neo4j.2025.yml3-6 .github/workflows/memgraph.yml3-6 .github/workflows/nornicdb.yml3-6

Workflow Trigger Configuration

All workflows share identical trigger conditions:

Configuration	Value	Purpose
Event	pull_request	Trigger on PR activity
Types	opened, synchronize, reopened, ready_for_review	Execute on PR updates
Branches	master	Only for master branch PRs
Draft Check	if: ${{ github.event.pull_request.draft == false }}	Skip draft PRs

Sources: .github/workflows/no-db.yml3-10 .github/workflows/neo4j.4.4.yml3-10 .github/workflows/neo4j.5.yml3-10

Matrix Testing Strategy

The library employs a comprehensive matrix testing strategy to validate compatibility across multiple dimensions: database versions and PHP versions.

Neo4j Version Coverage

Sources: .github/workflows/neo4j.4.4.yml13-17 .github/workflows/neo4j.5.yml13-17 .github/workflows/neo4j.2025.yml13-17

Matrix Configuration Details

Neo4j 5.x Workflow (Largest Matrix)

This configuration creates 7 × 4 = 28 parallel jobs. The fail-fast: false setting ensures all jobs run to completion even if some fail, providing comprehensive test results across all combinations.

Sources: .github/workflows/neo4j.5.yml13-17

Alternative Database Workflows

Alternative graph databases use simplified configurations without matrix expansion:

Workflow	Database	PHP Version	Test Suite
memgraph.yml	Memgraph (latest)	8.5 only	Memgraph
nornicdb.yml	NornicDB (timothyswt/nornicdb-amd64-cpu)	8.5 only	NornicDB

Sources: .github/workflows/memgraph.yml1-36 .github/workflows/nornicdb.yml1-40

Test Suite Configuration

The phpunit.xml configuration file defines four distinct test suites, each targeting different testing scenarios:

Sources: phpunit.xml3-22

Test Suite Mapping

Test Suite	Workflow	Purpose	Database Required
Neo4j	neo4j.4.4.yml, neo4j.5.yml, neo4j.2025.yml	Full integration testing	Yes (Neo4j)
NoDatabase	no-db.yml	Protocol and cache unit tests	No
Memgraph	memgraph.yml	Memgraph compatibility	Yes (Memgraph)
NornicDB	nornicdb.yml	NornicDB compatibility	Yes (NornicDB)

Sources: phpunit.xml4-21

Service Container Configuration

Each database workflow configures a service container to provide the graph database instance. The configurations vary by database type:

Neo4j Service Configuration

Key aspects:

• Dynamic image versioning: Uses matrix variable for version selection
• Authentication: Credentials set via NEO4J_AUTH environment variable
• APOC plugin: Automatically installed for extended functionality
• Health check: Verifies HTTP endpoint availability before test execution

Sources: .github/workflows/neo4j.5.yml19-29 .github/workflows/neo4j.2025.yml19-29

Neo4j 4.4 Special Configuration

Neo4j 4.4 uses a different plugin configuration syntax:

Note: Password is nothing instead of nothing123, and uses NEO4JLABS_PLUGINS with apoc-core.

Sources: .github/workflows/neo4j.4.4.yml22-24

Memgraph and NornicDB Service Configuration

Sources: .github/workflows/memgraph.yml14-18 .github/workflows/nornicdb.yml14-21

Workflow Execution Steps

Each workflow follows a consistent execution pattern across all database configurations:

Sources: .github/workflows/neo4j.5.yml31-50 .github/workflows/no-db.yml18-34

Step-by-Step Breakdown

1. Repository Checkout

Sources: .github/workflows/neo4j.5.yml32-33

2. PHP Environment Setup

Key configurations:

• Extensions: mbstring (required), sockets (required for Socket connection class)
• Coverage: xdebug enabled for code coverage analysis
• ini-values: Unlimited execution time for long-running tests (e.g., PerformanceTest)

Sources: .github/workflows/neo4j.5.yml35-41

3. Dependency Installation

The --no-progress flag suppresses progress bar output for cleaner CI logs.

Sources: .github/workflows/neo4j.5.yml43-44

4. Test Execution

Environment variables:

• GDB_USERNAME: Database username (accessed via $GLOBALS['NEO_USER'] in tests)
• GDB_PASSWORD: Database password (accessed via $GLOBALS['NEO_PASS'] in tests)

Sources: .github/workflows/neo4j.5.yml46-50 tests/BoltTest.php33

NoDatabase Workflow Differences

The no-db.yml workflow omits service containers and database credentials:

Sources: .github/workflows/no-db.yml33-34

PHP Version Support Matrix

All workflows except Memgraph and NornicDB test against four PHP versions:

PHP Version	Status	First Supported	Notes
8.2	Active	Stable	Minimum supported version
8.3	Active	Stable	Current stable
8.4	Active	Latest stable	Recently added
8.5	Development	RC/Alpha	Future compatibility testing

Rationale: The library keeps up with PHP supported versions as documented in README.md47

Sources: .github/workflows/neo4j.5.yml17 .github/workflows/no-db.yml16 README.md47

Alternative Database PHP Configuration

Memgraph and NornicDB workflows test only PHP 8.5:

This simplified configuration focuses on validating compatibility with the latest PHP features and ensures alternative databases work with cutting-edge PHP versions.

Sources: .github/workflows/memgraph.yml25-30 .github/workflows/nornicdb.yml27-33

Database-Specific Test Implementation

Neo4j Test Structure

The primary test file BoltTest.php implements comprehensive protocol testing:

Test dependencies: Tests use PHPUnit's @depends annotation to chain tests and reuse protocol instances, improving efficiency.

Sources: tests/BoltTest.php17-204

NornicDB Test Structure

Key differences:

• Uses protocol version '4.4.4' specifically for NornicDB compatibility
• Authentication scheme: 'none' (no credentials required)
• Tests focus on core graph structures: Node, Relationship, Path

Sources: tests/NornicDBTest.php17-176

Memgraph Test Structure

Unique features:

• Protocol version negotiation: 5.2, 4.3, 4.1, 4.0 in priority order
• Conditional authentication: Uses logon() for v5.2+, hello() for older versions
• Data provider testing for temporal structures: Duration, Date, LocalTime, LocalDateTime

Sources: tests/MemgraphTest.php24-153

Total Test Job Matrix

The complete CI/CD pipeline executes the following job distribution:

Workflow	Database Versions	PHP Versions	Total Jobs
no-db.yml	N/A	4	4
neo4j.4.4.yml	1	4	4
neo4j.5.yml	7	4	28
neo4j.2025.yml	2	4	8
memgraph.yml	1	1	1
nornicdb.yml	1	1	1
Total	46 jobs

Critical insight: The Neo4j 5.x workflow accounts for 28 of 46 total jobs (61%), reflecting Neo4j's position as the primary target database and the library's commitment to comprehensive version coverage.

Sources: .github/workflows/neo4j.5.yml15-17 .github/workflows/neo4j.4.4.yml15-17 .github/workflows/neo4j.2025.yml15-17

Test Environment Variables

Tests access database credentials through PHPUnit globals defined in phpunit.xml:

These are overridden by workflow environment variables:

Test access pattern:

Sources: phpunit.xml23-26 .github/workflows/neo4j.5.yml47-49 tests/BoltTest.php33

Workflow Optimization Strategies

Parallel Execution

The fail-fast: false configuration ensures independent job execution:

Benefit: Even if Neo4j 5.4 + PHP 8.2 fails, all other 27 combinations complete, providing maximum test coverage visibility.

Sources: .github/workflows/neo4j.5.yml13-17

Runner Selection

All workflows use Ubuntu 22.04 LTS for consistency:

Exception: The no-db.yml workflow runs on ubuntu-latest since no database-specific compatibility is required.

Sources: .github/workflows/neo4j.5.yml11 .github/workflows/no-db.yml11

Dependency Caching

Composer automatically caches dependencies between runs when using the same PHP version, reducing installation time for subsequent workflow executions.

Sources: .github/workflows/neo4j.5.yml43-44

Test Execution Output

Success Response Structure

Tests verify successful operations using signature matching:

Sources: tests/NornicDBTest.php6-37

Generator-Based Response Handling

Multiple workflows use iterator patterns for response processing:

Sources: tests/BoltTest.php97-105

Maintenance and Updates

Adding New Database Versions

To add a new Neo4j version to the test matrix:

1. Update the matrix.neo4j-version array in the appropriate workflow file
2. Verify authentication requirements (password, plugin syntax)
3. Ensure service container health check compatibility

Example for adding Neo4j 5.27:

Sources: .github/workflows/neo4j.5.yml16

Adding New PHP Versions

To add PHP 8.6 when released:

Note: Verify PHP extension availability (mbstring, sockets) in shivammathur/setup-php for new versions.

Sources: .github/workflows/neo4j.5.yml17 .github/workflows/neo4j.5.yml39

Workflow File Version Management

Action versions are periodically updated:

Action	Current Version	Purpose
actions/checkout	@v4	Repository checkout
shivammathur/setup-php	@v2	PHP environment setup

Newer workflows use @v6 for actions/checkout, indicating incremental updates.

Sources: .github/workflows/memgraph.yml22 .github/workflows/neo4j.5.yml32