{"id":13505190,"url":"https://github.com/mihaeu/dephpend","last_synced_at":"2025-05-15T22:05:03.072Z","repository":{"id":41472469,"uuid":"58526787","full_name":"mihaeu/dephpend","owner":"mihaeu","description":"Detect flaws in your architecture, before they drag you down into the depths of dependency hell ...","archived":false,"fork":false,"pushed_at":"2022-09-24T21:29:11.000Z","size":2368,"stargazers_count":533,"open_issues_count":9,"forks_count":27,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-05-15T22:04:36.713Z","etag":null,"topics":["architecture","php","php-parser","trace"],"latest_commit_sha":null,"homepage":"https://dephpend.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mihaeu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-11T08:20:12.000Z","updated_at":"2025-02-11T21:32:36.000Z","dependencies_parsed_at":"2022-08-21T11:20:19.220Z","dependency_job_id":null,"html_url":"https://github.com/mihaeu/dephpend","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihaeu%2Fdephpend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihaeu%2Fdephpend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihaeu%2Fdephpend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihaeu%2Fdephpend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mihaeu","download_url":"https://codeload.github.com/mihaeu/dephpend/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254430326,"owners_count":22069907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","php","php-parser","trace"],"created_at":"2024-08-01T00:00:59.779Z","updated_at":"2025-05-15T22:05:03.036Z","avatar_url":"https://github.com/mihaeu.png","language":"PHP","funding_links":[],"categories":["Standalone","PHP","Programming Languages"],"sub_categories":["Metrics"],"readme":"\u003ch1 align=\"center\"\u003e\u003ca href=\"https://dephpend.com/\"\u003e\u003cimg src=\"doc/logo.svg\" alt=\"dePHPend lgo\"\u003e\u003c/a\u003e\u003c/h1\u003e\n\n[![Build Status](https://travis-ci.org/mihaeu/dephpend.svg?branch=master)](https://travis-ci.org/github/mihaeu/dephpend)\n[![Coverage Status](https://coveralls.io/repos/github/mihaeu/dephpend/badge.svg)](https://coveralls.io/github/mihaeu/dephpend)\n[![Packagist Version](https://img.shields.io/packagist/v/dephpend/dephpend)](https://packagist.org/packages/dephpend/dephpend)\n[![License MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](https://github.com/mihaeu/dephpend/blob/main/LICENSE)\n[![PHP 7.2](https://img.shields.io/badge/PHP-7.2-blue.svg?style=flat)](https://www.php.net/supported-versions.php)\n[![Join the chat at Gitter](https://badges.gitter.im/dephpend/Lobby.svg)](https://gitter.im/dephpend/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nDetect flaws in your architecture before they drag you down into the depths of dependency hell ...\n\n- [What it does](#what-it-does)\n- [System Requirements](#system-requirements)\n- [Installation](#installation)\n  + [Phive](#phive)\n  + [Composer](#composer)\n  + [Manual .phar download](#manual-phar-download)\n  + [Git](#git)\n- [Usage](#usage)\n  + [Filters](#filters)\n  + [Text](#text)\n  + [UML](#uml)\n  + [Dependency Structure Matrix](#dependency-structure-matrix)\n  + [Metrics](#metrics)\n  + [Dynamic Analysis](#dynamic-analysis)\n    * [Setup](#setup)\n    * [Usage](#usage-1)\n- [Examples](#examples)\n  + [Architecture Constraints](#architecture-constraints)\n  + [Architecture Timeline](#architecture-timeline)\n- [How it all works](#how-it-all-works)\n- [Supported Features](#supported-features)\n- [Troubleshooting](#troubleshooting)\n  + [Not enough RAM](#not-enough-ram)\n- [License](#license)\n\n## What it does\n\ndePHPend helps with bringing your PHP projects back in shape. Over the course\nof a project, we usually keep adding more and more dependencies. Often hidden \nbehind singletons or service locators, these dependencies can quickly become \na maintenance (and testing!) nightmare.\n\ndePHPend analyses your app and attempts to find everything you depend on.\n\nWith this information you can:\n\n - get a quick overview of how an application is structured\n - start refactoring where it's needed the most\n - track architecture violations \n    (maybe your view shouldn't be telling the model what to do?)\n - find out why your changes are breaking tests\n\n\n## System Requirements\n- PHP \u003e= 7.2\n- plantuml (UML Class diagram)\n\n\n## Installation\n\n### Docker\n\nIf you don't want to worry about PHP versions, composer dependencies etc. you can run dePHPend from a docker container:\n\n```bash\n# replace $PATH_TO_INSPECT with whatever path you would live to inspect\ndocker run --rm -v $PATH_TO_INSPECT:/inspect mihaeu/dephpend:latest text /inspect\n```\n\n### Phive\n\n[Phive](https://phar.io) 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:\n\n```bash\nphive install dephpend\n\n# or\n\nphive install --copy dephpend\n```\n\n### Composer\n\nYou can install dePHPend globally, but this might lead to problems if other globally installed QA tools use different versions of PhpParser for instance.\n\n```bash\ncomposer global require dephpend/dephpend:dev-main\n```\n\n### Manual .phar download\n\nDownload the PHAR file by selecting the latest file from [GitHub Releases](https://github.com/mihaeu/dephpend/releases/latest).\n\n### Git\n\n```bash\ngit clone git@github.com:mihaeu/dephpend.git\n# or\ngit clone https://github.com/mihaeu/dephpend.git\n\ncd dephpend\ncomposer install\n```\n\n## Usage\n\nYou 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). \n\n```\n# or bin/dephpend depending on how you installed this\n$ php -n -d extension=tokenizer.so -d extension=json.so -d extension=mbstring.so dephpend.phar                                                                                                 \n      _      _____  _    _ _____               _ \n     | |    |  __ \\| |  | |  __ \\             | |\n   __| | ___| |__) | |__| | |__) |__ _ __   __| |\n  / _` |/ _ \\  ___/|  __  |  ___/ _ \\ '_ \\ / _` |\n | (_| |  __/ |    | |  | | |  |  __/ | | | (_| |\n  \\__,_|\\___|_|    |_|  |_|_|   \\___|_| |_|\\__,_| version 0.8.1\n\nUsage:\n  command [options] [arguments]\n\nOptions:\n  -h, --help            Display this help message\n  -q, --quiet           Do not output any message\n  -V, --version         Display this application version\n      --ansi            Force ANSI output\n      --no-ansi         Disable ANSI output\n  -n, --no-interaction  Do not ask any interactive question\n  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nAvailable commands:\n  dsm            Generate a Dependency Structure Matrix of your dependencies\n  help           Displays help for a command\n  list           Lists commands\n  metrics        Generate dependency metrics\n  test-features  Test support for dependency detection\n  text           Prints a list of all dependencies\n  uml            Generate a UML Class diagram of your dependencies\n```\n\n### Filters\n\nWithout 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:\n\n```bash\n      --no-classes                         Remove all classes and analyse only namespaces.\n  -f, --filter-from=FILTER-FROM            Analyse only dependencies which originate from this namespace.\n      --filter-namespace=FILTER-NAMESPACE  Analyse only classes where both to and from are in this namespace.\n  -d, --depth[=DEPTH]                      Output dependencies as packages instead of single classes. [default: 0]\n  -e, --exclude-regex=EXCLUDE-REGEX        Exclude all dependencies which match the (PREG) regular expression.\n\n      --dynamic=DYNAMIC                    Adds dependency information from dynamically analysed function traces, for more information check out https://dephpend.com\n  -u, --underscore-namespaces              Parse underscores in Class names as namespaces.\n      --internals                          Check for dependencies from internal PHP Classes like SplFileInfo.\n```\n\nFor more info just run `php dephpend.phar help text`.\n\n### Text\n\nFor 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: \n\n```bash\nphp dephpend.phar text src | grep XYZ\n\n# or for more complex applications use filters\nphp dephpend.phar text symfony --no-classes --depth 3 --exclude-regex='/Test/'\n```\n\n### UML\n\nGenerates UML class or package diagrams of your source code. Requires [PlantUML](http://plantuml.com/) to be installed.\n\nYou can either run \n\n```bash\nphp dephpend.phar uml --output=uml.png src\n\n# or for post-processing\nphp dephpend.phar uml --output=uml.png --keep-uml src\n``` \n\nbut 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.\n\n### Dependency Structure Matrix\n\nIf 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.\n\nThis feature is still under construction and right now it's not really fun to use. If you still want to try run \n\n```bash\nphp dephpend.phar dsm src \u003e dependencies.html\n\nphp dephpend.phar dsm src --no-classes | bcat\n``` \nor pipe it to something like [bcat](https://rtomayko.github.io/bcat/).\n\n### Metrics\n\nThe most common package metrics have already been implemented, but there are more to come. Check them out by running the following command:\n\n```bash\nphp dephpend.phar metrics src\n```\n\nThis feature is not production ready and it's better to rely on [PHP Depend](https://pdepend.org) for this.\n\n### Dynamic Analysis\n\nIf 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.\n\ndePHPend can analyse XDebug trace files and add that information to the static result.\n\n#### Setup\n\nMake 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`:\n\n```ini\n; you should already have this somewhere in your php.ini\nzend_extension=path-to-your-xdebug/xdebug.so\n\n[xdebug]\n...\n\n; add this for tracing function calls\nxdebug.auto_trace=1\nxdebug.collect_params=1\nxdebug.collect_return=3\nxdebug.collect_assignments=1\nxdebug.trace_format=1\n\n```\n\nThis 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`.\n\n#### Usage\n\nFirst 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).\n\n```bash\n# use your tests (but make sure to exclude unwanted data using filters)\nphp -c php-with-traces.ini vendor/bin/phpunit\n\n# or using PHP's inbuilt server etc.\nphp -c php-with-traces.ini -S localhost:8080\n```\n\nThe 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.\n\n```bash\nphp dephpend.phar text src                  \\\n    --no-classes                            \\\n    --filter-from=Mihaeu\\\\PhpDependencies   \\\n    --exclude-regex='/(Test)|(Mock)/'       \\\n    --dynamic=/tmp/traces.12345.xt          \n```\n\nYou 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.\n\nThe 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](https://xdebug.org/docs/execution_trace)).\n\n## Examples\n\n### Architecture Constraints\n\nUsing the `text` command it is fairly straightforward to create a script which validates your architecture:\n\n```php\n#!/usr/bin/env php\n\u003c?php\n\n$output = shell_exec('php dephpend.phar text src --no-classes');\n$constraints = [\n    'OS --\u003e .*Analyser',\n    'Analyser --\u003e .*OS',\n];\nif (preg_match('/('.implode(')|(', $constraints).')/', $output)) {\n    echo 'Architecture violation'.PHP_EOL;\n    exit(1);\n}\n```\n\nSave 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.\n\n### Architecture Timeline\n\nExecuting 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:\n\n![dePHPend Timeline](./doc/dephpend-timeline.gif)\n\n## How it all works\n\nBasically 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):\n\n - find all relevant PHP files\n - generate an abstract syntax tree using [php-parser](https://github.com/nikic/PHP-Parser) by the awesome Nikita Popov\n - traverse the tree, gathering dependencies along the way\n - pass the information to a formatter\n\n## Supported Features\n\nCheck out `tests/features` for examples of supported features or run `bin/dephpend test-features` for a list of supported detection features:\n\n```bash\n[✓]  creating objects\n[✓]  using traits\n[✓]  extending other classes\n[✓]  type hints in method arguments\n[✓]  param return throws in doc comment\n[✓]  implementing interfaces\n[✓]  php7 return value declaration\n[✓]  call to static method\n[✗]  return value of known method\n[✗]  method arguments and return value from doc\n[✗]  known variable passed into method without type hints\n[✗]  creating objects from strings\n```\n\n## Troubleshooting\n\n### Not enough RAM\n\nThe 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 ...`.\n\n## License\n\nSee [LICENSE](LICENSE) file\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmihaeu%2Fdephpend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmihaeu%2Fdephpend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmihaeu%2Fdephpend/lists"}