LocalhostIndex

A beautiful, self-contained localhost homepage for local development environments. Display all your projects, server info, and quick links in one elegant interface.

Features

• 📂 Directory Browser - Automatically scans and displays all projects/folders
• 🎨 10 Beautiful Themes - Switch between bluey, sunny, forest, retro, matrix, nebula, sundown, mono, dark, and light
• 🔍 Instant Search - Filter projects with live search and Enter-to-navigate
• 🔀 Instant Sorting - Client-side sort by name, date, or size with no page reload
• 🔄 Reverse Sort - Click any sort button twice to reverse order (A-Z ↔ Z-A)
• 📁 Folder Sizes - Actual folder sizes calculated recursively
• 💾 File Sizes - Display file sizes in human-readable format
• ⚡ Smart Caching - 60-second cache for improved performance
• 🔧 Multi-Runtime Detection - Auto-detects Python, Node.js, Ruby, Go, Docker and more (macOS/Linux)
• 📊 Server Dashboard - Shows Apache, PHP, MySQL, and all detected development tools
• 📈 System Statistics - Total disk, Memory, CPU cores, Uptime, OS version (macOS/Linux)
• 🎛️ Quick Actions - Restart Apache/MySQL, Clear Cache, View Logs with one click
• 📁 Collapsible Sections - All sections expand/collapse with +/- toggle buttons
• 🔎 Preview Mode - See key info at a glance, expand for full details
• ⏱️ Recent Activity - Displays 2 recent items (folded) or 10 items (expanded)
• 🔗 Quick Links - Configurable shortcuts to phpMyAdmin, phpinfo, or custom tools
• 🌐 Open Ports Detection - Scan and display running localhost services (Node, Python, etc.)
• 📱 Responsive Design - Works beautifully on desktop and mobile
• ♿ Accessible - Keyboard navigation and ARIA labels
• 🔐 Security Hardened - CSRF protection, rate limiting, security headers, path validation
• 🏥 Health Check - Built-in ?health endpoint for monitoring
• 💾 Theme Persistence - Remembers your theme preference via localStorage

Installation

Quick Start

1. Download index.php
2. Drop it into your localhost root directory (e.g., /htdocs, /www, or /Sites)
3. Navigate to http://localhost/ in your browser

That's it! No dependencies, no build process, no configuration required.

Deploy Script

If you cloned the repository, use the deploy script to copy files to your Sites folder:

./deploy.sh                    # Deploy index.php only
./deploy.sh --full             # Deploy index.php + favicon.png
./deploy.sh --backup           # Backup previous as index_old_1.php, then deploy
./deploy.sh --full --backup    # Both options
./deploy.sh --help             # Show help

Requirements

• PHP 7.4 or higher
• Apache web server (for Apache version detection)
• Optional: MySQL/MariaDB (for database version detection)

Platform Compatibility

Feature	macOS	Linux	Windows
Core (directory listing, themes, search)	✅	✅	✅
File/folder sizes	✅	✅	✅
Authentication & security	✅	✅	✅
Caching	✅	✅	✅
Runtime detection (Python, Node, etc.)	✅	✅	❌
System stats (Memory, CPU, Uptime)	✅	✅	❌
MySQL version detection	✅	✅	⚠️
Apache version detection	✅	✅	✅

Note: On Windows, runtime detection and system statistics require Unix shell commands that are not available. Core functionality works fully. MySQL detection works if you configure direct connection credentials.

Configuration

Edit the $options array at the top of index.php:

$options = [
    // Choose a theme: bluey, sunny, forest, retro, matrix, nebula, sundown, monochrome, dark, light
    'theme' => 'bluey',

    // Exclude files or folders using wildcard patterns
    'exclude' => [ '.DS_Store', '.localized', '*.php*', '*.png' ],

    // Add extra tool links
    'extras' => [
        'phpinfo()' => '?phpinfo=1',
        'PhpMyAdmin()' => 'phpMyAdmin'
    ],

    // Set favicon file(s) to look for
    'favicon' => [ 'favicon.ico', 'favicon.png', 'favicon.svg' ],

    // MySQL detection options
    'mysql' => [
        // Explicit binary paths (optional)
        'bin' => ['/usr/local/bin/mysql'],

        // Direct connection (optional)
        'connection' => [
            'host' => '127.0.0.1',
            'user' => 'root',
            'password' => '',
            'port' => 3306,
        ]
    ],

    // Display settings (v1.2.0+)
    'display' => [
        'show_file_sizes' => true,      // Show file sizes
        'default_sort' => 'name',       // Default sort: name, date, size
        'enable_cache' => true,         // Enable 60s cache
    ],

    // Security settings (v1.1.0+)
    'security' => [
        'enable_authentication' => false,
        'password' => '',               // Bcrypt hash
        'disable_phpinfo' => false,
        'enable_csrf' => true,
        'strict_path_validation' => true,
    ]
];

Themes

10 carefully crafted color schemes:

Theme	Description
bluey	Deep blue with lime accents (default)
light	Clean light mode
sunny	Warm orange and yellow
forest	Teal and forest green
retro	Classic terminal green
matrix	Cyberpunk neon green
nebula	Purple and pink space vibes
sundown	Sunset coral tones
monochrome	Black and white with gold
dark	Pure dark mode

Click the theme dots in the top-right to switch instantly. Your preference is saved automatically.

Usage Tips

Search & Navigation

• Type to filter projects instantly
• Press Enter to open the first matching result
• Click any project/file to open in new tab

Keyboard Shortcuts

• Arrow Left/Right - Navigate between theme buttons
• Tab - Move through interface elements
• Enter - Quick-open first search result

MySQL Detection

The script attempts to detect MySQL version using multiple strategies:

1. Shell commands (mysql --version, mysqld --version)
2. Common binary paths
3. Environment variables (DB_USER, MYSQL_HOST, etc.)
4. Database URL parsing (DATABASE_URL)
5. Direct mysqli connection (if credentials provided)
6. Falls back to mysqli client info

Customization

Exclude Files

Add patterns to hide files/folders from the list:

'exclude' => [ '.git*', 'node_modules', '*.log', '.env' ]

Add Custom Links

Add shortcuts to frequently used tools:

'extras' => [
    'Adminer' => 'adminer.php',
    'MailHog' => 'http://localhost:8025',
    'Logs' => 'logs/',
]

Change Default Theme

Set your preferred default theme:

'theme' => 'matrix'  // or any other theme name

Security Features (v1.1.0+)

LocalhostIndex now includes built-in security options for shared or public environments.

Security Configuration

Configure security settings in the $options['security'] array:

'security' => [
    // Enable password authentication
    'enable_authentication' => false,

    // Set password hash (generate with: password_hash('your_password', PASSWORD_DEFAULT))
    'password' => '',

    // Disable phpinfo() for security
    'disable_phpinfo' => false,

    // Enable CSRF token protection (recommended)
    'enable_csrf' => true,

    // Strict path validation against traversal attacks
    'strict_path_validation' => true,
]

Enabling Authentication

To enable password protection:

1. Generate a password hash:

   echo password_hash('your_secure_password', PASSWORD_DEFAULT);

2. Update your configuration:

   'security' => [
       'enable_authentication' => true,
       'password' => '$2y$10$...',  // paste your hash here
   ]

Security Features

✅ CSRF Protection - Protects phpinfo() and sensitive endpoints (POST-based) ✅ Path Traversal Prevention - Validates all file paths with symlink protection ✅ Password Authentication - Optional login system with rate limiting ✅ Session Management - Secure session handling with regeneration ✅ Security Headers - X-Content-Type-Options, X-Frame-Options, X-XSS-Protection ✅ Input Sanitization - All user input is escaped ✅ Graceful Degradation - Works even when shell_exec is disabled

For Local Use Only (Default Configuration)

By default (all security features disabled):

• No authentication required
• phpinfo() accessible via ?phpinfo=1&token=<csrf_token>
• Shows directory structure
• Displays server configuration

Recommended for: Local development (localhost, 127.0.0.1)

For Shared/Public Servers

Enable these settings:

'security' => [
    'enable_authentication' => true,
    'password' => '<your_hash>',
    'disable_phpinfo' => true,
    'enable_csrf' => true,
    'strict_path_validation' => true,
]

Additional recommendations:

• Use HTTPS
• Configure firewall rules
• Use .htaccess IP restrictions
• Regular security audits

Browser Compatibility

• ✅ Chrome/Edge 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Opera 76+

Troubleshooting

MySQL Version Shows "Unknown"

• Ensure MySQL/MariaDB is installed and running
• Add explicit binary path in $options['mysql']['bin']
• Provide connection credentials in $options['mysql']['connection']

Apache Version Not Detected

• Ensure Apache is running
• Check if apache_get_version() is available in your PHP build

Themes Not Persisting

• Check if localStorage is enabled in browser
• Try clearing browser cache
• Ensure you're not in private/incognito mode

API Endpoints

Health Check

Access ?health to get a JSON response for monitoring:

{
  "status": "ok",
  "timestamp": 1733400000,
  "php_version": "8.4.0",
  "server": "2.4.59"
}

phpinfo

Access phpinfo() via the UI link (requires CSRF token, submitted via POST for security).

Development

File Structure

LocalhostIndex/
├── index.php       # Single-file application (intentional)
├── deploy.sh       # Deployment script with --full and --backup options
├── README.md       # This file
├── features/       # Feature specifications
└── .gitignore      # Git ignore rules

Why Single File?

The entire application is intentionally in one index.php file for:

• Portability - Drop anywhere and it works
• Simplicity - No build process or dependencies
• Zero Config - Works out of the box
• Easy Updates - Replace one file to upgrade

Contributing

Contributions are welcome! Please ensure:

• Code remains in a single index.php file
• Follows existing code style
• Maintains backward compatibility
• Updates README.md with new features

License

MIT License - feel free to use, modify, and distribute.

Credits

Developed with ❤️ for the local development community.

---

Note: This is a development tool. Use responsibly and never deploy to production without proper security measures.