Phpunit Constraint Xmlmatchesxsd Laravel Package

Getting Started

This package provides a custom PHPUnit constraint XmlMatchesXsd for validating XML against an XSD schema. It is exclusively designed for internal use by PHP-CS-Fixer’s test suite, as explicitly stated in the README: "This constraint is for PHP CS Fixer usage only."
To use it, install via Composer:

composer require --dev php-cs-fixer/phpunit-constraint-xmlmatchesxsd

Then, in a PHPUnit test, assert XML validity like this:

use PHPUnit\Framework\TestCase;
use PHP-CS-Fixer\PHPUnit\Constraint\XmlMatchesXsd;

class MyXmlTest extends TestCase
{
    public function testXmlMatchesSchema(): void
    {
        $xml = '<root><item id="1"/></root>';
        $xsd = __DIR__ . '/schema.xsd';

        $this->assertThat($xml, new XmlMatchesXsd($xsd));
    }
}

Start by reading the tests directory — they contain the canonical usage examples.

Implementation Patterns

• Schema-based XML validation in tests: Ideal for test suites where XML outputs (e.g., from generators, reporters, or CLI tools) must conform to strict schemas — especially useful for PHP-CS-Fixer’s own test suite validating generated config files or XML reports.
• Integration with custom fixtures: Load XML from fixtures (e.g., $this->loadXmlFixture('expected.xml')) and validate against a pre-approved XSD in the same way as above.
• Complementary to PHP-CS-Fixer tests: Most developers will not use this directly in their apps. Instead, it appears when working on PHP-CS-Fixer itself (e.g., when adding a new fixer that outputs XML, you’ll validate its output matches a schema).
• Strict error reporting: When validation fails, the constraint surfaces detailed libxml errors (e.g., line numbers, missing elements) — use $this->assertThat(...)->getMessage() or check PHPUnit output for diagnostics.

Gotchas and Tips

• ❗ Do not use in production apps: The README is clear — it’s a private utility. Relying on it externally risks breaking changes (e.g., no semver guarantees beyond test coverage).
• 🧪 Use only with PHP-CS-Fixer-compatible PHPUnit versions: The package pins support closely to PHPUnit versions (currently 9–13); verify your test PHP/PHPUnit version matches the latest release requirements (see changelog: PHP ≥ 7.4 required since v1.8).
• ⚠️ XSD path must be resolvable at runtime: Passing a relative path like 'schema.xsd' works only if the test’s working directory is the repo root. Prefer absolute paths (__DIR__ . '/../../fixtures/schema.xsd') for reliability.
• 📄 Empty/whitespace XML may silently pass or fail: Libxml validation is strict — leading whitespace, comments, or missing XML declaration can trigger errors. Trim or canonicalize XML before passing it in.
• 🔍 Debug failing assertions: Override XmlMatchesXsd::evaluate() temporarily or use var_dump($this->getActual()) in assertThat() to inspect the raw XML and libxml error log (via libxml_get_errors()).
• 🔗 Not a standalone library: Its limited stars (3), 0 dependents, and “NOASSERTION” license signal it’s not a public API. For similar functionality elsewhere, consider libxsd + custom constraint, or webmozart/path-util + domdocument manually.