README

Build, parse, traverse, print, edit, and compare filesystem trees in PHP.

ALTO Tree turns paths, directories, Git repositories, and textual tree diagrams into one typed model. The same tree can then be filtered, rendered, traversed, split, merged, or compared without coupling the operation to its original source.

use Alto\Tree\Printer\TreePrinter;
use Alto\Tree\TreeBuilder;

$tree = TreeBuilder::fromPaths([
    'project/src/App.php',
    'project/tests/AppTest.php',
], 'project');

echo (new TreePrinter())->print($tree);
// ├── src
// │   └── App.php
// └── tests
//     └── AppTest.php

The package has no PHP package runtime dependencies. It provides dedicated providers, visitors, printers, and diff objects while keeping the core tree model small and fully typed.

Installation

Install ALTO Tree with Composer:

composer require alto/tree

ALTO Tree requires PHP 8.2 or later and the Mbstring extension. Mbstring is available in most PHP distributions but must be enabled.

Quick Start

Build a tree from paths and inspect its nodes:

use Alto\Tree\TreeBuilder;

$tree = TreeBuilder::fromPaths([
    'project/src/Controller/HomeController.php',
    'project/src/Entity/User.php',
], 'project');

echo $tree->children['src']->children['Entity']->children['User.php']->path;

The root is a Tree; every descendant is a TreeNode with its path, name, directory flag, children, and optional filesystem metadata.

Building Trees

Create trees from known paths, a directory, a Git repository, or a custom provider:

$filesystem = TreeBuilder::fromFilesystem(__DIR__, [
    'max_depth' => 3,
    'exclude' => ['vendor', '.git'],
]);

$tracked = TreeBuilder::fromGit(__DIR__);
$modified = TreeBuilder::fromGit(__DIR__, ['modified_only' => true]);

Read Building trees for every provider, filesystem metadata, Git modes, and the custom provider contract.

Parsing and Printing

TreeParser reads box-drawing trees, bullet lists, and plain indentation. TreePrinter renders the model with depth, pattern, visibility, sorting, metadata, and terminal-color options.

use Alto\Tree\Parser\TreeParser;
use Alto\Tree\Printer\TreePrinter;

$tree = (new TreeParser())->parse("project\n  src\n    App.php");
$output = (new TreePrinter())->print($tree, ['pattern' => '*.php']);

See Parsing trees and Printing trees.

Traversing and Editing

Use visitors to collect or analyze nodes. Tree edits return cloned structures, leaving their inputs unchanged.

$subtree = $tree->split('project/src');
$merged = $tree->merge($anotherTree);
$paths = Alto\Tree\Traverser\TreeFlattener::flatten($merged);

See Traversing trees and Editing trees.

Comparing Trees

Classify paths as added, removed, or unchanged, then inspect or print the result:

use Alto\Tree\Diff\TreeDiff;

$diff = TreeDiff::compare($before, $after);

echo $diff->getSummary();

Read Comparing trees for result accessors and output formats. The complete guide links every topic.

Contributing

Contributions of all kinds are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request.

Before submitting code, run:

# Runs PHP CS Fixer, PHPStan, and PHPUnit
composer qa

Changes to public behavior should include tests and documentation.

Support

ALTO Tree is open source. You can support its continued development through GitHub Sponsors.

Sharing this package with others or starring it on GitHub is also much appreciated.

License

ALTO Tree is released by ALTO PHP under the MIT License.

alto / tree

Maintainers

Package info

Fund package maintenance!

Statistics

Security