# phpoffice/phpspreadsheet architecture

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

- Interactive diagram: https://gitdiagram.com/phpoffice/phpspreadsheet
- Repository: https://github.com/phpoffice/phpspreadsheet

## Overview

##### Main Components
- Core API & Data Model: This layer consists of classes representing the spreadsheet’s fundamental structures—Spreadsheet, Worksheet, Cell, Row, Column, DefinedName, and so on. Represent these as “core domain objects.”
- Calculation Engine: A specialized module that handles formulas, functions, calculation settings, and formula parsing. It is subdivided further into areas such as Binary Comparison, Date/Time Excel calculations, Mathematical Functions, Financial, Statistical functions, and text processing. Show multiple sub-components under the Calculation Engine.
- Readers: Modules that handle different file formats (XLS, XLSX, CSV, ODS, HTML, and even specialized XML formats). They convert external spreadsheet file structures into the internal data model.
- Writers: Modules that export or save the data model back to various spreadsheet file formats. There’s a parallel structure to the Readers for CSV, XLS, XLSX, ODS, PDF, and HTML.
- Style, Formatting, and Rendering: Classes responsible for style properties, conditional formatting, fonts, borders, number formats, and even chart components. They reside closely with both the core API and the output writers.
- Helper and Utility Components: These include support for file handling (OLE, zip streams), text and string helpers, trend calculations, and various miscellaneous helpers that are used across the library.
- Testing & Samples: While not part of production runtime, tests (located in the “tests” directory) and sample files (in “samples”) can be shown as separate modules that ensure reliability and also serve as usage examples.
- Documentation & Infrastructure: The “docs” folder contains both user documentation and support for online documentation generators. There is also infrastructure code (e.g., “infra”) used for document generation and locale management.

##### Relationships and Interactions
- The Core API acts as the heart of the library. Both Reader and Writer modules interact with it—they populate the data model and then persist it.
- The Calculation Engine is used by the Spreadsheet object for processing formulas embedded in cells. It interacts with a Formula Parser, Tokenizer, and a set of specialized function classes.
- Styles and formatting components are applied on top of core cell values and used by the Writers when formatting output.
- Dependency modules, such as those for file reading/ZIP extraction and PHP’s own Composer dependency management (indicated by composer.json) are supporting external libraries and standards (e.g., PSR).

##### Architectural Patterns and Design Principles
- Layered Architecture: Clearly separate the interface (public API, Readers, Writers) from the core business logic (data model, calculation engine) and supporting utilities.
- Modularity: The project is broken up into self-contained namespaces and modules (e.g., the Calculation sub-modules, the Reader submodules for each file type, etc.) which communicate via well-defined interfaces.
- Separation of Concerns: Distinct modules handle file I/O (Readers/Writers), business logic (Calculation Engine, Core Models), and formatting/styling. This is evident in the directory structure, with a “src/PhpSpreadsheet” root.
- Test-Driven: The comprehensive “tests” directory shows the emphasis on unit tests and integration tests for each module.

##### Relevant Technologies and Frameworks
- PHP (language with modern features, namespaces, and PSR standards).
- Composer for dependency management.
- Standard PHP testing frameworks (e.g., PHPUnit) as reflected by the tests and configuration files (phpunit.xml.dist, phpstan, etc.).
- Integration with documentation tools (readthedocs and mkdocs configuration files).

##### Final Touches
- Optionally, include an “External Interfaces” section at the bottom for documentation links, GitHub workflows, and support interactions (StackOverflow, Gitter).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Layer
    subgraph "Core Layer"
        CA["Core API & Data Model"]
        CE["Calculation Engine"]
    end

    %% I/O Layer
    subgraph "I/O Layer"
        R["Readers"]
        W["Writers"]
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        SStyle["Styles & Rendering"]
        SChart["Chart Rendering"]
    end

    %% Utility Layer
    subgraph "Utility Layer"
        HU["Helpers & Utilities"]
        SU["Shared Utilities"]
    end

    %% QA & Documentation
    subgraph "QA & Documentation"
        T["Tests"]
        SA["Samples"]
        D["Documentation"]
        I["Infrastructure"]
    end

    %% Calculation Engine Details Subgraph
    subgraph "Calculation Engine Details"
        FP["FormulaParser"]
        FI["Function Implementations"]
        CS["Calculation Settings"]
        F["Financial Functions"]
        DT["Date/Time Functions"]
        M["Mathematical Functions"]
        ST["Statistical Functions"]
        TXT["Text Processing"]
    end

    %% Connections between major layers
    R -->|"populates"| CA
    CA -->|"invokes"| CE
    CA -->|"provides data to"| W
    SStyle -->|"formats output for"| W
    SChart -->|"renders charts for"| W

    %% Connection to Calculation Engine Details
    CE --> FP
    CE --> FI
    CE --> CS
    FI --> F
    FI --> DT
    FI --> M
    FI --> ST
    FI --> TXT

    %% Helper connections (shared utilities support multiple layers)
    HU --- CA
    HU --- R
    HU --- W
    HU --- CE
    SU --- CA
    SU --- R
    SU --- W

    %% QA & Documentation interactions (testing touches core functionality)
    T --- CA
    SA --- CA
    D --- CA
    I --- CA

    %% Click Events for components
    click CA "https://github.com/phpoffice/phpspreadsheet/tree/master/src/PhpSpreadsheet"
    click CE "https://github.com/phpoffice/phpspreadsheet/tree/master/src/PhpSpreadsheet/Calculation"
    click R "https://github.com/phpoffice/phpspreadsheet/tree/master/src/PhpSpreadsheet/Reader"
    click W "https://github.com/phpoffice/phpspreadsheet/tree/master/src/PhpSpreadsheet/Writer"
    click SStyle "https://github.com/phpoffice/phpspreadsheet/tree/master/src/PhpSpreadsheet/Style"
    click SChart "https://github.com/phpoffice/phpspreadsheet/tree/master/src/PhpSpreadsheet/Chart"
    click HU "https://github.com/phpoffice/phpspreadsheet/tree/master/src/PhpSpreadsheet/Helper"
    click SU "https://github.com/phpoffice/phpspreadsheet/tree/master/src/PhpSpreadsheet/Shared"
    click T "https://github.com/phpoffice/phpspreadsheet/tree/master/tests"
    click SA "https://github.com/phpoffice/phpspreadsheet/tree/master/samples"
    click D "https://github.com/phpoffice/phpspreadsheet/tree/master/docs"
    click I "https://github.com/phpoffice/phpspreadsheet/tree/master/infra"

    %% Styles
    classDef coreStyle fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef calcStyle fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef ioStyle fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef presStyle fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef utilStyle fill:#E5E8E8,stroke:#566573,stroke-width:2px;
    classDef qaStyle fill:#F5B7B1,stroke:#CB4335,stroke-width:2px;
    classDef docStyle fill:#85C1E9,stroke:#2471A3,stroke-width:2px;

    %% Assign classes
    class CA coreStyle;
    class CE calcStyle;
    class FP,FI,CS,F,DT,M,ST,TXT calcStyle;
    class R,W ioStyle;
    class SStyle,SChart presStyle;
    class HU,SU utilStyle;
    class T,SA qaStyle;
    class D,I docStyle;
```
