README

Elegantly transform directory structures into traversable tree objects

This library provides object-oriented directory structure mapping and transformation capabilities for PHP applications. It converts physical filesystem hierarchies into traversable tree objects with support for multiple export formats including JSON, XML and visual representations.

✨ 特性

将实体目录结构映射为记忆中的树形结构
支持祖先、父代、子代、兄弟节点的查询
提供 Array JSON XML 多种格式输出
支持树形文本、缩进文本 HTML/UL 等展示格式

📦 安装

composer require hizpark/directory-tree

📂 目录结构

src
├── Contract
│   ├── NodeInterface.php
│   ├── TreeBuilderInterface.php
│   └── TreeMemoryInterface.php
├── Exception
│   └── DirectoryTreeException.php
├── DirectoryNode.php
├── DirectoryTreeBuilder.php
├── DirectoryTreeMemory.php
├── DirectoryTreeTransformer.php
└── DirectoryTreeViewer.php

🚀 使用示例

示例1：基本目录树渲染

use Hizpark\DirectoryTree\DirectoryTreeViewer;

$viewer = new DirectoryTreeViewer();
echo $viewer->render('/path/to/directory');

示例2：多种格式输出

use Hizpark\DirectoryTree\DirectoryTreeViewer;

$viewer = new DirectoryTreeViewer();

// HTML列表格式
echo $viewer->render('/path/to/directory', DirectoryTreeViewer::FORMAT_HTML_LIST);

// Markdown列表格式
echo $viewer->render('/path/to/directory', DirectoryTreeViewer::FORMAT_MARKDOWN_LIST);

// 文本缩进格式
echo $viewer->render('/path/to/directory', DirectoryTreeViewer::FORMAT_TEXT_INDENTED);

// 树状文本格式(默认)
echo $viewer->render('/path/to/directory', DirectoryTreeViewer::FORMAT_TEXT_TREE);

📐 接口说明

NodeInterface

定义目录树节点的基本接口

namespace Hizpark\DirectoryTree\Contract;

interface NodeInterface
{
    public function getParent(): ?NodeInterface;
    public function getPath(): string;
    public function getLocation(): string;
    public function getChildren(): ?array;
}

TreeBuilderInterface

定义构建目录树结构的接口

namespace Hizpark\DirectoryTree\Contract;

interface TreeBuilderInterface
{
    public function build(NodeInterface $root): TreeMemoryInterface;
}

TreeMemoryInterface

定义目录树内存操作的接口

namespace Hizpark\DirectoryTree\Contract;

interface TreeMemoryInterface
{
    public function getRoot(): NodeInterface;
    public function getAncestors(NodeInterface $node): array;
    public function getSiblings(NodeInterface $node): array;
    public function getDescendants(NodeInterface $node): array;
}

🛠️ 核心类说明

DirectoryNode

实现 NodeInterface
代表目录树中的单个节点
包含路径、父节点、子节点等信息
自动验证路径有效性

DirectoryTreeBuilder

实现 TreeBuilderInterface
使用迭代方式构建目录树
自动排序文件和目录
支持大目录处理

DirectoryTreeMemory

实现 TreeMemoryInterface
提供树结构查询功能：获取祖先节点，获取兄弟节点，获取后代节点
使用BFS算法遍历

DirectoryTreeTransformer

目录树结构转换器
支持多种输出格式转换：数组，JSON，XML，HTML列表，Markdown列表，缩进文本，ASCII树状文本
保持原始目录结构
自动处理特殊字符转义

DirectoryTreeViewer

提供简化的渲染接口
支持多种输出格式：HTML列表，Markdown列表，文本缩进，树状文本
内置异常处理

🔍 静态分析

使用 PHPStan 工具进行静态分析，确保代码的质量和一致性：

composer stan

🎯 代码风格

使用 PHP-CS-Fixer 工具检查代码风格：

composer cs:chk

使用 PHP-CS-Fixer 工具自动修复代码风格问题：

composer cs:fix

✅ 单元测试

执行 PHPUnit 单元测试：

composer test

执行 PHPUnit 单元测试并生成代码覆盖率报告：

composer test:coverage

🤝 贡献指南

欢迎 Issue 与 PR，建议遵循以下流程：

Fork 仓库
创建新分支进行开发
提交 PR 前请确保测试通过、风格一致
提交详细描述

📜 License

MIT License. See the LICENSE file for details.

hizpark / directory-tree

Maintainers

Details