adachsoft / code-graph-php

v0.2.0 2026-11-03 08:14 UTC

Requires

• php: ^8.3
• adachsoft/code-graph-contract: ^0.1.0
• adachsoft/console-io: ^0.2.0
• nikic/php-parser: ^5.0

Requires (Dev)

• adachsoft/php-code-style: ^0.7.1
• friendsofphp/php-cs-fixer: ^3.95
• phpstan/phpstan: ^2.3
• phpunit/phpunit: ^12.0 || ^13.0
• rector/rector: ^2.8
• symplify/phpstan-rules: ^14.9

MIT

• Arkadiusz Adach

• php
• ast
• static-analysis
• dependency-graph
• code-graph

Published on Packagist.org on 2026-11-03 07:56 UTC

README

adachsoft/code-graph-php extracts a graph of declarations and statically verifiable relationships from PHP source files. It implements the language-agnostic contracts provided by adachsoft/code-graph-contract and returns a CodeGraph containing typed nodes and edges.

Features

• Discovers and parses PHP source files with nikic/php-parser.
• Extracts class-like declarations and relationships into the shared code graph model.
• Configures excluded directories, file extensions, known internal namespaces, and module namespace depth.
• Optionally omits relationships to external code.
• Reports unreadable source paths and invalid PHP syntax with dedicated exceptions.

Requirements

• PHP 8.3 or later.
• Composer.

Installation

composer require adachsoft/code-graph-php

Command-line usage

Composer installs the code-graph executable in vendor/bin:

vendor/bin/code-graph [options] [source-path]

The source path defaults to the current directory. The command writes JSON to standard output by default; use --output to write the graph to a file. Examples:

vendor/bin/code-graph src
vendor/bin/code-graph src --format=json --output=var/graph.json

Options include:

• --format <format>: select an export format (defaults to json; run --help to see available formats).
• -o, --output <path>: write the graph to a file instead of standard output.
• --exclude-vendor / --include-vendor: exclude vendor dependencies by default or include them.
• --exclude-dir=<names>: exclude additional comma-separated directory names.
• --module=<name> or --target-module=<name>: limit the export to a module.
• -h, --help: display command usage and available formats.

Quick start

<?php

declare(strict_types=1);

use AdachSoft\CodeGraphPhp\Dto\PhpExtractionConfigDto;
use AdachSoft\CodeGraphPhp\Factory\PhpCodeGraphExtractorFactory;

$extractor = PhpCodeGraphExtractorFactory::create(
    new PhpExtractionConfigDto(
        knownInternalNamespaces: ['Acme\\Application'],
        excludeVendorRelations: true,
    ),
);

$graph = $extractor->extract(__DIR__ . '/src');

foreach ($graph->getNodes() as $node) {
    printf("%s (%s)\n", $node->id, $node->kind->value);
}

foreach ($graph->getEdges() as $edge) {
    printf("%s -[%s]-> %s\n", $edge->sourceId, $edge->relationType->value, $edge->targetId);
}

The factory creates a parser for the host PHP version and supplies the default file-discovery, vendor-filtering, and module-resolution services. By default, extraction looks for PHP files and excludes common dependency, test, and cache directories.

Per-call options

The shared contract provides ExtractionOptionsDto for options that apply to a single extraction:

use AdachSoft\CodeGraphContract\Dto\ExtractionOptionsDto;

$graph = $extractor->extract(
    __DIR__ . '/src',
    new ExtractionOptionsDto(
        excludeVendor: true,
        excludedDirectories: ['vendor', 'node_modules', '.git', 'tests'],
    ),
);

Errors

PhpCodeGraphExtractor::extract() throws FileReadException when the source directory or a discovered file cannot be read. It throws InvalidPhpSourceException when a PHP file has invalid syntax. Both exceptions are in the AdachSoft\CodeGraphPhp\Exception namespace.

Examples

See Extracting a PHP code graph for a complete usage example.