What causes "--%s-- is not a valid PHPT section" in sebastianbergmann/phpunit?

Fix the header so it matches a section PHPUnit knows: code sections FILE, FILEEOF, FILE_EXTERNAL; expectations EXPECT, EXPECT_EXTERNAL, EXPECTF, EXPECTF_EXTERNAL, EXPECTREGEX, EXPECTREGEX_EXTERNAL; plus TEST, INI, ENV, SKIPIF, XFAIL, CLEAN, STDIN, ARGS.

sebastianbergmann/phpunit · error · UnknownPhptSectionException

--%s-- is not a valid PHPT section

Error message

--%s-- is not a valid PHPT section

What it means

Phpt\Parser::parse() scans a .phpt file line by line; any line matching /^--([_A-Z]+)--/ is treated as a section header. When the captured name is in none of the SUPPORTED_SECTIONS, UNSUPPORTED_SECTIONS or IGNORED_SECTIONS constants, UnknownPhptSectionException('--%s-- is not a valid PHPT section') is thrown and the file is rejected before it can run. PHPUnit only understands its documented PHPT section set.

Source

Thrown at src/Runner/Phpt/Parser.php:129

        $lines = @file($phptFile);

        if ($lines === false) {
            throw new CannotLoadPhptFileException;
        }

        $lineNr = 0;

        foreach ($lines as $line) {
            $lineNr++;

            if (preg_match('/^--([_A-Z]+)--/', $line, $result) === 1) {
                $section = $result[1];

                if (!in_array($section, self::SUPPORTED_SECTIONS, true) &&
                    !in_array($section, self::UNSUPPORTED_SECTIONS, true) &&
                    !in_array($section, self::IGNORED_SECTIONS, true)) {
                    throw new UnknownPhptSectionException($section);
                }

                if (isset($sections[$section])) {
                    throw new DuplicatePhptSectionException($section);
                }

                $sections[$section]             = '';
                $sections[$section . '_offset'] = (string) $lineNr;

                continue;
            }

            if ($section === '') {
                throw new InvalidPhptFileException(
                    sprintf(
                        'PHPT file must not contain text before its first section (line %d)',
                        $lineNr,
                    ),

View on GitHub (pinned to f123cdb2a2)

Solutions

Fix the header so it matches a section PHPUnit knows: code sections FILE, FILEEOF, FILE_EXTERNAL; expectations EXPECT, EXPECT_EXTERNAL, EXPECTF, EXPECTF_EXTERNAL, EXPECTREGEX, EXPECTREGEX_EXTERNAL; plus TEST, INI, ENV, SKIPIF, XFAIL, CLEAN, STDIN, ARGS.
Remove the custom section if it carries no meaning for PHPUnit; free-form description text belongs in --TEST-- or --DESCRIPTION-- (the latter is ignored).
Upgrade PHPUnit — newer releases may recognize sections older versions reject as unknown.

Example fix

-- before
--FILE--
echo 'Hello';
--EXCEPT--
Hello

-- after
--FILE--
echo 'Hello';
--EXPECT--
Hello

Defensive patterns

Strategy: validation

Validate before calling

function assertKnownPhptSections(string $phptFile): void
{
    $known = ['TEST','FILE','FILEEOF','FILE_EXTERNAL','EXPECT','EXPECT_EXTERNAL',
        'EXPECTF','EXPECTF_EXTERNAL','EXPECTREGEX','EXPECTREGEX_EXTERNAL',
        'INI','ENV','SKIPIF','XFAIL','CLEAN','STDIN','ARGS',
        'CGI','COOKIE','DEFLATE_POST','EXPECTHEADERS','EXTENSIONS','GET',
        'GZIP_POST','HEADERS','PHPDBG','POST','POST_RAW','PUT','REDIRECTTEST','REQUEST',
        'CAPTURE_STDIO','CONFLICTS','CREDITS','DESCRIPTION','FLAKY',
        'WHITESPACE_SENSITIVE','XLEAK'];

    foreach (file($phptFile) as $i => $line) {
        if (preg_match('/^--([_A-Z]+)--/', $line, $m) === 1 && !in_array($m[1], $known, true)) {
            throw new RuntimeException(sprintf('Unknown section --%s-- at line %d', $m[1], $i + 1));
        }
    }
}

Try / catch

try {
    $sections = (new \PHPUnit\Runner\Phpt\Parser())->parse($phptFile);
} catch (\PHPUnit\Runner\Phpt\UnknownPhptSectionException $e) {
    // report the offending section name ($e->getMessage()) and skip/repair the file
}

Prevention

Run a PHPT lint step in CI that checks every header against the supported/unsupported/ignored lists before executing the suite.
Create new .phpt files from a tested template containing only known sections.
After copying upstream PHPT tests, diff their section headers against PHPUnit's documented set.

When it happens

Trigger: A .phpt file containing a section header PHPUnit does not know at all: a typo such as --EXCEPT-- instead of --EXPECT--, a custom section like --MY_SECTION--, or a section introduced by a newer php run-tests.php than this PHPUnit version recognizes.

Common situations: Copying PHPT tests from php/php-src or PECL into a PHPUnit-driven suite; typos while hand-writing section headers; using a newer PHP run-tests format on an older PHPUnit.

Related errors

AI-assisted analysis of sebastianbergmann/phpunit@f123cdb2a2 (2026-08-23). Data as JSON: /api/errors/428e77159722ded9. Report an issue: GitHub.