README

A flexible PHP library for rendering file system trees in various formats (Markdown, JSON, XML, HTML). It supports filtering, metadata enrichment (file size, permissions), and includes a CLI tool.

Features

Multiple Output Formats: Markdown (ASCII tree), JSON, XML, HTML.
Filtering: Whitelist file extensions and exclude specific directories.
Metadata: Optionally display file sizes and permissions.
Security: Uses adachsoft/normalized-safe-path to prevent path traversal.
CLI Tool: Includes a render-tree binary for command-line usage.
Customizable: Fluent Builder pattern for easy configuration.

Installation

composer require adachsoft/file-tree-render

Usage

Basic Usage

use AdachSoft\FileTreeRender\FileTreeRenderBuilder;

$renderer = (new FileTreeRenderBuilder())
    ->withBasePath(__DIR__) // Set the root directory to scan
    ->build();

// Render the tree relative to the base path
echo $renderer->render('.');

Advanced Configuration

use AdachSoft\FileTreeRender\FileTreeRenderBuilder;
use AdachSoft\FileTreeRender\Renderer\JsonTreeRenderer;

$renderer = (new FileTreeRenderBuilder())
    ->withBasePath('/var/www/project')
    // Only show these extensions
    ->withAllowedExtensions(['php', 'md', 'json'])
    // Exclude these directories from recursion
    ->withExcludedDirectories(['vendor', 'node_modules', '.git'])
    // Optionally show excluded items (without recursing into them)
    ->withShowExcludedDirectories(true)
    ->withShowExcludedFiles(true)
    // Enable metadata addons
    ->withAddons(['filesize', 'permissions'])
    // Use a specific renderer (default is Markdown)
    ->withRenderer(new JsonTreeRenderer())
    ->build();

echo $renderer->render('src');

Available Renderers

MarkdownTreeRenderer (Default): Generates a text-based tree suitable for Markdown files or console output.
JsonTreeRenderer: Generates a JSON representation of the tree.
XmlTreeRenderer: Generates an XML representation.
HtmlTreeRenderer: Generates an HTML unordered list (<ul>).

CLI Tool

The package comes with a binary bin/render-tree that can be used directly from the command line.

# Basic usage (renders current directory in Markdown)
./bin/render-tree

# Render a specific subdirectory
./bin/render-tree src

# Output as JSON
./bin/render-tree src --format=json

# Disable metadata
./bin/render-tree --no-metadata

# Show excluded directories (e.g. vendor) but don't recurse into them
./bin/render-tree --show-excluded-dirs

Options:

path: Path relative to project root (default: .)
format: One of: markdown, md, json, xml, html (default: markdown)
--metadata=default: Enable default metadata providers (size, permissions)
--metadata=none / --no-metadata: Disable metadata
--show-excluded-dirs: Show excluded directories (without recursion)
--show-excluded-files: Show excluded files
--dump-metadata: Print a debug tree with raw node metadata

Testing

composer test

License

MIT

adachsoft / file-tree-render

Maintainers

Details