README

A modern PHP library for building, parsing, traversing, and printing tree structures representing file and directory hierarchies.

Why Alto Tree?

Alto Tree makes it easy to work with hierarchical file structures in PHP. Whether you need to:

• Visualize directory structures in your CLI tools
• Parse output from the tree command
• Analyze project organization
• Generate documentation with file trees
• Compare or merge directory structures

Alto Tree provides a clean, type-safe API with comprehensive documentation and examples.

Features

• Build Trees: Create tree structures from arrays of file/directory paths
• Parse Trees: Parse string representations of trees in multiple formats (ASCII art, bullets, indented)
• Print Trees: Generate beautiful ASCII art representations of tree structures
• Traverse Trees: Use the visitor pattern to traverse and analyze tree structures
• Manipulate Trees: Split, merge, and append operations on tree nodes
• Compare Trees: Diff two trees to identify added, removed, and unchanged nodes
• Type-Safe: Fully typed with PHP 8.2+ features and strict types
• Well-Tested: Comprehensive test coverage with PHPUnit
• Modern: PSR-12 compliant, uses modern PHP features

Requirements

• PHP 8.2 or higher

Installation

Install via Composer:

composer require alto/tree

Quick Start

Basic Example

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

// Build a tree from paths
$paths = ['src/Controller/HomeController.php', 'src/Entity/User.php'];
$tree = TreeBuilder::fromPaths($paths, 'my-app');

// Print the tree
$printer = new TreePrinter();
echo $printer->print($tree);

Build from Filesystem

// Scan actual filesystem
$tree = TreeBuilder::fromFilesystem('/path/to/project', [
    'max_depth' => 3,
    'exclude' => ['vendor', 'node_modules'],
]);

Build from Git Repository

// Get git-tracked files
$tree = TreeBuilder::fromGit('/path/to/repo');

// Or get only modified files
$tree = TreeBuilder::fromGit('/path/to/repo', [
    'modified_only' => true,
]);

Usage

Building Trees

Alto Tree uses the Provider Pattern to support multiple data sources.

From Array of Paths

use Alto\Tree\TreeBuilder;

$paths = [
    'src/Controller/HomeController.php',
    'src/Controller/UserController.php',
    'src/Entity/User.php',
];

$tree = TreeBuilder::fromPaths($paths, 'src');

From Filesystem

Scan actual files and directories:

$tree = TreeBuilder::fromFilesystem('/path/to/project', [
    'max_depth' => 3,                    // Limit depth (default: unlimited)
    'exclude' => ['vendor', '.git'],     // Exclude patterns
    'include_hidden' => false,           // Include hidden files (default: false)
    'with_metadata' => true,             // Include file metadata (default: false)
]);

From Git Repository

Build tree from git-tracked files:

// All tracked files
$tree = TreeBuilder::fromGit('/path/to/repo');

// Only modified files
$tree = TreeBuilder::fromGit('/path/to/repo', [
    'modified_only' => true,
]);

// Diff between branches
$tree = TreeBuilder::fromGit('/path/to/repo', [
    'diff' => 'main..feature',
]);

// Files from specific commit
$tree = TreeBuilder::fromGit('/path/to/repo', [
    'commit' => 'abc123',
]);

Custom Providers

Create your own provider for any data source:

use Alto\Tree\Provider\TreeSourceProviderInterface;
use Alto\Tree\Provider\NodeData;

class ComposerProvider implements TreeSourceProviderInterface
{
    public function getRootPath(): string { return 'dependencies'; }

    public function getNodes(): array
    {
        // Parse composer.lock, return NodeData objects
        return [
            new NodeData('vendor/package', true),
            new NodeData('vendor/package/src/File.php', false),
        ];
    }
}

$tree = TreeBuilder::from(new ComposerProvider());

Parsing a Tree from String

Parse a string representation of a tree back into a Tree object:

use Alto\Tree\Parser\TreeParser;

$input = <<<EOT
src
├── Controller
│   ├── HomeController.php
│   └── UserController.php
└── Entity
    └── User.php
EOT;

$parser = new TreeParser();
$tree = $parser->parse($input);

The parser supports multiple formats:

ASCII Tree Format (with box-drawing characters)

src
├── Controller
│   └── HomeController.php
└── Entity
    └── User.php

Bullet List Format

src
* Controller
  * HomeController.php
* Entity
  * User.php

Dash List Format

src
- Controller
  - HomeController.php
- Entity
  - User.php

Simple Indentation (2 or 4 spaces)

src
  Controller
    HomeController.php
  Entity
    User.php

Traversing a Tree

Use the visitor pattern to traverse and analyze tree structures:

use Alto\Tree\Traverser\TreeTraverser;
use Alto\Tree\Visitor\CollectorVisitor;

$traverser = new TreeTraverser();
$collector = new CollectorVisitor();

$traverser->addVisitor($collector);
$traverser->traverse($tree);

echo $collector->getSummary();
// Output: Found 4 files and 3 directories

$files = $collector->getFiles();
$directories = $collector->getDirectories();

Flattening a Tree

Convert a tree structure into a flat array of paths:

use Alto\Tree\TreeFlattener;

$paths = TreeFlattener::flatten($tree);
// Returns: ['src/Controller', 'src/Controller/HomeController.php', ...]

// Rebuild a tree from paths
$newTree = TreeFlattener::buildTree($paths);

Splitting a Tree

Extract a subtree from a specific path:

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

// Extract just the Controller subtree
$controllerTree = $tree->split('src/Controller');

Merging Trees

Combine two trees into one:

$tree1 = TreeBuilder::fromPaths(['src/Controller/HomeController.php']);
$tree2 = TreeBuilder::fromPaths(['src/Entity/User.php']);

$merged = $tree1->merge($tree2);
// Now contains both Controller and Entity directories

Appending Nodes

Add a node as a child of another node:

$mainTree = TreeBuilder::fromPaths(['src/Controller/HomeController.php']);
$extraNode = TreeBuilder::fromPaths(['config/app.php']);

$result = $mainTree->append($extraNode, 'config');
// Adds the config tree as a child of mainTree

Comparing Trees (Diff)

Compare two trees to identify changes:

use Alto\Tree\Diff\TreeDiff;
use Alto\Tree\Diff\DiffPrinter;

$oldTree = TreeBuilder::fromPaths(['project/src/App.php']);
$newTree = TreeBuilder::fromPaths([
    'project/src/App.php',
    'project/src/Router.php',  // Added
]);

$diff = TreeDiff::compare($oldTree, $newTree);

echo $diff->getSummary();  // "+1"
echo $diff->getDetailedSummary();  // "Added: 1 file"

// Print visual diff
$printer = new DiffPrinter();
echo $printer->print($diff);

// Get added/removed nodes
$added = $diff->getAdded();
$removed = $diff->getRemoved();
$unchanged = $diff->getUnchanged();

API Reference

Core Classes

Tree

Final class representing the root of a tree structure. Extends TreeNode.

TreeNode

Represents a node (file or directory) in the tree.

Properties:

• string $path - Full path to the node
• string $name - Base name (file/directory name)
• bool $isDir - Whether this is a directory
• array<string, TreeNode> $children - Child nodes
• ?array $metadata - Optional metadata (size, mtime, permissions, etc.)

Metadata: When using with_metadata: true option with FileSystemProvider, the metadata array contains:

• size (int) - File size in bytes
• mtime (int) - Last modification timestamp
• permissions (string) - Unix permissions (e.g., "0755")
• is_readable (bool) - Whether file is readable
• is_writable (bool) - Whether file is writable

Methods:

• addChild(TreeNode $child): void - Add a child node
• split(string $path): ?TreeNode - Extract a subtree
• merge(TreeNode $other): TreeNode - Merge with another node
• append(TreeNode $child, ?string $childName = null): TreeNode - Append a child node

TreeBuilder

Final class factory for building trees from paths.

Methods:

• static fromPaths(array $paths, string $rootPath = 'src'): Tree - Build a tree from array of paths

Parsing

TreeParser

Final class that parses string representations into tree structures.

Methods:

• parse(string $tree): Tree - Parse a tree string into a Tree object

Printing

TreePrinter

Final class that generates ASCII art representation of trees with extensive formatting and filtering options.

Methods:

• print(TreeNode $tree, array $options = []): string - Generate tree visualization

Printer Options:

Filtering:

• show_hidden: bool - Show/hide hidden files (default: true)
• files_only: bool - Show only files, exclude directories (default: false)
• dirs_only: bool - Show only directories, exclude files (default: false)
• pattern: string - Filter by shell-style pattern compatible with PHP fnmatch (e.g., '*.php')
• max_depth: int - Limit tree depth (default: unlimited)

Display:

• show_size: bool - Show file sizes in human-readable format (default: false)
• show_date: bool - Show modification dates (default: false)
• show_permissions: bool - Show Unix permissions (default: false)

Sorting:

• sort_by: string - Sort by: 'name', 'size', 'date', 'type' (default: null = preserve order)
• sort_order: string - Sort order: 'asc', 'desc' (default: 'asc')

Visual:

• colors: bool - Use ANSI colors for terminal output (default: false)

Example:

$printer = new TreePrinter();

// Simple tree
echo $printer->print($tree);

// With icons and colors
echo $printer->print($tree, [
    'icons' => true,
    'colors' => true,
]);

// Show only PHP files with sizes, sorted by size
echo $printer->print($tree, [
    'pattern' => '*.php',
    'show_size' => true,
    'sort_by' => 'size',
    'sort_order' => 'desc',
]);

// Directories only with depth limit
echo $printer->print($tree, [
    'dirs_only' => true,
    'max_depth' => 2,
]);

Traversal

TreeTraverser

Final class that traverses tree structures using the visitor pattern.

Methods:

• addVisitor(VisitorInterface $visitor): self - Add a visitor
• traverse(TreeNode $node): void - Traverse the tree

CollectorVisitor

Final class that collects files and directories during traversal.

Methods:

• getFiles(): array - Get collected file paths
• getDirectories(): array - Get collected directory paths
• getTotalFiles(): int - Get file count
• getTotalDirectories(): int - Get directory count
• getSummary(): string - Get formatted summary

TreeFlattener

Final class utility for flattening and rebuilding trees.

Methods:

• static flatten(TreeNode $tree): array - Flatten tree to paths array
• static buildTree(array $paths, ?string $rootPath = null): Tree - Build tree from paths

Comparison

TreeDiff

Final class that compares two trees and identifies differences.

Methods:

• static compare(TreeNode $oldTree, TreeNode $newTree): DiffResult - Compare two trees

DiffResult

Readonly class containing the results of a tree comparison.

Methods:

• getAdded(): array - Get nodes added in new tree
• getRemoved(): array - Get nodes removed from old tree
• getUnchanged(): array - Get nodes present in both trees
• hasChanges(): bool - Check if there are any changes
• getSummary(): string - Get compact summary (e.g., "+5 -3")
• getDetailedSummary(): string - Get detailed summary with counts

DiffPrinter

Final class that prints visual representations of tree differences.

Methods:

• print(DiffResult $diff, array $options = []): string - Print diff as tree with +/- markers
• printSummary(DiffResult $diff): string - Print detailed summary
• printUnified(DiffResult $diff, string $oldLabel, string $newLabel): string - Print unified diff format

Testing

Run the test suite:

composer test

Run static analysis:

composer phpstan

Run code style fixer:

composer cs-fix

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.