DirList - Secure PHP File Browser

DirList is a simple and secure PHP application that allows you to manage files and folders on your web server in a clean, password-protected environment. The application is lightweight, requires no database, and offers essential features like uploading, deleting, and moving files.

---

Table of Contents

1. Features
2. Installation
3. Usage
4. Markdown Files (heading.md & disclaimer.md)
5. Security Notes
6. Switching from CDN to Local Assets (Data Protection)

---

1. Features

• Responsive Design: An attractive and intuitive user interface powered by Bootstrap 5.
• Customizable Layout: Supports Dark Mode and Light Mode.
• No Database: All user data is securely stored in the users.json file.
• File and Folder Management:
  • List files and folders.
  • Create new folders.
  • File uploads with robust extension and MIME type validation.
  • Delete and move files and folders (for logged-in users only).
• User Management (Admin):
  • Create and delete users.
  • Change user passwords.
• Password Protection: Secure password hashing ensures passwords are never stored in plaintext.
• Security Features:
  • Protection against directory traversal attacks.
  • CSRF protection for all forms.
  • Hiding critical system files from the directory listing.
• Dynamic Content: Supports displaying Markdown files for custom content within folders.

---

2. Installation

Installing DirList is very straightforward:

1. Upload all files to the folder on your web server that you want to manage.
2. Ensure that the web server has write permissions for the folder so it can create new files and the users.json file.
3. Open the URL in your browser. On the first run, the script will automatically create a default admin user with the password your_secure_password.
4. IMPORTANT: Log in immediately with this user and change the default password.

---

3. Usage

• Login Area: Open the login modal to log in as an administrator.
• Admin Functions: After logging in, forms for uploading files, creating new folders, and managing users will appear at the top.
• File Browser: The directory list shows all files and folders in the current path. For logged-in users, additional buttons for deleting and moving items are available.
• Breadcrumb Navigation: The path bar at the top helps you navigate through the folders.

---

4. Markdown Files

DirList allows you to customize each subdirectory with two special Markdown files:

• heading.md: If this file exists in the current folder, its content will be displayed at the very top of the directory view for non-logged-in users. It's ideal for a heading, a welcome message, or a brief description of the folder's contents.
• disclaimer.md: If this file exists, its content will be displayed at the end of the directory listing for non-logged-in users. This is perfect for disclaimers, contact information, or additional notes.

Note: These Markdown files are only visible to public visitors. For logged-in users (administrators), they are hidden to keep the management area clear and uncluttered.

---

5. Security Notes

• Default Password: Be sure to change the initial admin password in users.json or via the user interface.
• File Permissions: Ensure the folder containing index.php and users.json has secure write permissions (e.g., 0755) to prevent unauthorized access.
• Hidden Files: Add any other critical files to the $hiddenFiles list that should not be publicly visible.
• .htaccess Protection: The included .htaccess file is a critical security measure for Apache web servers. It prevents direct access to sensitive system files like users.json and Parsedown.php. If you are using a web server that does not support .htaccess (such as Nginx), it is crucial to manually configure your server to deny direct access to these files.

# Protects sensitive files from public access
<FilesMatch "^(users\.json|Parsedown\.php|index\.php|disclaimer\.md|heading\.md|\.htaccess)$">
    Require all denied
</FilesMatch>

# Allows only the main script to be accessed
<Files "index.php">
    Require all granted
</Files>

# Redirects all requests to the index.php script
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php?path=$1 [QSA,L]
</IfModule>

---

6. Switching from CDN to Local Assets (Data Protection)

By default, DirList uses Content Delivery Networks (CDNs) for Bootstrap and Font Awesome to ensure fast loading times. However, this means that your users' browsers connect to third-party servers to download these assets. For data protection reasons and to comply with GDPR, it is highly recommended to host these assets locally.

1. Download the Files: Download the latest versions of Bootstrap (CSS and JS) from the official Bootstrap website and Font Awesome (CSS and web fonts) from their official download page.
2. Create an assets folder: Create a new directory named assets in your root folder.
3. Place Files:
   • Place the Bootstrap CSS and JS files in a subfolder, e.g., assets/bootstrap/.
   • Place the Font Awesome CSS and web fonts in a subfolder, e.g., assets/fontawesome/.
4. Update index.php: Open index.php and replace the CDN links in the <head> section with the local paths.

Example of changes in index.php:

Old (CDN):

<link rel="stylesheet" href="[https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css](https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css)">
<link rel="stylesheet" href="[https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css](https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css)">
<script src="[https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js](https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js)"></script>

New (local)

<link rel="stylesheet" href="assets/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="assets/fontawesome/css/all.min.css">
<script src="assets/bootstrap/js/bootstrap.bundle.min.js"></script>