sonar-php

sonar-php is a static code analyzer for the PHP language designed as an extension for the SonarQube platform. It helps developers identify and correct bugs, vulnerabilities, and code smells.

Key Features:

• 200+ built-in rules.
• Support for PHP up to version 8.4.
• Calculation of metrics such as complexity and lines of code.
• Import of unit test and coverage results.
• Support for custom rules.

The CFG construction for try-catch-finally uses several simplifying assumptions:

1. Try Body: The try body is generated as a single block. Both catch and finally blocks are successors of this block. Note: While the CFG treats the body as one block, analysis must account for the fact that any statement within the body could trigger an exception and exit the block early.
2. Missing Finally: If no finally clause is present, the analyzer assumes an empty finally clause exists to maintain graph consistency.
3. Exception Handling: The analyzer assumes any catch clause might fail to handle an exception (even if it catches hrowable or aseException). Consequently, there is always a path from a catch block to the END block via any enclosed finally blocks.

For Loops

The for statement is decomposed into four distinct blocks:

1. Initialization: Variable initialization before the body.
2. Body: The code inside the loop.
3. Update: The increment/decrement step following the body.
4. Condition: The check performed before each iteration.

Switch Statements

switch statements are modeled as a series of if-elseif-else blocks.

Note on PHP behavior: The CFG accounts for the PHP-specific behavior where a continue statement inside a switch block behaves identically to a break statement.

Before running integration tests for the first time, follow these steps:

1. Ensure your Developer Box is properly set up.
2. Configure Orchestrator settings. The only mandatory options are the Artifactory API key and the GitHub token. The GitHub token must be a Personal Access Token (classic) with the repo scope permission and properly configured SSO.
3. Build the test resources (such as custom plugins) by running the build command from the repository root.

./gradlew :its:build

To build the project and run unit tests, ensure you have configured the build dependencies first.

1. Configure build dependencies:

git submodule update --init -- build-logic/common

Tip: To always get the latest build logic during git operations, run git config submodule.recurse true.

2. Build the project and run unit tests: Execute this from the project root:

./gradlew build

You can debug the Scanner during an integration test by setting the SONAR_SCANNER_DEBUG_OPTS environment variable. This configuration instructs the scanner to wait for a remote debug session to start at the specified port.

SonarScanner scanner = SonarScanner.create("projectDir")
    .setEnvironmentVariable("SONAR_SCANNER_DEBUG_OPTS", "-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=<port>");
 
ORCHESTRATOR.executeBuild(scanner);

The project uses spotless for formatting checks during the Gradle build. If your build fails due to formatting, you can check the status manually or apply fixes automatically.

Check formatting status:

./gradlew spotlessCheck

Apply formatting fixes:

./gradlew spotlessApply

To use Maven instead of Gradle, you must replace the build.gradle.kts file with the maven/pom.xml file. Note that when using Maven, you must manually build the plugin dependency by publishing it to your local Maven repository first.

# First, publish the dependency to your local Maven repository
./gradlew publishToMavenLocal

# Then proceed with your Maven build using maven/pom.xml

To ensure reproducible builds when dependencies change (e.g., after updating build.gradle.kts or gradle/libs.versions.toml), regenerate all Gradle lock files using:

./gradlew writeAllLockFiles --write-locks

To provide the SonarPHP analyzer with the necessary data for processing, you must generate both a JUnit log and a Clover coverage report using PHPUnit. This requires Xdebug to be enabled in coverage mode.

Requirements

• PHP 8.*
• Composer 2.*
• Xdebug

Steps to generate reports

1. Enable Xdebug coverage mode: Set the XDEBUG_MODE environment variable to coverage.
2. Run PHPUnit: Execute the test suite and specify the output paths for the Clover coverage and JUnit log files.

Note: The analyzer expects these reports to contain absolute paths.

# 1. Enable coverage generation
export XDEBUG_MODE=coverage

# 2. Run PHPUnit to create reports
vendor/bin/phpunit tests \
--coverage-clover=reports/phpunit.coverage.local.xml \
--log-junit=reports/phpunit.tests.local.xml