{"id":31932843,"url":"https://github.com/surtarso/single-file-php-file-browser","last_synced_at":"2025-10-14T05:26:14.481Z","repository":{"id":192803059,"uuid":"687444470","full_name":"surtarso/single-file-php-file-browser","owner":"surtarso","description":"Beautify the default HTML directory listing with a single file.","archived":false,"fork":false,"pushed_at":"2025-09-23T02:04:07.000Z","size":853,"stargazers_count":9,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-23T04:07:38.374Z","etag":null,"topics":["html","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/surtarso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-09-05T11:25:16.000Z","updated_at":"2025-09-23T02:04:10.000Z","dependencies_parsed_at":"2025-03-16T03:19:39.826Z","dependency_job_id":"b15a47aa-f671-49e2-96cc-4f477cf17646","html_url":"https://github.com/surtarso/single-file-php-file-browser","commit_stats":null,"previous_names":["surtarso/single-file-php-dir-list","surtarso/single-file-php-file-browser"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/surtarso/single-file-php-file-browser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surtarso%2Fsingle-file-php-file-browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surtarso%2Fsingle-file-php-file-browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surtarso%2Fsingle-file-php-file-browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surtarso%2Fsingle-file-php-file-browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/surtarso","download_url":"https://codeload.github.com/surtarso/single-file-php-file-browser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surtarso%2Fsingle-file-php-file-browser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279018012,"owners_count":26086236,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["html","php"],"created_at":"2025-10-14T05:26:13.406Z","updated_at":"2025-10-14T05:26:14.472Z","avatar_url":"https://github.com/surtarso.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Single File PHP File Browser\n\n[Experience a live instance with some mock files](https://tarsogalvao.ddns.net/stuff/)\n\n## Table of Contents\n1. [Introduction](#introduction)\n2. [Functionality](#functionality)\n3. [Screenshot](#screenshot)\n4. [Usage](#usage)\n5. [Technologies Used](#technologies-used)\n6. [Best Practices](#best-practices)\n7. [Code Explanation](#code-explanation)\n8. [Roadmap](#roadmap)\n\n## Introduction\n\nThe **Single File PHP File Browser** is a lightweight and straightforward project that provides a web-based directory listing for the files contained within a specified directory. This project serves as a quick and easy way to share files or documents with others via a web interface. This code provides a flexible way to display and customize directory listings, making it useful for creating file browsers and similar applications.\n\n[Back to top](#table-of-contents)\n\n## Functionality\n\nThis project offers the following functionalities:\n\n- Lists files and folders contained within a specified directory.\n- Allows users to navigate through the directory tree structure.\n- Download or Upload single or multiple files at once.\n- Excludes specific file extensions and hidden files from the listing.\n- Displays free space on current directory.\n- Automatic link to other instances of this script.*\n\n[Back to top](#table-of-contents)\n\n## Screenshot\n\n| Normal view | Uploads enabled |\n| ---------------------------------- | ---------------------------------- |\n| ![image](https://github.com/user-attachments/assets/4ac672f9-d835-4dbf-8de9-350cc8586873) | ![image](https://github.com/user-attachments/assets/e6d580d4-44f0-473a-a1ec-7eb2722c7cb8) |\n\n\n\u003cp align=\"center\"\u003e(*Folders with the 'external link' icon will navigate to their own index.php file instance.)\u003c/p\u003e\n\n[Back to top](#table-of-contents)\n\n## Usage\n\u003e[!IMPORTANT]\n\u003eMake sure you have PHP enabled on your webserver.\n\nTo use the Single File PHP File Browser, follow these simple steps:\n\n1. Download the `index.php` file from this project.\n\n2. Place the `index.php` file in the folder you want to share on the web.\n\n3. Access the folder using a web browser. You can do this by entering the folder's URL in your web browser's address bar. For example, if you placed `index.php` in a folder called \"stuff\" on your web server, you would access it like this: `http://yourdomain.com/stuff/`.\n\nThe `index.php` file will automatically generate a directory listing for the specified folder, allowing you to view and access the contained files and folders via a user-friendly web interface.\n## Uploads (Optional)\n\u003e[!IMPORTANT]\n\u003eThe upload functionality requires you to add users to the system.\n\nHere's how to set it up:\n\n**Enabling Uploads**\n\n1. **Create Users:** The provided script `create-user` will generate a file named `.users` that **must be in the same directory as `index.php` for the upload section to show up.** The `.users` file stores user credentials securely.\n\n   ```bash\n   $ create-user your_username your_password\n   ```\n\n   This command creates the `.users` file with your credentials, enabling uploads. You can repeat this command to add more users.\n\n2. **Delete Users:** To delete an existing user, run the `create-user` script with the `--delete` flag after the username:\n\n   ```bash\n   $ create-user your_username --delete\n   ```\n\n   This will remove the user's credentials from the `.users` file. When the last user is deleted, the `.users` file will be automatically removed, and **the upload section will be hidden.**\n\n3. **Upload types:** By default only compressed files are authorized to be uploaded. You can change what types you want by commenting/uncommenting or adding more types to the $allowedUploadTypes global variable at the top of the index.php file:\n\n   ```php\n   $allowedUploadTypes = array_merge(\n        // array('jpg', 'jpeg', 'png', 'gif', 'webp', 'bmp', 'tiff'),               // images\n        // array('mp4', 'mov', 'avi', 'mkv', 'webm', 'flv', 'wmv'),                 // videos\n        // array('mp3', 'wav', 'flac', 'ogg', 'aac', 'm4a'),                        // audio\n        // array('pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'txt', 'rtf'), // documents\n        array('zip', 'rar', 'tar', 'gz', '7z', '7za'),                           // compressed\n        // array('sh'),                                                             // script\n        // add more/edit as needed\n    );\n   ```\n\n**Security Considerations**\n\u003e[!WARNING]\n\u003eFor basic protection, rename the `create-user` script to `.create-user` so it's hidden on the file list (**note: this doesn't hide it completely**). It's better to move it to a location outside the web-accessible directory.\n\n\n[Back to top](#table-of-contents)\n\n## Technologies Used\n\n- **PHP**: PHP is used to generate the directory listing and handle file system operations.\n- **HTML/CSS**: HTML and CSS are used for the presentation and styling of the directory listing.\n- **JavaScript:** to implement client-side features.\n- **Bash Script:** to provide user management.\n- **Font Awesome**: Font Awesome icons are used to enhance the visual representation of files and folders.\n\n[Back to top](#table-of-contents)\n\n## Best Practices\n\nTo maintain simplicity and effectiveness, this project follows some best practices:\n\n- **Minimalism**: The code is kept minimal and straightforward to ensure ease of understanding and maintenance.\n- **Security**: Security measures are taken by excluding certain file extensions to prevent exposing sensitive files (e.g., PHP files).\n- **User Experience**: The interface is designed for user-friendliness, with clear differentiations between files and folders.\n\n[Back to top](#table-of-contents)\n\n## Code Explanation\n\nThis PHP code snippet is designed to generate a directory listing for a specified directory, presenting its contents in a structured HTML format. The code can be used to showcase files and subdirectories while allowing for customization of icons based on file extensions. Below is a breakdown of how the code works:\n\n### Function `listDirectory`\n\n```php\nfunction listDirectory($directory) {\n    // ...\n}\n```\n\n- `listDirectory` is a recursive function that takes the path to a directory as its parameter.\n\n### Scanning Directory Contents\n\n```php\n$files = scandir($directory);\n```\n\n- `scandir` is used to retrieve an array of files and directories within the specified `$directory`.\n\n### Excluded File Extensions\n\n```php\n$notAllowedExtensions = array('html', 'php', 'swp', 'css');\n```\n\n- An array, `$notAllowedExtensions`, is defined to store file extensions that should be excluded from the listing. These extensions won't be displayed in the directory listing.\n\n### File Extension to Icon Mapping\n\n```php\n$iconMapping = array(\n    'pdf' =\u003e 'fa-regular fa-file-pdf',       // PDF document\n    'doc' =\u003e 'fa-regular fa-file-word',      // Microsoft Word document\n    'docx' =\u003e 'fa-regular fa-file-word',     // Microsoft Word document\n    'txt' =\u003e 'fa-solid fa-file-lines',       // Text document\n    'md' =\u003e 'fa-solid fa-file-code',         // Markdown document\n    'ppt' =\u003e 'fa-regular fa-file-powerpoint',// PowerPoint presentation\n    // ...\n);\n```\n\n- `$iconMapping` is an associative array that maps file extensions to corresponding CSS icon classes. These classes determine the icons displayed next to file names in the directory listing.\n\n### Generating the Directory Listing\n\n```php\necho '\u003cul class=\"folder-contents\"\u003e';\nforeach ($files as $file) {\n    // ...\n}\necho '\u003c/ul\u003e';\n```\n\n- An unordered list (`\u003cul\u003e`) with the class \"folder-contents\" is initiated to structure the directory listing.\n- A `foreach` loop iterates through the files and directories obtained from `$files`.\n\n### Handling Subdirectories Recursively\n\n```php\nif (is_dir($path)) {\n    // ...\n}\n```\n\n- If the current item in the loop is a directory, it is displayed as a folder in the listing. The function `listDirectory` is then called recursively to list the contents of the subdirectory.\n\n### Customizing Icons and File Links\n\n```php\n$iconClass = isset($iconMapping[$extension]) ? $iconMapping[$extension] : 'icon-default';\necho '\u003cli\u003e\u003ci class=\"' . $iconClass . '\"\u003e\u003c/i\u003e\u003ca href=\"' . $file . '\"\u003e' . $file . '\u003c/a\u003e\u003c/li\u003e';\n```\n\n- Icons are customized based on file extensions using the `$iconMapping` array. If an extension is not found in the mapping, it defaults to 'icon-default'.\n- Hyperlinks are generated for each file or directory entry.\n\n### Specifying the Directory\n\n```php\n$directory = './'; // Specify the directory you want to list\n```\n\n- The `$directory` variable is set to the path of the directory you want to list.\n\n### Invoking the Function\n\n```php\nlistDirectory($directory);\n```\n\n- Finally, the `listDirectory` function is called with the specified directory to generate the directory listing.\n\n[Back to top](#table-of-contents)\n\n## Roadmap\n\nHere are some planned enhancements for the Single File PHP File Browser:\n\n- ~~**Bulk Downloads:** Add the ability to select and download multiple files at once.~~ [Done]\n- ~~**Bulk Uploads:** Add the ability to select and upload multiple files at once.~~ [Done]\n- ~~**Password:** Secure uploads with user/password.~~ [Done]\n- ~~**Security:** Use hash to save/retrieve passwords from .users file.~~ [Done]\n- ~~**Frontend:** Better mapping of icons and colors to default expected ones.~~ [Done]\n- ~~**Free Space:** Display free space on current directory so uploaders can be informed.~~ [Done]\n- **Upload Progress:** Display upload progress for user feedback.\n- **Mouse-over File Preview:** Implement mouse-over file preview to display a small preview when hovering over file links.\n- **Pagination:** Implement pagination for directories with a large number of files and folders.\n- **Lazy Loading:** Improve performance by implementing lazy loading for large directories.\n\n## Contribute\n\nFeel free to contribute to the project and help make these enhancements a reality.\n\n[Back to top](#table-of-contents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurtarso%2Fsingle-file-php-file-browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsurtarso%2Fsingle-file-php-file-browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurtarso%2Fsingle-file-php-file-browser/lists"}