How to validate PHP code in GitHub Actions? #191801

jcubic · 2026-04-07T14:49:28Z

jcubic
Apr 7, 2026

ideepakchauhan7 · 2026-04-07T15:51:09Z

ideepakchauhan7
Apr 7, 2026

The most reliable way to validate PHP syntax in GitHub Actions is to use php -l (lint mode) — it checks for syntax errors without executing the script, so you're not fighting the built-in server's misleading 200 responses.

To lint a single file:

- name: Validate PHP syntax
  run: php -l path/to/your/script.php

To lint all PHP files recursively:

- name: Validate PHP syntax
  run: find . -name "*.php" -not -path "./vendor/*" | xargs -I{} php -l {}

php -l exits with a non-zero code on any syntax error, which will correctly fail the workflow and block the deployment.

Full example workflow:

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'

      - name: Validate PHP syntax
        run: find . -name "*.php" -not -path "./vendor/*" | xargs -I{} php -l {}

      - name: Deploy via SSH
        run: ssh user@yourserver "cd /var/www && git pull"

Why not the built-in server? php -S is meant for local dev and does not surface fatal parse errors as HTTP errors — it's not suitable for CI validation. php -l is purpose-built for exactly this use case.

If you also want to catch runtime/logic issues beyond syntax, consider adding PHPStan or Psalm as a next step.

1 reply

jcubic Apr 7, 2026
Author

php -l will only give you errors about syntax errors. This is what AI gives me, which is not a good solution. There are multiple errors you can get from the code that are not syntax errors but logic errors. but I will check if I can use this action to detect 500 errors.

Gecko51 · 2026-04-18T20:35:53Z

Gecko51
Apr 18, 2026

You're right that php -l only catches syntax. To catch logic issues (undefined variables, wrong method calls, type mismatches, unreachable code) you want a static analyzer plus real request-level smoke tests. php -S will never give you this because it sends 200 with a "Parse error" HTML body when things break, which is exactly what you hit.

Here's a layered CI that actually fails when the code is broken:

name: Validate PHP
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
      -         with:
      -           php-version: '8.2'
      -           coverage: none
      -           tools: composer, phpstan
      - name: Syntax check
      -         run: find . -name "*.php" -not -path "./vendor/*" -print0 | xargs -0 -n1 -P4 php -l
      - name: Install deps
      -         run: composer install --no-interaction --prefer-dist
      - name: Static analysis (PHPStan)
      -         run: vendor/bin/phpstan analyse --no-progress --level=5 src/
      - name: Smoke-test endpoints
      -         run: |
      -           php -S 127.0.0.1:8000 -t public/ > server.log 2>&1 &
      -           SERVER_PID=$!
      -           sleep 2
      -           for route in / /health /api/users; do
      -             BODY=$(curl -sS "http://127.0.0.1:8000$route")
      -             if echo "$BODY" | grep -qiE "parse error|fatal error|uncaught|warning:"; then
      -               echo "::error::Broken response on $route"
      -               echo "$BODY"
      -               kill $SERVER_PID
      -               exit 1
      -             fi
      -           done
      -           kill $SERVER_PID
      - ```
The trick for the built-in server is grepping the response body, not the HTTP code. The 200 you're seeing is the server saying "I replied", not "the script worked". Fatal errors get printed into the response body with words like "Parse error" or "Fatal error", so you match on those (with `display_errors=On`, which is the default in the built-in server).

PHPStan at level 5 or 6 catches the class of bugs you're after: typos in method names, calling things on nulls, wrong argument counts. Psalm does the same. Either needs `composer install` to have run first so it can see your classes.

If you have a test suite, add `vendor/bin/phpunit` before the smoke test. That's where you actually catch business-logic bugs. Static analysis and syntax checks only catch a subset of them.

One more thing: the warnings you quoted ("PHP error detection is completely broken on this runner") read like AI output rather than real PHP output. The runner is fine, `php -l` and `phpstan` behave the same on GitHub runners as they do locally. If you share the exact step that produced those, I can help narrow it down further.

1 reply

jcubic Apr 18, 2026
Author

I was using something similar, but it was not working on GitHub workflow. It was working locally, though.

Gecko51 · 2026-04-21T11:06:01Z

Gecko51
Apr 21, 2026

"Works locally but not in Actions" on PHP is almost always one of three things:

Missing composer install before the lint/analysis step. Your autoloader isn't present in CI, so any analyzer doing class/function resolution trips on your own code with "unknown symbol" errors. Locally you already have vendored deps installed, so you never see it.
PHP version mismatch. shivammathur/setup-php@v2 uses whatever version you pin. If your local is 8.3 and CI defaults to something older, syntax and runtime behavior differ. Pin the version explicitly in the workflow and match your production server.
Runtime error display differs. PHP's built-in server (php -S) on the Ubuntu runner happily returns HTTP 200 with a "Parse error" HTML body when something breaks at runtime. Your local PHP-FPM or Apache probably returns 500 because of a different display_errors / error_log config. That's why your HTTP-code check fails on CI but works locally.

For logic-level validation (undefined vars, wrong method calls, type mismatches, unreachable code) you want static analysis, not the built-in server. PHPStan is the go-to:

- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    coverage: none
- run: composer install --no-progress --prefer-dist
- run: vendor/bin/phpstan analyse --no-progress --error-format=github

Minimal phpstan.neon at the repo root:

parameters:
  level: 6
  paths:
    - src
    - public

It exits non-zero on any reported issue and surfaces them inline on the PR thanks to --error-format=github. Start at level 4-5 on an existing codebase, then ratchet up.

For runtime smoke tests (to catch 500s hidden behind 200s from the built-in server), assert on the response body, not the status code:

- name: Smoke test
  run: |
    php -S localhost:8000 -t public &
    sleep 2
    response=$(curl -s http://localhost:8000/index.php)
    echo "$response"
    echo "$response" | grep -qiE "parse error|fatal error|warning:" && exit 1 || exit 0

That grep catches the hidden errors the built-in server swallows. Pair that with PHPStan and you get both "logic is sane" and "runtime doesn't explode" checks.

If you can share the workflow yaml and the output of the failing step, happy to tell you what's different between CI and your local run.

1 reply

jcubic Apr 21, 2026
Author

I created a syntax error to see if the job would fail. I was not able to trigger the error. It always succeeded.

Gecko51 · 2026-04-21T20:21:38Z

Gecko51
Apr 21, 2026

"I created a syntax error to see if the job would fail. I was not able to trigger the error."

That's the key thing to debug. If php -l isn't catching a syntax error you introduced, one of two things is happening:

The glob isn't matching the file you edited. Run this in your workflow to verify:

- name: Debug - list PHP files found
  run: find . -name "*.php" -not -path "./vendor/*"

If your broken file doesn't appear in the output, the find isn't reaching it (wrong path, or the file is nested somewhere excluded).

The step is swallowing the exit code. Check if you have continue-on-error: true on the lint step, or if you're piping through something that resets $?. A pipe through xargs can also eat exit codes in some shells. Use this form instead which fails reliably:

- name: Validate PHP syntax
  run: |
    find . -name "*.php" -not -path "./vendor/*" -print0       | xargs -0 -n1 php -l
    echo "Exit: $?"

Or even simpler to test: just hardcode the broken file directly:

- name: Test lint
  run: php -l path/to/your/broken_file.php

If that doesn't fail either, post the exact error message you put in the file and the step output. At that point it's something specific to your runner setup.

1 reply

jcubic Apr 22, 2026
Author

I don't use php -l because it will not detect logic errors. In order to find logic errors (runtime errors). You need to run the code. And I have a problem with running the code, not with the linter.

AbhinavPabbaraju · 2026-04-21T22:57:52Z

AbhinavPabbaraju
Apr 21, 2026

The issue here is not that PHP validation is “broken” on GitHub Actions — it’s that the validation strategy is incorrect.

You’re currently relying on:

HTTP response codes from PHP’s built-in server

That approach is fundamentally unreliable because:

PHP’s built-in server returns 200 even for fatal errors
Errors are often emitted to stderr, not HTTP output
You’re testing runtime behavior indirectly instead of validating code itself

Correct approach: validate PHP at multiple layers

You should treat validation as three independent checks:

1. Syntax validation (fast + mandatory)

Use PHP’s built-in linter:

- name: PHP Lint
  run: find . -name "*.php" -exec php -l {} \;

This will:

catch parse errors
fail the workflow immediately if syntax is invalid

2. Static analysis (catches real bugs)

Add tools like:

phpstan (recommended)
psalm (alternative)

Example:

- name: Install dependencies
  run: composer install --no-progress --prefer-dist

- name: Run PHPStan
  run: vendor/bin/phpstan analyse

This catches:

type errors
undefined variables
incorrect method usage

3. Runtime validation (actual behavior)

Instead of relying on HTTP status, explicitly fail on errors:

- name: Run PHP script with strict error handling
  run: |
    php -d display_errors=1 -d log_errors=1 -d error_reporting=E_ALL script.php

OR better — write proper tests:

- name: Run PHPUnit
  run: vendor/bin/phpunit

Why your current method fails

Your current pipeline:

“start PHP server → curl → check HTTP 200”

Problems:

HTTP 200 ≠ correct execution
Fatal errors don’t necessarily propagate to HTTP status
Logs may not be captured in Actions runner

So even broken code can appear “successful”.

Recommended CI structure

A proper pipeline should look like:

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.2

      - name: Install dependencies
        run: composer install --no-progress

      - name: Lint
        run: find . -name "*.php" -exec php -l {} \;

      - name: Static Analysis
        run: vendor/bin/phpstan analyse

      - name: Tests
        run: vendor/bin/phpunit

Then only deploy if all steps pass.

Key takeaway

You don’t validate PHP by checking HTTP responses.

You validate it by:

Parsing correctness (lint)
Logical correctness (static analysis)
Behavior correctness (tests)

Bonus (production-grade)

If you want this to be bulletproof:

fail on warnings: -d error_reporting=E_ALL
convert warnings to exceptions
enforce coverage thresholds in PHPUnit

0 replies

Sunbelt Computer Software

PL/B Language Development and Support

GitHub Community

How to validate PHP code in GitHub Actions? #191801

Uh oh!

jcubic Apr 7, 2026

🏷️ Discussion Type

💬 Feature/Topic Area

Discussion Details

Replies: 5 comments · 4 replies

Uh oh!

ideepakchauhan7 Apr 7, 2026

Uh oh!

Uh oh!

jcubic Apr 7, 2026 Author

Uh oh!

Gecko51 Apr 18, 2026

Uh oh!

jcubic Apr 18, 2026 Author

Uh oh!

Gecko51 Apr 21, 2026

Uh oh!

jcubic Apr 21, 2026 Author

Uh oh!

Gecko51 Apr 21, 2026

Uh oh!

jcubic Apr 22, 2026 Author

Uh oh!

AbhinavPabbaraju Apr 21, 2026

Correct approach: validate PHP at multiple layers

1. Syntax validation (fast + mandatory)

2. Static analysis (catches real bugs)

3. Runtime validation (actual behavior)

Why your current method fails

Recommended CI structure

Key takeaway

Bonus (production-grade)

jcubic
Apr 7, 2026

Replies: 5 comments 4 replies

ideepakchauhan7
Apr 7, 2026

jcubic Apr 7, 2026
Author

Gecko51
Apr 18, 2026

jcubic Apr 18, 2026
Author

Gecko51
Apr 21, 2026

jcubic Apr 21, 2026
Author

Gecko51
Apr 21, 2026

jcubic Apr 22, 2026
Author

AbhinavPabbaraju
Apr 21, 2026