# oroinc/upgrade architecture

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

- Interactive diagram: https://gitdiagram.com/oroinc/upgrade
- Repository: https://github.com/oroinc/upgrade

## Overview

##### Main Components
- CLI Entry Points & Commands:
- The “bin” directory contains the main executables (e.g., upgrade-toolkit).
- Commands like “ProcessCommand”, “UpgradeCommand”, and “YmlFixCommand” (located under src/...) represent the user-facing CLI functionality.
- Rector Engine:
▫ Application processors (processing added, deleted, or modified files)
▫ Rule sets organized by target versions (e.g., Oro42, Oro51, Oro60) which define the code refactoring transformations.
▫ Namespace manipulation and PHP-Parser based components for analyzing and transforming code.
- “rector.php” at the project root also indicates configuration for Rector.
- YML Fixer:
- Located in “src/YmlFixer” – this component houses the logic to process and correct .yml configuration files.
- It includes commands, configuration, file visitors, processors, and rules specific to YML files.
- Configuration and Signature Components:
- In “src/Configuration” and “src/Rector/Signature”, helper classes define command options, signature builders, and overall configuration for the upgrade procedures.
- Test Suite:
- The “tests” directory comprehensively covers both Rector and YmlFixer functionalities to ensure the reliability of rule transformations through unit and integration tests.

##### Relationships and Interactions
- The CLI interface (invoked via “php bin/upgrade-toolkit” or “bin/rector”) acts as the entry point.
- The Rector components (for PHP code refactoring), or
- The YML Fixer components (for processing .yml files).
- The corresponding processors within each module then:
- Parse the source files (using PHP-Parser for PHP files or custom parsing logic for YML files).
- Apply a set of transformation rules (different rule sets for Oro42, Oro51, Oro60).
- Generate new outputs or update code in-place.
- Helper classes (like configuration classes and signature builders) support the main processing units.
- Finally, the test suite (via PHPUnit) validates the transformations to ensure integrity after the upgrade process.

##### Architectural Patterns and Design Principles
- Modular Design:
- The project is clearly divided into modules (CLI, Rector rules, YML fixer, configuration, and tests). This encourages separation of concerns.
- Extensibility:
- By isolating the rule sets into separate directories and files (e.g., sets/oro-51, sets/oro-60), the design allows for easy expansion and customization.
- Rule-based Refactoring:
- The use of specialized rule sets for refactoring (both for PHP and YML) highlights the principle of declarative transformation based on predefined rules.

##### Relevant Technologies and Frameworks
- PHP (the core language) with Composer for dependency management.
- PHP-Parser and Rector for static code analysis and automated code transformation.
- PHPUnit for testing.
- CLI tools integrated into PHP scripts (as seen with commands in the “bin” directory).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Interface Cluster
    subgraph "CLI Interface"
        A1["Executable Script"]:::cli
        A2["ProcessCommand"]:::cli
        A3["UpgradeCommand"]:::cli
        A4["YmlFixCommand"]:::cli
    end

    %% Rector Engine Cluster
    subgraph "Rector Engine"
        B1["Rector Runner"]:::rector
        B2["Application Processors"]:::rector
        B3["Oro42 Rules"]:::rector
        B4["Oro51 Rules"]:::rector
        B5["Oro60 Rules"]:::rector
        B6["PHP-Parser"]:::rector
        B7["Namespace Manipulation"]:::rector
        B8["Signature & Config"]:::rector
    end

    %% YML Fixer Engine Cluster
    subgraph "YML Fixer Engine"
        C1["YML Fixer Core"]:::yml
        C2["YML Config"]:::yml
        C3["YML Finder"]:::yml
        C4["YML File Processor"]:::yml
        C5["App YML Processor"]:::yml
        C6["YML File Visitor"]:::yml
    end

    %% Configuration & Utilities Cluster
    subgraph "Configuration & Utilities"
        D1["General Configuration"]:::config
    end

    %% Test Suite Cluster
    subgraph "Test Suite"
        E1["Rector Tests"]:::test
        E2["YML Fixer Tests"]:::test
    end

    %% Connections from CLI to Engine Clusters
    A1 --> A2
    A1 --> A3
    A1 --> A4

    A2 -->|triggers| B1
    A3 -->|triggers| B1
    A4 -->|triggers| C1

    %% Connections within Rector Engine
    B1 --> B2
    B1 --> B6
    B1 --> B7
    B1 --> B8
    B2 --> B3
    B2 --> B4
    B2 --> B5
    B8 --> D1
    B1 ---|tested by| E1

    %% Connections within YML Fixer Engine
    C1 --> C2
    C1 --> C3
    C1 --> C4
    C1 --> C5
    C1 --> C6
    C1 ---|tested by| E2

    %% Class definitions with colors
    classDef cli fill:#ffefc6,stroke:#ffaa00,stroke-width:2px;
    classDef rector fill:#d0e9ff,stroke:#337ab7,stroke-width:2px;
    classDef yml fill:#d4f4dd,stroke:#3c763d,stroke-width:2px;
    classDef config fill:#f7d1f7,stroke:#a94442,stroke-width:2px;
    classDef test fill:#fff2cc,stroke:#8a6d3b,stroke-width:2px;

    %% Click Events for CLI
    click A1 "https://github.com/oroinc/upgrade/tree/master/bin/upgrade-toolkit"
    click A2 "https://github.com/oroinc/upgrade/blob/master/src/Rector/Console/Command/ProcessCommand.php"
    click A3 "https://github.com/oroinc/upgrade/blob/master/src/Rector/Console/Command/UpgradeCommand.php"
    click A4 "https://github.com/oroinc/upgrade/blob/master/src/YmlFixer/Command/YmlFixCommand.php"

    %% Click Events for Rector Engine
    click B2 "https://github.com/oroinc/upgrade/tree/master/src/Rector/Application"
    click B3 "https://github.com/oroinc/upgrade/blob/master/sets/oro-42.php"
    click B4 "https://github.com/oroinc/upgrade/blob/master/sets/oro-51.php"
    click B5 "https://github.com/oroinc/upgrade/blob/master/sets/oro-60.php"
    click B6 "https://github.com/oroinc/upgrade/tree/master/src/Rector/PhpParser"
    click B7 "https://github.com/oroinc/upgrade/tree/master/src/Rector/Namespace"
    click B1 "https://github.com/oroinc/upgrade/blob/master/src/Rector/Rector/RectorRunner.php"
    click B8 "https://github.com/oroinc/upgrade/tree/master/src/Rector/Signature"

    %% Click Events for YML Fixer Engine
    click C1 "https://github.com/oroinc/upgrade/tree/master/src/YmlFixer"
    click C2 "https://github.com/oroinc/upgrade/blob/master/src/YmlFixer/Config/Config.php"
    click C3 "https://github.com/oroinc/upgrade/blob/master/src/YmlFixer/Finder/YmlFilesFinder.php"
    click C4 "https://github.com/oroinc/upgrade/blob/master/src/YmlFixer/Processor/YmlFileProcessor.php"
    click C5 "https://github.com/oroinc/upgrade/blob/master/src/YmlFixer/Processor/AppYmlFileProcessor.php"
    click C6 "https://github.com/oroinc/upgrade/blob/master/src/YmlFixer/Visitor/YmlFileVisitor.php"

    %% Click Events for Configuration
    click D1 "https://github.com/oroinc/upgrade/tree/master/src/Configuration"

    %% Click Events for Test Suite
    click E1 "https://github.com/oroinc/upgrade/tree/master/tests/Rector"
    click E2 "https://github.com/oroinc/upgrade/tree/master/tests/Unit/YmlFixer"
```
