Detect flaws in your architecture before they drag you down into the depths of dependency hell ...

• What it does
• System Requirements
• Installation
  • Phive
  • Composer
  • Manual .phar download
  • Git
• Usage
  • Filters
  • Text
  • UML
  • Dependency Structure Matrix
  • Metrics
  • Dynamic Analysis
    • Setup
    • Usage
• Examples
  • Architecture Constraints
  • Architecture Timeline
• How it all works
• Supported Features
• Troubleshooting
  • Not enough RAM
• License

What it does

dePHPend helps with bringing your PHP projects back in shape. Over the course of a project, we usually keep adding more and more dependencies. Often hidden behind singletons or service locators, these dependencies can quickly become a maintenance (and testing!) nightmare.

dePHPend analyses your app and attempts to find everything you depend on.

With this information you can:

• get a quick overview of how an application is structured
• start refactoring where it's needed the most
• track architecture violations (maybe your view shouldn't be telling the model what to do?)
• find out why your changes are breaking tests

System Requirements

• PHP >= 7.2
• plantuml (UML Class diagram)

Installation

Docker

If you don't want to worry about PHP versions, composer dependencies etc. you can run dePHPend from a docker container:

# replace $PATH_TO_INSPECT with whatever path you would live to inspect
docker run --rm -v $PATH_TO_INSPECT:/inspect mihaeu/dephpend:latest text /inspect

Phive

Phive is the preferred method of installing QA tools which are not linked directly to your code. If you've never heard about it, I'd recommend you check it out. Once installed simply use:

phive install dephpend

# or

phive install --copy dephpend

Composer

You can install dePHPend globally, but this might lead to problems if other globally installed QA tools use different versions of PhpParser for instance.

composer global require dephpend/dephpend:dev-main

Manual .phar download

Download the PHAR file by selecting the latest file from GitHub Releases.

Git

git clone [email protected]:mihaeu/dephpend.git
# or
git clone https://github.com/mihaeu/dephpend.git

cd dephpend
composer install

Usage

You should almost always run QA tools without XDebug (unless you need code coverage of course). You could use a separate php.ini where XDebug is not loaded and pass that to php or you just use the -n option (this will however not load any extensions, so you have to specify those separately).

# or bin/dephpend depending on how you installed this
$ php -n -d extension=tokenizer.so -d extension=json.so -d extension=mbstring.so dephpend.phar                                                                                                 
      _      _____  _    _ _____               _ 
     | |    |  __ \| |  | |  __ \             | |
   __| | ___| |__) | |__| | |__) |__ _ __   __| |
  / _` |/ _ \  ___/|  __  |  ___/ _ \ '_ \ / _` |
 | (_| |  __/ |    | |  | | |  |  __/ | | | (_| |
  \__,_|\___|_|    |_|  |_|_|   \___|_| |_|\__,_| version 0.8.1

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  dsm            Generate a Dependency Structure Matrix of your dependencies
  help           Displays help for a command
  list           Lists commands
  metrics        Generate dependency metrics
  test-features  Test support for dependency detection
  text           Prints a list of all dependencies
  uml            Generate a UML Class diagram of your dependencies

Filters

Without filters the output for large apps is too bloated which is why I implemented a couple of filters to help you get the output you want:

      --no-classes                         Remove all classes and analyse only namespaces.
  -f, --filter-from=FILTER-FROM            Analyse only dependencies which originate from this namespace.
      --filter-namespace=FILTER-NAMESPACE  Analyse only classes where both to and from are in this namespace.
  -d, --depth[=DEPTH]                      Output dependencies as packages instead of single classes. [default: 0]
  -e, --exclude-regex=EXCLUDE-REGEX        Exclude all dependencies which match the (PREG) regular expression.

      --dynamic=DYNAMIC                    Adds dependency information from dynamically analysed function traces, for more information check out https://dephpend.com
  -u, --underscore-namespaces              Parse underscores in Class names as namespaces.
      --internals                          Check for dependencies from internal PHP Classes like SplFileInfo.

For more info just run php dephpend.phar help text.

Text

For quick debugging use the text command. Say you want to find out which classes depend on XYZ and what XYZ depends on, you'd run:

php dephpend.phar text src | grep XYZ

# or for more complex applications use filters
php dephpend.phar text symfony --no-classes --depth 3 --exclude-regex='/Test/'

UML

Generates UML class or package diagrams of your source code. Requires PlantUML to be installed.

You can either run

php dephpend.phar uml --output=uml.png src

# or for post-processing
php dephpend.phar uml --output=uml.png --keep-uml src

but most likely what you want to do is to use the --no-classes and --depth[=DEPTH] option. If your app has more than 20 classes, the UML will become messy if you don't use namespace instead of class level. Experiment with different depth values, but usually a depth of 2 or 3 is what you want.

Dependency Structure Matrix

If you've tried decrypting massive UML diagrams before, you know that they become very hard to interpret for large applications. DSMs allow you to get a quick overview of your application and where dependency hotspots are.

This feature is still under construction and right now it's not really fun to use. If you still want to try run

php dephpend.phar dsm src > dependencies.html

php dephpend.phar dsm src --no-classes | bcat

or pipe it to something like bcat.

Metrics

The most common package metrics have already been implemented, but there are more to come. Check them out by running the following command:

php dephpend.phar metrics src

This feature is not production ready and it's better to rely on PHP Depend for this.

Dynamic Analysis

If you want to analyse an old legacy application which makes little use of type hints and other static information and is therefore hard to analyse consider using dynamic analysis.

dePHPend can analyse XDebug trace files and add that information to the static result.

Setup

Make sure you have XDebug installed and included in your php.ini. Also make sure to include the following in the XDebug section of your php.ini:

; you should already have this somewhere in your php.ini
zend_extension=path-to-your-xdebug/xdebug.so

[xdebug]
...

; add this for tracing function calls
xdebug.auto_trace=1
xdebug.collect_params=1
xdebug.collect_return=3
xdebug.collect_assignments=1
xdebug.trace_format=1

This will slow down PHP A LOT so it is best to put it in a separate file like php-with-traces.ini and call dePHPend using php -c /path/to/php-with-traces.ini.

Usage

First create the sample data by running any PHP script (or website) with the above settings in your php.ini (set xdebug.trace_options=1 if you want to track multiple calls, but this will make the trace file grow BIG).

# use your tests (but make sure to exclude unwanted data using filters)
php -c php-with-traces.ini vendor/bin/phpunit

# or using PHP's inbuilt server etc.
php -c php-with-traces.ini -S localhost:8080

The better the sample run and the more of your application it covers, the better the results are going to be. After that process the trace file using the --dynamic option.

php dephpend.phar text src                  \
    --no-classes                            \
    --filter-from=Mihaeu\\PhpDependencies   \
    --exclude-regex='/(Test)|(Mock)/'       \
    --dynamic=/tmp/traces.12345.xt          

You will probably always end up using filters like --filter-from because the dynamic parser parses everything not just the stuff from the directory provided. So all third party stuff is going to show up as well.

The trace file, by default, will be in your system's temporary folder. This can be changed by setting xdebug.trace_output_dir and xdebug.trace_output_name in your php.ini (see XDebug Function Traces).

Examples

Architecture Constraints

Using the text command it is fairly straightforward to create a script which validates your architecture:

#!/usr/bin/env php
<?php

$output = shell_exec('php dephpend.phar text src --no-classes');
$constraints = [
    'OS --> .*Analyser',
    'Analyser --> .*OS',
];
if (preg_match('/('.implode(')|(', $constraints).')/', $output)) {
    echo 'Architecture violation'.PHP_EOL;
    exit(1);
}

Save this in your .git/hooks/pre-commit or .git/hooks/pre-push and you'll never violate your project managers trust again. You could also include this on every Travis or Jenkins CI build, but I prefer to not bother the CI when I can check it myself.

Architecture Timeline

Executing dePHPend's metric command on any branch git log --pretty=%H and using convert -delay 100 -loop 0 *.png dephpend-timeline.gif you can create a nice animation detailing the evolution of your architecture:

How it all works

Basically the process can be broken down into four steps (the actual work is a bit more complicated and for those interested, I'll publish a paper about it, later this year):

• find all relevant PHP files
• generate an abstract syntax tree using php-parser by the awesome Nikita Popov
• traverse the tree, gathering dependencies along the way
• pass the information to a formatter

Supported Features

Check out tests/features for examples of supported features or run bin/dephpend test-features for a list of supported detection features:

[✓]  creating objects
[✓]  using traits
[✓]  extending other classes
[✓]  type hints in method arguments
[✓]  param return throws in doc comment
[✓]  implementing interfaces
[✓]  php7 return value declaration
[✓]  call to static method
[✗]  return value of known method
[✗]  method arguments and return value from doc
[✗]  known variable passed into method without type hints
[✗]  creating objects from strings

Troubleshooting

Not enough RAM

The PHP-Parser can take up lots of RAM for big applications. You can adjust the RAM limit in your php.ini, but a safer solution would be to call dePHPend by adding php -n -d memory_limit=1024M dephpend.phar ....

License

See LICENSE file