smeghead/php-class-diagram

A CLI tool that parses the PHP source directory and outputs PlantUML scripts.

v1.2.5 2024-01-17 12:29 UTC

Requires

• php: >=8.0
• nikic/php-parser: ^4.13
• phpstan/phpdoc-parser: ^1.23
• symfony/finder: ^5.3|^6.0

Requires (Dev)

• clue/phar-composer: ^1.2
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^9.5

Apache-2.0

• smeghead

• plantuml
• classdiagram

README

A CLI tool that parses the PHP source directory and generates PlantUML class diagram scripts as output.

Features

• ♻️ Generating class diagrams from source code contributes to continuous design improvement.
• 🔖 It produces expressive class diagrams with a focus on namespaces and relationships.
• 🔧 This simple CLI tool is easy to use.
• 💡 Additionally, it can generate a package relationship diagram to visualize dependencies on external namespaces.

What is PlantUML

PlantUML - Wikipedia PlantUML is an open-source tool allowing users to create diagrams from a plain text language. Besides various UML diagrams, PlantUML has support for various other software development related formats (such as Archimate, Block diagram, BPMN, C4, Computer network diagram, ERD, Gantt chart, Mind map, and WBD), as well as visualisation of JSON and YAML files.

Dogfooding

php-class-diagram class diagram

php-class-diagram class diagram without fields and methods

If your analysis primarily focuses on the relationships between classes, a simpler notation may be more appropriate.

php-class-diagram package related diagram

Visualizing package relationships can uncover critical design issues.

Install

From DockerHub

You can utilize a Docker image that includes php-class-diagram and PlantUML from the following URL.

• https://hub.docker.com/r/smeghead7/php-class-diagram

From Composer

$ mkdir sample
$ cd sample
$ composer init
$ composer require --dev smeghead/php-class-diagram

Now, you can execute ./vendor/bin/php-class-diagram. for instance, try to display help message.

$ vendor/bin/php-class-diagram --help
usage: php-class-diagram [OPTIONS] <target php source directory>

A CLI tool that parses the PHP source directory and generates PlantUML class diagram scripts as output.

OPTIONS
  -h, --help                     show this help page.
  -v, --version                  show version.
      --class-diagram            output class diagram script. (default)
      --package-diagram          output package diagram script.
      --division-diagram         output division diagram script.
      --jig-diagram              output class diagram and package diagram script.
      --enable-class-properties  describe properties in class diagram. (default)
      --disable-class-properties not describe properties in class diagram.
      --enable-class-methods     describe methods in class diagram. (default)
      --disable-class-methods    not describe methods in class diagram.
      --enable-class-name-summary  describe classname with Class summary of document comment. (default)
      --disable-class-name-summary describe classname without Class summary of document comment.
      --php5                     parse php source file as php5.
      --php7                     parse php source file as php7.
      --php8                     parse php source file as php8. (not suppoted)
      --header='header string'   additional header string. You can specify multiple header values.
      --include='wildcard'       include target file pattern. (default: `*.php`) You can specify multiple include patterns.
      --exclude='wildcard'       exclude target file pattern. You can specify multiple exclude patterns.

How to execute

Class Diagram

If there are three PHP source files in the directory test/fixtures/no-namespace each with a TYPE comment,

• php source files.

└─test
    └─fixtures
        └─no-namespace
            └─product
                    Product.php
                    Name.php
                    Price.php

• Product.php

<?php
class Product {
    /** @var Name   product name. */
    private $name;
    /** @var Price  price of product. */
    private $price;
}

• Name.php

<?php
class Name {
    /** @var string  name. */
    private $name;
}

• Price.php

<?php
class Price {
    /** @var int  price. */
    private int $price;
}

Executing php-class-diagram will output the PlantUML script.

$ vendor/bin/php-class-diagram test/fixtures/no-namespace
@startuml class-diagram
  package product as product {
    class "Price" as product_Price {
      -price : int
    }
    class "Name" as product_Name {
      -name : string
    }
    class "Product" as product_Product {
      -name : Name
      -price : Price
      +method1(param1)
    }
  }
  product_Product ..> product_Name
  product_Product ..> product_Price
  product_Product ..> product_Product
@enduml

Use PlnatUML to convert the PlantUML script to an image.

option header

You can specify the string to be output to the PlantUML header.

$ vendor/bin/php-class-diagram \
    --header='title "This is the class diagram"' \
    path/to/src

option include

You can add patterns to specify the target files for processing.

$ vendor/bin/php-class-diagram \
    --include='*.php' \
    --include='*.php4' \
    path/to/src

option exclude

You can specify patterns to exclude files from the processing.

$ vendor/bin/php-class-diagram \
    --exclude='test' \
    --exclude='*Exception.php' \
    path/to/src

Package Diagram

You can visualize package dependencies by creating a package relationship diagram using php-class-diagram.

$ vendor/bin/php-class-diagram --package-diagram test/fixtures/dependency-loops
@startuml package-related-diagram
  package hoge.fuga as ROOT {
    package product as product {
      package attribute as product.attribute {
      }
      package config as product.config {
      }
    }
  }
  product --> product.attribute
  product <-[#red,plain,thickness=4]-> product.config
@enduml

Packages that depend on each other are undesirable. If the tool detects such dependencies, it will issue a warning with a thick red line.

Division Diagram

If you are utilizing the Enum feature introduced in PHP 8.1, you can generate the division diagram. Visualizing the divisions employed in the program can be beneficial for research and design purposes.

$ bin/php-class-diagram --division-diagram test/fixtures/enum/ 
@startuml division-diagram
  card Suit #ccffcc [
    Suit
    <b>スート</b>
    ====
    Hearts
    <b>ハート</b>
    ----
    Diamonds
    <b>ダイヤ</b>
    ----
    Clubs
    <b>クローバー</b>
    ----
    Spades
    <b>スペード</b>
  ]
  package Sub as Sub {
    card Status #ffcccc [
      Status
      <b>ゲームのステータス</b>
      ====
      Player
      <b>プレイヤーのターン</b>
      ----
      Computer
      <b>コンピュータのターン</b>
      ----
      GameSet
      <b>ゲーム終了</b>
    ]
    card MyExceptionCase #ccccff [
      MyExceptionCase
      ====
      InvalidMethod
      ----
      InvalidProperty
      ----
      Timeout
    ]
    card Size #ccffff [
      Size
      ====
      Small
      ----
      Medium
      ----
      Large
    ]
  }
@enduml

Development

Open shell

docker compose build
docker compose run --rm php_cli bash

install dependencies

composer install

execute tests

composer test

CONTRIBUTING

Both Issues and Pull Requests are welcome!