README

A powerful PHP library to visualize project directory structures with .gitignore support and interactive HTML output. Perfect for documentation, project analysis, and development tools.

✨ Features

🌳 Interactive Tree View: Beautiful HTML tree structure with expand/collapse functionality
🚫 Gitignore Support: Respects .gitignore rules automatically
📊 Multiple Output Formats: HTML, JSON, and Array formats
🔒 Security First: Built-in protection against accessing system directories
🎨 VS Code Theme: Dark theme inspired by Visual Studio Code
📱 Responsive Design: Works perfectly on desktop and mobile devices
⚡ Framework Independent: Works with any PHP project or framework
🔧 Easy Integration: Simple API with fluent interface
📈 Statistics: File counts, sizes, and project metrics
⌨️ Keyboard Shortcuts: Ctrl+E (expand), Ctrl+C (collapse), Ctrl+R (refresh)

🚀 Installation

Via Composer (Recommended)

composer require arcanisgk/project-structure-viewer

Manual Installation

Download the latest release
Extract to your project
Include the autoloader or manually require the files

📖 Quick Start

Basic Usage

<?php
require_once 'vendor/autoload.php';

use ProjectStructureViewer\ProjectStructureViewer;

// Create viewer for current directory
$viewer = ProjectStructureViewer::create();

// Or specify a custom directory
$viewer = ProjectStructureViewer::for('/path/to/your/project');

// Display as HTML (in browser)
$viewer->display();

// Or get HTML string
$html = $viewer->toHtml('My Project Structure');

// Get JSON output
$json = $viewer->toJson();

// Get array data
$array = $viewer->toArray();

Web Access (Automatic URL)

After installation, you can access the viewer via web browser:

http://localhost/structure-project
http://localhost/structure-project?path=/custom/path
http://localhost/structure-project?format=json

🌐 Web Integration Examples

Standalone PHP

<?php
require_once 'vendor/autoload.php';

use ProjectStructureViewer\ProjectStructureViewer;

$viewer = ProjectStructureViewer::for(__DIR__);
$viewer->display('My Project Structure');
?>

Laravel Integration

// routes/web.php
Route::get('/structure', function () {
    $viewer = ProjectStructureViewer\ProjectStructureViewer::for(base_path());
    return response($viewer->toHtml('Laravel Project Structure'))
        ->header('Content-Type', 'text/html');
});

// Or as JSON API
Route::get('/api/structure', function () {
    $viewer = ProjectStructureViewer\ProjectStructureViewer::for(base_path());
    return response()->json($viewer->toArray());
});

Symfony Integration

// src/Controller/StructureController.php
<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use ProjectStructureViewer\ProjectStructureViewer;

class StructureController extends AbstractController
{
    #[Route('/structure', name: 'project_structure')]
    public function index(): Response
    {
        $viewer = ProjectStructureViewer::for($this->getParameter('kernel.project_dir'));
        
        return new Response(
            $viewer->toHtml('Symfony Project Structure'),
            200,
            ['Content-Type' => 'text/html']
        );
    }
}

🎛️ Configuration Options

Output Formats

// HTML with custom title
$html = $viewer->toHtml('Custom Project Title');

// JSON with custom flags
$json = $viewer->toJson(JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

// Compact JSON (structure only)
$renderer = new ProjectStructureViewer\Renderers\JsonRenderer($projectRoot);
$compactJson = $renderer->renderCompact($structure);

// Flat structure (all paths in single array)
$flatJson = $renderer->renderFlat($structure);

Custom Project Root

// Different ways to specify project root
$viewer1 = new ProjectStructureViewer('/absolute/path/to/project');
$viewer2 = ProjectStructureViewer::for('/absolute/path/to/project');
$viewer3 = ProjectStructureViewer::create(); // Uses current directory

🔧 Advanced Usage

Working with Gitignore

$viewer = ProjectStructureViewer::for('/path/to/project');

// Access gitignore parser
$gitignoreParser = $viewer->getGitignoreParser();

// Check if path should be ignored
$shouldIgnore = $gitignoreParser->shouldIgnore('node_modules', true);

// Get all gitignore rules
$rules = $gitignoreParser->getRules();

Custom Rendering

use ProjectStructureViewer\Renderers\HtmlRenderer;
use ProjectStructureViewer\Renderers\JsonRenderer;

$viewer = ProjectStructureViewer::for('/path/to/project');
$structure = $viewer->generateStructure();

// Custom HTML rendering
$htmlRenderer = new HtmlRenderer('/path/to/project');
$customHtml = $htmlRenderer->renderFullPage($structure, 'Custom Title');

// Custom JSON rendering with statistics
$jsonRenderer = new JsonRenderer('/path/to/project');
$jsonWithStats = $jsonRenderer->render($structure);

🛡️ Security Features

Path Validation: Prevents access to system directories
Input Sanitization: All user inputs are properly sanitized
Directory Restrictions: Built-in blacklist for sensitive paths
Safe File Operations: All file operations include proper error handling

🎨 Customization

CSS Styling

The HTML output includes embedded CSS that you can customize:

// Get the HTML and modify CSS
$html = $viewer->toHtml();
$customHtml = str_replace(
    'background-color: #1e1e1e',
    'background-color: #your-color',
    $html
);

JavaScript Functionality

The viewer includes these interactive features:

Click folders to expand/collapse
Ctrl+E: Expand all folders
Ctrl+C: Collapse all folders
Ctrl+R: Refresh page
Hover effects and smooth animations

📊 Output Examples

HTML Output

Interactive tree view with VS Code-inspired dark theme
File/folder icons and syntax highlighting
File size, permissions, and modification dates
Responsive design for all screen sizes
Real-time statistics (file count, total size)

JSON Output

{
    "project_root": "/path/to/project",
    "project_name": "my-project",
    "generated_at": "2024-01-15 10:30:45",
    "generator": "Project Structure Viewer",
    "version": "1.0",
    "structure": [...],
    "statistics": {
        "total_files": 42,
        "total_directories": 8,
        "total_size_bytes": 1048576,
        "total_size_formatted": "1.00 MB",
        "file_extensions": {
            "php": 15,
            "js": 8,
            "css": 3
        }
    }
}

🔧 Development

Requirements

PHP 8.0 or higher
Composer (for dependency management)
Web server (Apache, Nginx, or PHP built-in server)

Running Tests

composer test

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📝 License

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

👨‍💻 Author

Walter Nuñez

Email: icarosnet@gmail.com
GitHub: @arcanisgk

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📞 Support

If you encounter any issues or have questions:

Check the Issues page
Create a new issue if your problem isn't already reported
Provide as much detail as possible including PHP version, OS, and error messages

🔄 Changelog

Version 1.0.0

Initial release
Interactive HTML tree view
Gitignore support
Multiple output formats
Framework-independent design
Automatic web URL setup
Security features
Responsive design

⭐ If you find this project useful, please consider giving it a star on GitHub!

arcanisgk / project-structure-viewer

Maintainers

Details