README

A lightweight WordPress library providing essential file path operations, MIME type detection, and security validation.

Installation

composer require arraypress/wp-file-utils

Requirements

PHP 7.4 or later
WordPress 5.0 or later

Core Classes

File Class

Path/URL conversions and path manipulation that WordPress doesn't provide natively.

use ArrayPress\FileUtils\File;

// Convert between URLs and paths (the real value of this library)
$path = File::url_to_path( 'https://site.com/wp-content/uploads/file.pdf' );
$url  = File::path_to_url( '/var/www/wp-content/uploads/file.pdf' );

// Resolve paths within the uploads directory
$path = File::upload_path( 'sugarcart/2024/01/file.zip' );
$url  = File::upload_url( 'sugarcart/2024/01/file.zip' );

// Check if file is local
if ( File::is_local_file( $url ) ) {
    // Safe to convert to local path
}

// Change extension
$new_path = File::change_extension( 'image.jpg', 'png' ); // 'image.png'

// Rename with preserved extension
$filename = File::rename_preserve_extension( 'My Report', 'original.pdf' ); // 'my-report.pdf'

// Join paths safely
$full_path = File::join_path( $upload_dir, '2024', 'documents', 'file.pdf' );

// Normalize cross-platform paths
$clean = File::normalize_path( 'path\\to//file.pdf' ); // 'path/to/file.pdf'

MIME Class

MIME type detection and categorization with 70+ file type mappings.

use ArrayPress\FileUtils\MIME;

// Get MIME type from filename
$mime = MIME::get_type( 'document.pdf' ); // 'application/pdf'

// Get extension from MIME type
$ext = MIME::get_extension_from_type( 'application/pdf' ); // 'pdf'

// Determine extension from HTTP response (useful for sideloading)
$ext = MIME::get_extension_from_response( $response, $body ); // 'webp'

// Determine delivery behavior
if ( MIME::should_force_download( $mime ) ) {
    // Force download (ZIP, DOC, executables, etc.)
} else {
    // Display inline (PDF, images, video, audio)
}

// Type checking
MIME::is_media( $mime );    // Audio or video
MIME::is_image( $mime );    // Image files
MIME::is_document( $mime ); // Office docs, PDFs, text
MIME::is_archive( $mime );  // ZIP, RAR, 7Z, etc.

// Get all registered types
$all = MIME::get_all_types(); // ['pdf' => 'application/pdf', ...]

Security Class

File security validation and path sanitization.

use ArrayPress\FileUtils\Security;

// Check if filename is safe (no traversal, null bytes, or dangerous extensions)
if ( Security::is_safe_filename( $filename ) ) {
    // Safe to use
}

// Check against an allowlist
$allowed = [ 'pdf', 'doc', 'docx', 'jpg', 'png' ];
if ( Security::is_allowed_file_type( 'document.pdf', $allowed ) ) {
    // File type is permitted
}

// Sanitize user-supplied paths (strips phar://, php://, traversal, etc.)
$safe_path = Security::sanitize_path( $user_input );

Supported MIME Types

The library includes mappings for 70+ file types:

Documents: PDF, Word, Excel, PowerPoint, OpenDocument
Media: MP3, MP4, WebM, AVI, MOV, OGG, WAV, FLAC
Images: JPEG, PNG, GIF, WebP, SVG, BMP, TIFF
Archives: ZIP, RAR, 7Z, TAR, GZ, BZ2
E-books: EPUB, MOBI, AZW
Text: TXT, CSV, JSON, XML, HTML, CSS, JS, RTF
Fonts: TTF, OTF, WOFF, WOFF2
Applications: EXE, DMG, APK, DEB, RPM

Why This Library?

WordPress lacks several essential file operations:

URL ↔ path conversion — no built-in way to convert between file URLs and local paths
Upload path resolution — no simple helper to resolve paths within the uploads directory
Smart delivery detection — no logic for determining inline vs download behavior
Comprehensive MIME mappings — limited file type coverage beyond basics
MIME from HTTP responses — no detection from response headers or binary inspection
Path security — no protection against protocol injection (phar://, php://, etc.)

Integration Examples

File Upload Validation

use ArrayPress\FileUtils\Security;
use ArrayPress\FileUtils\MIME;

function validate_upload( string $filename ): bool|WP_Error {
    if ( ! Security::is_safe_filename( $filename ) ) {
        return new WP_Error( 'unsafe', 'Filename contains unsafe characters.' );
    }

    $allowed = [ 'pdf', 'doc', 'docx', 'jpg', 'png' ];
    if ( ! Security::is_allowed_file_type( $filename, $allowed ) ) {
        return new WP_Error( 'invalid_type', 'File type not allowed.' );
    }

    return true;
}

Sideloading Remote Images

use ArrayPress\FileUtils\MIME;

$response = wp_remote_get( $image_url );
$body     = wp_remote_retrieve_body( $response );

// Detect extension even when URL has no file extension
$ext      = MIME::get_extension_from_response( $response, $body );
$filename = 'product-image.' . $ext;

Download Handling

use ArrayPress\FileUtils\File;
use ArrayPress\FileUtils\MIME;

$local_path = File::url_to_path( $download_url );

if ( $local_path && is_readable( $local_path ) ) {
    $mime = MIME::get_type( $local_path );

    if ( MIME::should_force_download( $mime ) ) {
        // Serve as download
    } else {
        // Display inline
    }
}

License

GPL-2.0-or-later

Credits

Created and maintained by David Sherlock at ArrayPress.

arraypress / wp-file-utils

Maintainers

Details