SonarQubeでコード品質を分析する方法｜WordPressのテーマ・プラグインをDockerで解析して結果を読むまで

SonarQube は、ソースコードを静的に解析して、不具合につながる書き方、セキュリティ上の注意点、重複コード、テストのカバレッジなどを一覧にしてくれるツールです。この記事では、自分で管理するサーバーやローカル環境に Docker で SonarQube を立て、WordPress のテーマやプラグインを解析し、結果を読んで直すところまでを説明します。あわせて、WordPress 固有のルールは SonarQube だけでは足りないため、PHPCS（WordPress Coding Standards）や PHPStan とどう組み合わせるかも扱います。

SonarQube の種類と、この記事で使うもの

SonarQube は 2024 年後半に名称が整理され、無償で自分でホストする「SonarQube Community Build」、有償の自己ホスト版「SonarQube Server」、クラウドサービスの「SonarQube Cloud」（旧 SonarCloud）に分かれています（2026年10月現在）。この記事では Community Build を使います。

Community Build でも PHP、JavaScript、CSS などの解析はできますが、ブランチごとの解析やプルリクエストへの結果表示、外部からの入力が危険な処理に届くかを追跡する解析（テイント解析）などは有償版の機能とされています。どの機能がどの版に含まれるかは変わることがあるため、導入前に公式サイトの比較表を確認してください。

Docker Compose で起動する

SonarQube は内部で検索エンジン（Elasticsearch 系）を使うため、ホスト側のカーネル設定が足りないと起動直後に停止します。先にホストで次の設定を行います。

# 一時的に設定
sudo sysctl -w vm.max_map_count=524288
sudo sysctl -w fs.file-max=131072
# 再起動後も維持する場合
echo -e "vm.max_map_count=524288\nfs.file-max=131072" | sudo tee /etc/sysctl.d/99-sonarqube.conf

データベースは、評価用の組み込みデータベースではなく PostgreSQL を使います。組み込みデータベースは試用向けで、アップグレードや移行ができないためです。

# compose.yaml
services:
  sonarqube:
    image: sonarqube:community
    depends_on:
      - db
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: ${SONAR_DB_PASSWORD}
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
    ports:
      - "127.0.0.1:9000:9000"
    ulimits:
      nofile:
        soft: 131072
        hard: 131072
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: ${SONAR_DB_PASSWORD}
      POSTGRES_DB: sonar
    volumes:
      - postgresql_data:/var/lib/postgresql/data
volumes:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:
  postgresql_data:

SONAR_DB_PASSWORD は同じディレクトリの .env に書き、そのファイルを Git に含めないようにします。ポートを 127.0.0.1 に限定しているのは、SonarQube の画面をインターネットに直接公開しないためです。外部から使う場合は、HTTPS を設定したリバースプロキシや VPN を経由してください。対応する PostgreSQL のバージョンは SonarQube のバージョンごとに決まっているので、公式ドキュメントの要件を確認してから選びます。

docker compose up -d で起動し、docker compose logs -f sonarqube で起動完了のメッセージを待ちます。メモリは数GB単位で使うため、小さな VPS では WordPress と同居させず、手元の PC や別のサーバーで動かすほうが安全です。

初期設定とトークンの作成

ブラウザーで http://127.0.0.1:9000 を開き、初期の管理者アカウントでログインします。初回ログイン時にパスワードの変更を求められるので、推測されにくいものに変えてください。

次にプロジェクトを作成します。リポジトリとの連携を使わない場合は、ローカルのプロジェクトとして手動で作成し、プロジェクトキー（例: my-theme）を決めます。続いて解析用のトークンを発行します。トークンはパスワードと同じ扱いで、画面に表示されたときに控え、リポジトリや共有のドキュメントには書かないでください。画面の項目名は版によって変わるため、プロジェクトの作成画面の案内に沿って進めます。

解析の設定ファイルを置く

テーマやプラグインのリポジトリの直下に sonar-project.properties を置きます。

sonar.projectKey=my-theme
sonar.projectName=My Theme
sonar.sources=.
sonar.sourceEncoding=UTF-8
sonar.exclusions=vendor/**,node_modules/**,build/**,dist/**,**/*.min.js,**/*.min.css

# PHPUnit のカバレッジとテスト結果（出力している場合）
sonar.php.coverage.reportPaths=build/coverage/clover.xml
sonar.php.tests.reportPath=build/phpunit-junit.xml

# PHPStan の結果を取り込む（JSON 形式で出力している場合）
sonar.php.phpstan.reportPaths=build/phpstan.json

除外の設定が最も大切です。vendor や node_modules、ビルド済みの圧縮ファイルを解析対象に含めると、自分で書いていないコードの問題が大量に表示され、本当に直すべき指摘が埋もれます。カバレッジや PHPStan の結果は、それぞれのツールで先に出力しておく必要があります（PHPStan は --error-format=json で JSON を出力できます）。

スキャナーを実行する

解析はスキャナーと呼ばれる別のプログラムで行います。Docker のイメージを使うと、Java などを手元に入れずに実行できます。

cd /path/to/my-theme
export SONAR_TOKEN="your-sonar-token"
docker run --rm --network host \
  -e SONAR_HOST_URL="http://127.0.0.1:9000" \
  -e SONAR_TOKEN \
  -v "$(pwd):/usr/src" \
  sonarsource/sonar-scanner-cli

--network host は Linux で同じホストの SonarQube に接続するための指定です。Docker Desktop を使っている場合は、SONAR_HOST_URL を http://host.docker.internal:9000 に変え、--network host を外します。トークンはコマンドラインに直接書くとシェルの履歴に残るため、環境変数で渡しています。CI で実行する場合は、CI のシークレット機能に登録してください。

結果を読む

解析が終わると、プロジェクトの画面に結果が表示されます。最初に見るのは次の項目です。

• 品質ゲート（Quality Gate）: 合格か不合格かの判定です。標準の「Sonar way」では、主に「新しく書いたコード」に対して条件が設定されています。既存の古いコードに問題が多くても、新しい変更で問題を増やしていなければ合格になる考え方です。
• 新しいコードと全体のコード: 新しいコードの範囲（前回のバージョンからの変更、一定日数以内の変更など）はプロジェクトの設定で変えられます。最初の解析では全体の数字に驚きがちですが、まずは新しいコードを基準に運用すると負担が少なくなります。
• Issues（指摘）: 信頼性、保守性、セキュリティなどの観点で分類され、重大度が付いています。重大度の高いものから確認します。
• セキュリティホットスポット: 「脆弱性がある」という判定ではなく、「人が確認すべき箇所」という意味です。確認して問題がなければ、安全と判断した理由を残して状態を変更します。
• 重複とカバレッジ: 重複が多いテンプレートファイルは、テンプレートパーツや関数への切り出しを検討します。

WordPress のコードで注意すること

SonarQube の標準ルールは一般的な PHP を前提にしているため、WordPress のコードでは合わない指摘が出ることがあります。たとえば、関数名や変数名の命名規則のルールが WordPress のスネークケースと合わない、テンプレートファイルの書き方が「複雑すぎる」と判定される、といったものです。

こうした場合は、標準の品質プロファイル（Quality Profile）を直接編集するのではなく、複製して自分用のプロファイルを作り、合わないルールを無効化してプロジェクトに割り当てます。標準のプロファイルはアップグレード時に更新されるため、複製してから変更するほうが管理しやすくなります。

一方で、WordPress 特有のセキュリティ上の確認、つまり出力時のエスケープ（esc_html() など）、nonce の検証、入力のサニタイズは、SonarQube の標準ルールでは十分に確認できません。これらは PHPCS と WordPress Coding Standards の WordPress.Security.EscapeOutput、WordPress.Security.NonceVerification、WordPress.Security.ValidatedSanitizedInput などのルールで確認します。役割分担の目安は次のとおりです。

• PHPCS（WordPress Coding Standards）: WordPress の書き方とセキュリティ上の作法
• PHPStan: 型やメソッドの呼び出しの誤り（WordPress の関数を認識させる拡張と組み合わせる）
• SonarQube: 不具合につながりやすい書き方、複雑さ、重複、カバレッジの推移をプロジェクト単位で継続的に追う

CI に組み込む

手動の解析に慣れたら、プッシュのたびに解析する設定に進みます。GitHub Actions には SonarSource が提供する公式のアクションがあり、トークンとサーバーの URL をシークレットとして渡して使います。アクションの名前や推奨の設定は更新されることがあるため、公式ドキュメントの最新の例を参照してください。

スキャナーに sonar.qualitygate.wait=true を指定すると、品質ゲートの判定が出るまで待ち、不合格ならスキャナーが失敗として終了します。これを使うと、品質ゲートに通らない変更を CI の段階で止められます。ただし Community Build ではブランチやプルリクエストごとの解析が制限されるため、どのブランチで解析するかは運用に合わせて決めてください。

SonarQube 本体も定期的に更新が出ます。更新の前には PostgreSQL のバックアップを取り、リリースノートで移行手順を確認してから行います。

まとめ

• 自己ホストなら SonarQube Community Build を Docker Compose と PostgreSQL で動かす。ホストの vm.max_map_count の設定を先に行う
• 画面は 127.0.0.1 に限定し、外部から使うなら HTTPS のリバースプロキシや VPN を通す。トークンはシークレットとして扱う
• sonar-project.properties で vendor などを除外しないと、本当に直すべき指摘が埋もれる
• 品質ゲートは新しいコードを基準に運用し、セキュリティホットスポットは人が確認して理由を残す
• WordPress 特有のエスケープや nonce の確認は PHPCS（WordPress Coding Standards）で行い、SonarQube と役割を分ける

• PHPStan で WordPress のコード品質を上げる方法
• GitHub Actions で CI/CD を構築する方法