# sebastianbergmann/phpunit architecture

> Architecture diagram of the GitHub repository sebastianbergmann/phpunit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sebastianbergmann/phpunit
- Repository: https://github.com/sebastianbergmann/phpunit

## Overview

##### Project Type and Purpose
- PHPUnit is an open-source, CLI-based testing framework for PHP (an xUnit tool).
- It provides a command-line interface (TextUI), core testing abstractions (Framework), a test-execution engine (Runner), an event system for decoupled instrumentation (Event), multiple logging back-ends (JUnit, TeamCity, TestDox), configuration parsing (Metadata, TextUI/Configuration), and utility services (Util).

##### High-Level Module Breakdown
Hundreds of classes into these logical subsystems.
a. CLI / Entry Point
- src/TextUI/Application.php
- src/TextUI/Command/… (commands like VersionCheck, GenerateConfiguration)
- TextUI/Output (printers, progress indicators)
- ShellExitCodeCalculator
b. Configuration
- src/TextUI/Configuration (CLI vs XML)
- Xml loader, validator, merger, migration
- CodeCoverageFilterRegistry
c. Test Suite Loading & Sorting
- src/Runner/TestSuiteLoader.php
- src/Runner/TestSuiteSorter.php
d. Test Execution Engine (Runner)
- src/Runner/TestRunner (isolated vs in-process runners)
- ChildProcessResultProcessor, ErrorHandler, HookMethodCollection
- Filters: NameFilterIterator, GroupFilterIterator
- Baseline management, ResultCache, DeprecationCollector, CodeCoverage
e. Core Test Abstractions (Framework)
- TestCase, Assert, Constraint, TestSuite, TestResult, TestBuilder
- MockObject generation/runtime
- ExecutionOrderDependency, TestRunner interfaces
f. Event System
- src/Event/Dispatcher, Emitter, Facade
- Events for Application, TestRunner, TestSuite, Test, TestDouble, Telemetry
- Subscriber interfaces (Decoupled observers)
g. Logging Back-Ends
- src/Logging/JUnit, TeamCity, TestDox (Html, PlainText)
- Each provides subscribers reacting to events and emitting XML, TeamCity-formatted messages, or pretty-printed output.
h. Metadata & Parsing
- Attribute/Annotation parsers, requirements (Groups, Depends, Covers)
- Version constraints, API attributes
i. Utilities & Build Tools
- src/Util (Filesystem, XML loader, HTTP downloader, PHP job runner)
- build/ and tools/ for PHAR scoping, versioning, autoload templating, generating releases
j. Schema Definitions & Tests
- schema/*.xsd for CLI XML, tests for each subsystem in tests/unit and tests/end-to-end

##### Interactions and Data Flows
- User invokes “phpunit” → TextUI/Application parses CLI args via Configuration/Cli → builds Configuration object
- Configuration feeds TestSuiteLoader → produces a TestSuite tree
- TextUI/TestRunner orchestrates: selects a Runner (isolated or in-process) → Runner loads tests, executes them
- During execution, the Framework/TestCase triggers assertions and life-cycle hooks → publishes events to Event/Facade
- Event/Dispatcher dispatches events to registered subscribers: Logging back-ends, ResultCache, BaselineWriter, DeprecationCollector, GarbageCollectionHandler
- After all tests, TestRunner collates TestResult, writes exit code, Blat PHAR if invoked

##### Architectural Patterns & Principles
- Event‐Driven: central Event Facade with Dispatchers + Emitter + Subscribers
- Strategy/Factory: multiple TestRunner implementations selected at runtime
- Template Method: TestCase defines run() skeleton, hook methods injected via Metadata/Parser
- Builder: Configuration and Metadata builders, TestSuiteBuilder, TestDoxBuilder
- Dependency Injection / Facade: Runner/Facade classes hide complexity
- Extension Points: Runner/ExtensionBootstrappers, CLI commands, Logging subscribers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs with colored boxes

    subgraph "CLI / Entry Point"
        direction TB
        Application["TextUI/Application"]:::cli
        Commands["TextUI/Command (commands)"]:::cli
        Output["TextUI/Output"]:::cli
        ShellExit["ShellExitCodeCalculator"]:::cli
    end

    subgraph "Configuration"
        direction TB
        CfgCli["Configuration/Cli"]:::config
        CfgXml["Configuration/Xml"]:::config
        CfgRegistry["CodeCoverageFilterRegistry"]:::config
        CfgBuilder["Builder"]:::config
        CfgMerger["Merger"]:::config
    end

    subgraph "Test Suite Loading & Sorting"
        direction TB
        Loader["TestSuiteLoader"]:::loader
        Sorter["TestSuiteSorter"]:::loader
    end

    subgraph "Test Execution Engine (Runner)"
        direction TB
        TestRunner["TestRunner (+strategy interface)"]:::runner
        Filters["Filter/ (NameFilterIterator, GroupFilterIterator)"]:::runner
        Hooks["HookMethodCollection"]:::runner
        Baseline["Baseline/"]:::runner
        ResultCache["ResultCache/"]:::runner
        Deprecation["DeprecationCollector"]:::runner
        CodeCoverage["CodeCoverage"]:::runner
        Extension["Extension/"]:::runner
        Garbage["GarbageCollection"]:::runner
        Phpt["Phpt"]:::runner
        TestResult["TestResult"]:::runner
    end

    subgraph "Core Test Abstractions (Framework)"
        direction TB
        TestCase["TestCase"]:::framework
        Assert["Assert"]:::framework
        Constraint["Constraint/"]:::framework
        Suite["TestSuite"]:::framework
        FRunners["TestRunner interfaces"]:::framework
    end

    subgraph "Event System"
        direction TB
        Dispatcher["Dispatcher/"]:::event
        Emitter["Emitter/"]:::event
        Facade["Facade"]:::event
        SubscriberIfc["Subscriber.php (+subscriber interface)"]:::event
        Events["Events/"]:::event
    end

    subgraph "Logging Back-Ends"
        direction TB
        JUnit["Logging/JUnit"]:::logging
        TeamCity["Logging/TeamCity"]:::logging
        TestDox["Logging/TestDox"]:::logging
    end

    subgraph "Metadata & Parsing"
        direction TB
        Parser["Parser/"]:::metadata
        Api["Api/"]:::metadata
        Version["Version/"]:::metadata
        MetaClasses["Metadata classes"]:::metadata
    end

    subgraph "Utilities & Build Tools"
        direction TB
        UtilFS["Util/Filesystem"]:::util
        UtilHTTP["Util/Http/Downloader"]:::util
        UtilJob["Util/PHP/JobRunner"]:::util
        UtilXML["Util/Xml/Loader"]:::util
        UtilOthers["Other Util"]:::util
        BuildScripts["build/ PHAR scripts"]:::build
        Tools["tools/"]:::build
    end

    subgraph "Schema & Tests"
        direction TB
        Schemas["schema/*.xsd"]:::cylinder
        UnitTests["tests/unit/"]:::cylinder
        E2ETests["tests/end-to-end/"]:::cylinder
    end

    %% Connections
    Application -->|invokes| CfgCli
    Application -->|invokes| CfgXml
    CfgBuilder --> Loader
    CfgMerger --> Loader
    Loader --> Sorter
    Sorter --> TestRunner
    TestRunner --> TestCase
    TestRunner --> Framework
    TestCase --> Facade
    Facade --> Dispatcher
    Facade --> Emitter
    Facade --> SubscriberIfc
    Facade --> Events
    Facade --> JUnit
    Facade --> TeamCity
    Facade --> TestDox
    Facade --> ResultCache
    Facade --> Baseline
    Facade --> Deprecation
    Facade --> Garbage
    Parser --> TestCase
    Api --> TestCase
    Version --> TestCase
    UtilFS --> CfgXml
    UtilXML --> CfgXml
    BuildScripts --> Application
    BuildScripts --> Schemas
    Tools --> BuildScripts
    Schemas --> CfgXml
    UnitTests --> Loader
    E2ETests --> Application

    %% Click Events
    click Application "https://github.com/sebastianbergmann/phpunit/blob/main/src/TextUI/Application.php"
    click Commands "https://github.com/sebastianbergmann/phpunit/tree/main/src/TextUI/Command/Commands/"
    click Output "https://github.com/sebastianbergmann/phpunit/tree/main/src/TextUI/Output/"
    click ShellExit "https://github.com/sebastianbergmann/phpunit/blob/main/src/TextUI/ShellExitCodeCalculator.php"
    click CfgCli "https://github.com/sebastianbergmann/phpunit/tree/main/src/TextUI/Configuration/Cli/"
    click CfgXml "https://github.com/sebastianbergmann/phpunit/tree/main/src/TextUI/Configuration/Xml/"
    click CfgRegistry "https://github.com/sebastianbergmann/phpunit/blob/main/src/TextUI/Configuration/CodeCoverageFilterRegistry.php"
    click CfgBuilder "https://github.com/sebastianbergmann/phpunit/blob/main/src/TextUI/Configuration/Builder.php"
    click CfgMerger "https://github.com/sebastianbergmann/phpunit/blob/main/src/TextUI/Configuration/Merger.php"
    click Loader "https://github.com/sebastianbergmann/phpunit/blob/main/src/Runner/TestSuiteLoader.php"
    click Sorter "https://github.com/sebastianbergmann/phpunit/blob/main/src/Runner/TestSuiteSorter.php"
    click TestRunner "https://github.com/sebastianbergmann/phpunit/blob/main/src/Runner/TestRunner.php"
    click Filters "https://github.com/sebastianbergmann/phpunit/tree/main/src/Runner/Filter/"
    click Hooks "https://github.com/sebastianbergmann/phpunit/blob/main/src/Runner/HookMethod/HookMethodCollection.php"
    click Baseline "https://github.com/sebastianbergmann/phpunit/tree/main/src/Runner/Baseline/"
    click ResultCache "https://github.com/sebastianbergmann/phpunit/tree/main/src/Runner/ResultCache/"
    click Deprecation "https://github.com/sebastianbergmann/phpunit/tree/main/src/Runner/DeprecationCollector/"
    click CodeCoverage "https://github.com/sebastianbergmann/phpunit/blob/main/src/Runner/CodeCoverage.php"
    click Extension "https://github.com/sebastianbergmann/phpunit/tree/main/src/Runner/Extension/"
    click Garbage "https://github.com/sebastianbergmann/phpunit/tree/main/src/Runner/GarbageCollection/"
    click Phpt "https://github.com/sebastianbergmann/phpunit/tree/main/src/Runner/Phpt/"
    click TestResult "https://github.com/sebastianbergmann/phpunit/tree/main/src/Runner/TestResult/"
    click TestCase "https://github.com/sebastianbergmann/phpunit/blob/main/src/Framework/TestCase.php"
    click Assert "https://github.com/sebastianbergmann/phpunit/blob/main/src/Framework/Assert.php"
    click Constraint "https://github.com/sebastianbergmann/phpunit/tree/main/src/Framework/Constraint/"
    click Suite "https://github.com/sebastianbergmann/phpunit/blob/main/src/Framework/TestSuite.php"
    click FRunners "https://github.com/sebastianbergmann/phpunit/tree/main/src/Framework/TestRunner/"
    click Dispatcher "https://github.com/sebastianbergmann/phpunit/tree/main/src/Event/Dispatcher/"
    click Emitter "https://github.com/sebastianbergmann/phpunit/tree/main/src/Event/Emitter/"
    click Facade "https://github.com/sebastianbergmann/phpunit/blob/main/src/Event/Facade.php"
    click SubscriberIfc "https://github.com/sebastianbergmann/phpunit/blob/main/src/Event/Subscriber.php"
    click Events "https://github.com/sebastianbergmann/phpunit/tree/main/src/Event/Events/"
    click JUnit "https://github.com/sebastianbergmann/phpunit/tree/main/src/Logging/JUnit/"
    click TeamCity "https://github.com/sebastianbergmann/phpunit/tree/main/src/Logging/TeamCity/"
    click TestDox "https://github.com/sebastianbergmann/phpunit/tree/main/src/Logging/TestDox/"
    click Parser "https://github.com/sebastianbergmann/phpunit/tree/main/src/Metadata/Parser/"
    click Api "https://github.com/sebastianbergmann/phpunit/tree/main/src/Metadata/Api/"
    click Version "https://github.com/sebastianbergmann/phpunit/tree/main/src/Metadata/Version/"
    click UtilFS "https://github.com/sebastianbergmann/phpunit/tree/main/src/Util/Filesystem"
    click UtilHTTP "https://github.com/sebastianbergmann/phpunit/tree/main/src/Util/Http/Downloader"
    click UtilJob "https://github.com/sebastianbergmann/phpunit/tree/main/src/Util/PHP/JobRunner"
    click UtilXML "https://github.com/sebastianbergmann/phpunit/tree/main/src/Util/Xml/Loader"
    click BuildScripts "https://github.com/sebastianbergmann/phpunit/tree/main/build/"
    click Tools "https://github.com/sebastianbergmann/phpunit/tree/main/tools/"
    click Schemas "https://github.com/sebastianbergmann/phpunit/tree/main/schema/"
    click UnitTests "https://github.com/sebastianbergmann/phpunit/tree/main/tests/unit/"
    click E2ETests "https://github.com/sebastianbergmann/phpunit/tree/main/tests/end-to-end/"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0366d6
    classDef config fill:#DFFFD0,stroke:#228B22
    classDef loader fill:#FFE6B0,stroke:#FF8C00
    classDef runner fill:#FFE6B0,stroke:#FF8C00
    classDef framework fill:#FFF7B0,stroke:#DAA520
    classDef event fill:#E6D0FF,stroke:#800080
    classDef logging fill:#D0F0EF,stroke:#20B2AA
    classDef metadata fill:#F0FFB0,stroke:#9ACD32
    classDef util fill:#DDDDDD,stroke:#888888
    classDef build fill:#CCCCCC,stroke:#444444
    classDef cylinder fill:#FFFFFF,stroke:#000000,stroke-dasharray: 2 2
```
