Skip to content

Latest commit

 

History

History
151 lines (121 loc) · 5.26 KB

structure.md

File metadata and controls

151 lines (121 loc) · 5.26 KB

Project Structure

This document describes the organization and purpose of each folder and file in the Project Structure Viewer library.

Root Directory

project-structure-viewer/
├── src/                          # Main source code directory
├── public/                       # Web-accessible files
├── install/                      # Installation and setup scripts
├── tests/                        # Unit tests (future)
├── composer.json                 # Composer configuration and dependencies
├── LICENSE                       # MIT license file
├── README.md                     # Main documentation and usage guide
├── structure.md                  # This file - project structure documentation
├── features.md                   # Feature list and implementation status
└── task_pending.md               # Pending tasks and future improvements

Source Code (src/)

Main Classes

  • ProjectStructureViewer.php - Main library class that orchestrates the entire functionality
    • Handles directory scanning and structure generation
    • Provides multiple output formats (HTML, JSON, Array)
    • Manages gitignore integration
    • Offers static factory methods for easy instantiation

Utilities (src/Utils/)

  • GitignoreParser.php - Handles .gitignore file parsing and pattern matching
    • Loads and parses .gitignore rules
    • Converts gitignore patterns to regex
    • Provides path filtering functionality
    • Supports negation patterns and complex gitignore syntax

Renderers (src/Renderers/)

  • HtmlRenderer.php - Generates interactive HTML output

    • Creates complete HTML pages with embedded CSS and JavaScript
    • Provides VS Code-inspired dark theme
    • Includes responsive design for mobile devices
    • Handles tree structure rendering with expand/collapse functionality

  • JsonRenderer.php - Generates JSON output in various formats

    • Standard JSON with metadata and statistics
    • Compact JSON (structure only)
    • Flat JSON (all paths in single array)
    • Calculates project statistics (file counts, sizes, extensions)

Public Files (public/)

  • index.php - Web entry point for automatic URL access
    • Handles http://localhost/structure-project requests
    • Auto-detects project root directory
    • Provides security checks and error handling
    • Supports multiple output formats via query parameters
    • Includes comprehensive error pages with troubleshooting

Installation (install/)

  • setup.php - Post-installation configuration script
    • Runs automatically after composer install
    • Sets up automatic web URL access
    • Creates necessary directories and files
    • Provides usage instructions and examples
    • Handles different web server configurations

Configuration Files

composer.json

  • Package metadata and dependencies
  • PSR-4 autoloading configuration
  • Post-install scripts
  • Development dependencies (PHPUnit)
  • Packagist publishing information

LICENSE

  • MIT license terms
  • Copyright information
  • Usage permissions and limitations

Documentation Files

README.md

  • Complete usage guide and API documentation
  • Installation instructions
  • Framework integration examples
  • Feature overview and screenshots
  • Contributing guidelines

structure.md (this file)

  • Detailed project structure explanation
  • File and directory purposes
  • Architecture overview

features.md

  • Implemented features list
  • Feature status and completion
  • Technical specifications

task_pending.md

  • Future improvements and enhancements
  • Bug fixes and optimizations
  • Community feature requests

Architecture Overview

Design Principles

  1. Single Responsibility: Each class has a specific, well-defined purpose
  2. Framework Independence: No external framework dependencies
  3. Extensibility: Easy to add new renderers and output formats
  4. Security First: Built-in security checks and validations
  5. PSR Standards: Follows PSR-4 autoloading and PSR-12 coding standards

Data Flow

  1. ProjectStructureViewer scans directory structure
  2. GitignoreParser filters files based on .gitignore rules
  3. Structure data is passed to appropriate renderer
  4. Renderer generates final output (HTML, JSON, etc.)
  5. Output is returned to user or displayed in browser

Key Components

  • Scanner: Directory traversal and file information gathering
  • Filter: Gitignore-based file filtering
  • Renderer: Output format generation
  • Security: Path validation and access control
  • Web Interface: Browser-based access and interaction

File Naming Conventions

  • Classes: PascalCase (e.g., ProjectStructureViewer.php)
  • Namespaces: Follow PSR-4 standards
  • Methods: camelCase with descriptive names
  • Constants: UPPER_SNAKE_CASE
  • Files: kebab-case for documentation, PascalCase for classes

Dependencies

Runtime Dependencies

  • PHP 8.0+: Modern PHP features and type declarations
  • Composer: Autoloading and package management

Development Dependencies

  • PHPUnit: Unit testing framework (future implementation)

No External Libraries

The library is designed to work without external dependencies to ensure:

  • Maximum compatibility
  • Minimal installation footprint
  • Reduced security surface
  • Framework independence