{"id":31241612,"url":"https://github.com/arraypress/wp-file-utils","last_synced_at":"2026-01-20T16:26:01.331Z","repository":{"id":312975602,"uuid":"1015014897","full_name":"arraypress/wp-file-utils","owner":"arraypress","description":"A comprehensive WordPress library for file operations, path manipulation, MIME type handling, and secure filesystem operations.","archived":false,"fork":false,"pushed_at":"2025-11-27T19:54:26.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-30T11:23:15.135Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/arraypress.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":"2025-07-06T21:07:57.000Z","updated_at":"2025-11-27T19:54:29.000Z","dependencies_parsed_at":"2025-09-03T07:14:12.713Z","dependency_job_id":"54a79129-38e4-4e1b-9b36-7dd1cbc70703","html_url":"https://github.com/arraypress/wp-file-utils","commit_stats":null,"previous_names":["arraypress/wp-file-utils"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arraypress/wp-file-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-file-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-file-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-file-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-file-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arraypress","download_url":"https://codeload.github.com/arraypress/wp-file-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-file-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2025-09-23T00:11:09.332Z","updated_at":"2026-01-20T16:26:01.326Z","avatar_url":"https://github.com/arraypress.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WP File Utils\n\nA lightweight WordPress library providing essential file operation utilities, MIME type detection, and security validation for file handling.\n\n## Installation\n\nInstall via Composer:\n\n```bash\ncomposer require arraypress/wp-file-utils\n```\n\n## Requirements\n\n- PHP 7.4 or later\n- WordPress 5.0 or later\n\n## Features\n\n- 🔄 **URL/Path Conversion** - Convert between file URLs and local paths\n- 📁 **File Operations** - Path manipulation, filename extraction, extension handling\n- 🔒 **Security Validation** - Safe filename checking, path sanitization\n- 🎯 **MIME Detection** - Comprehensive MIME type detection and categorization\n- 🚀 **Optimized Streaming** - Smart chunk size detection for file delivery\n- 📦 **Zero Dependencies** - Lightweight with no external dependencies\n\n## Core Classes\n\n### File Class\n\nEssential file operations and path/URL conversions.\n\n```php\nuse ArrayPress\\Utils\\File;\n\n// Convert between URLs and paths\n$path = File::url_to_path( 'https://site.com/wp-content/uploads/file.pdf' );\n$url = File::path_to_url( '/var/www/wp-content/uploads/file.pdf' );\n\n// Check if file is local\nif ( File::is_local_file( $url ) ) {\n    $size = File::get_size( $path );\n}\n\n// Path and filename operations\n$extension = File::get_extension( 'document.pdf' );     // 'pdf'\n$filename = File::get_filename( '/path/to/file.pdf' );  // 'file'\n$basename = File::get_basename( '/path/to/file.pdf' );  // 'file.pdf'\n$directory = File::get_directory( '/path/to/file.pdf' ); // '/path/to'\n\n// Change extension\n$new_path = File::change_extension( 'image.jpg', 'png' ); // 'image.png'\n\n// Sanitize filename\n$safe = File::sanitize_filename( 'My File!!!.pdf', true ); // 'my-file.pdf'\n\n// Join paths safely\n$full_path = File::join_path( $upload_dir, '2024', 'documents', 'file.pdf' );\n```\n\n### Security Class\n\nFile security validation and path sanitization.\n\n```php\nuse ArrayPress\\Utils\\Security;\n\n// Check if filename is safe\nif ( Security::is_safe_filename( $filename ) ) {\n    // No path traversal, null bytes, or dangerous extensions\n}\n\n// Check allowed file types\n$allowed = ['pdf', 'doc', 'docx'];\nif ( Security::is_allowed_file_type( 'document.pdf', $allowed ) ) {\n    // File type is permitted\n}\n\n// Sanitize file paths\n$safe_path = Security::sanitize_path( $user_input );\n// Removes dangerous protocols like phar://, php://, etc.\n// Removes path traversal attempts (..)\n```\n\n### MIME Class\n\nComprehensive MIME type detection and categorization.\n\n```php\nuse ArrayPress\\Utils\\MIME;\n\n// Get MIME type from filename\n$mime = MIME::get_type( 'document.pdf' ); // 'application/pdf'\n\n// Get extension from MIME type\n$ext = MIME::get_extension_from_type( 'application/pdf' ); // 'pdf'\n\n// Determine delivery behavior\nif ( MIME::should_force_download( $mime ) ) {\n    // Force download (true for ZIP, DOC, etc.)\n} else {\n    // Display inline (false for PDF, images, video)\n}\n\n// Get optimal chunk size for streaming\n$chunk_size = MIME::get_optimal_chunk_size( 'video/mp4' ); // 2097152 (2MB)\n\n// Type checking\nMIME::is_media( $mime );      // Audio or video\nMIME::is_image( $mime );      // Image files\nMIME::is_document( $mime );   // Office docs, PDFs, text\nMIME::is_archive( $mime );    // ZIP, RAR, etc.\n\n// Check if suitable for selling as digital product\nif ( MIME::is_downloadable_product( $mime ) ) {\n    // Suitable for e-commerce\n}\n```\n\n## Supported MIME Types\n\nThe library includes comprehensive mappings for 70+ file types including:\n\n- **Documents**: PDF, Word, Excel, PowerPoint, OpenDocument\n- **Media**: MP3, MP4, WebM, AVI, MOV, OGG, WAV\n- **Images**: JPEG, PNG, GIF, WebP, SVG, BMP, TIFF\n- **Archives**: ZIP, RAR, 7Z, TAR, GZ, BZ2\n- **E-books**: EPUB, MOBI, AZW\n- **Text**: TXT, CSV, JSON, XML, HTML, CSS, JS\n- **Fonts**: TTF, OTF, WOFF, WOFF2\n- And many more...\n\n## Optimal Chunk Sizes\n\nThe library automatically determines optimal chunk sizes for streaming:\n\n- **Video files**: 2MB chunks for smooth streaming\n- **Archives**: 4MB chunks for faster downloads\n- **Audio files**: 1MB chunks\n- **Images**: 512KB chunks (2MB for large formats like PSD)\n- **Documents**: 1MB chunks\n- **Default**: 1MB chunks\n\n## Integration Examples\n\n### With Protected Folders\n\n```php\nuse ArrayPress\\Utils\\MIME;\n\nclass Delivery {\n    private function detect_mime_type( string $file_path ): string {\n        return MIME::get_type( $file_path );\n    }\n    \n    private function should_force_download( string $mime_type ): bool {\n        return MIME::should_force_download( $mime_type );\n    }\n}\n```\n\n### With E-Commerce (SugarCart)\n\n```php\nuse ArrayPress\\Utils\\File;\nuse ArrayPress\\Utils\\MIME;\n\n// Convert URL to local path for file operations\n$local_path = File::url_to_path( $download_url );\n\nif ( $local_path \u0026\u0026 File::is_readable( $local_path ) ) {\n    $file_size = File::get_size( $local_path );\n    $mime_type = MIME::get_type( $local_path );\n    \n    // Store file metadata\n    $file_data = [\n        'path' =\u003e $local_path,\n        'size' =\u003e $file_size,\n        'type' =\u003e $mime_type,\n        'name' =\u003e File::get_basename( $local_path )\n    ];\n}\n```\n\n### File Upload Validation\n\n```php\nuse ArrayPress\\Utils\\Security;\nuse ArrayPress\\Utils\\MIME;\n\nfunction validate_upload( $filename, $tmp_path ) {\n    // Security checks\n    if ( ! Security::is_safe_filename( $filename ) ) {\n        return new WP_Error( 'unsafe_filename', 'Filename contains unsafe characters' );\n    }\n    \n    // Check allowed types\n    $allowed = ['pdf', 'doc', 'docx', 'jpg', 'png'];\n    if ( ! Security::is_allowed_file_type( $filename, $allowed ) ) {\n        return new WP_Error( 'invalid_type', 'File type not allowed' );\n    }\n    \n    // Verify MIME type matches extension\n    $mime = MIME::get_type( $filename );\n    if ( MIME::is_downloadable_product( $mime ) ) {\n        // Process as digital product\n    }\n    \n    return true;\n}\n```\n\n## Why Use This Library?\n\n### What WordPress Doesn't Provide\n\nWhile WordPress has many file functions, it lacks:\n- **URL to path conversion** - No built-in way to convert URLs to local file paths\n- **Path to URL conversion** - No reverse conversion function\n- **Smart delivery detection** - No logic for inline vs download behavior\n- **Optimized chunk sizes** - No MIME-based chunk optimization\n- **Comprehensive MIME mappings** - Limited file type coverage\n\n### Benefits Over DIY Solutions\n\n- **Battle-tested** - Used in production e-commerce and file delivery systems\n- **Performance optimized** - Smart defaults based on file types\n- **Security focused** - Protects against path traversal and dangerous files\n- **WordPress integrated** - Falls back to WordPress functions when appropriate\n- **Minimal footprint** - Just ~500 lines of focused utility code\n- **Well documented** - Comprehensive PHPDoc blocks\n\n## License\n\nGPL-2.0-or-later\n\n## Credits\n\nCreated and maintained by [David Sherlock](https://davidsherlock.com) at [ArrayPress](https://arraypress.com).\n\n## Support\n\nFor bugs and feature requests, please visit the [GitHub repository](https://github.com/arraypress/wp-file-utils).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fwp-file-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farraypress%2Fwp-file-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fwp-file-utils/lists"}