arraypress/wp-media-utils

A lean WordPress library for working with attachments and media files.

dev-main 2025-09-06 16:48 UTC

Requires

• php: >=7.4

GPL-2.0-or-later

• David Sherlock

• metadata
• media
• wordpress
• files
• wp
• attachments
• arraypress

README

A lean WordPress library for working with attachments and media files.

Installation

composer require arraypress/wp-media-utils

Usage

Single Attachment Operations

use ArrayPress\MediaUtils\Attachment;

// Get attachment info
$attachment = Attachment::get( 123 );
$exists     = Attachment::exists( 123 );

// File information
$type      = Attachment::get_type( 123 );        // 'image', 'video', 'audio', 'document', 'file'
$mime      = Attachment::get_mime_type( 123 );   // 'image/jpeg'
$extension = Attachment::get_extension( 123 );   // 'jpg'
$size      = Attachment::get_file_size( 123 );   // '2.5 MB'
$filename  = Attachment::get_filename( 123 );    // 'photo.jpg'
$url       = Attachment::get_url( 123 );

// Attachment fields
$title       = Attachment::get_title( 123 );
$caption     = Attachment::get_caption( 123 );
$description = Attachment::get_description( 123 );
$alt         = Attachment::get_alt_text( 123 );
Attachment::set_alt_text( 123, 'New alt text' );

// Image specific
$is_image   = Attachment::is_image( 123 );
$dimensions = Attachment::get_dimensions( 123 ); // ['width' => 1920, 'height' => 1080]
$image_html = Attachment::get_image( 123, 'thumbnail' );
$image_url  = Attachment::get_image_url( 123, 'large' );

// Media content
$duration  = Attachment::get_duration( 123 );           // 180 (seconds)
$formatted = Attachment::get_duration_formatted( 123 ); // '3:00'

// Delete
Attachment::delete( 123, true ); // force delete

Multiple Attachment Operations

use ArrayPress\MediaUtils\Attachments;

// Get multiple attachments
$attachments    = Attachments::get( [ 123, 456, 789 ] );
$by_parent      = Attachments::get_by_parent( 100 );
$images         = Attachments::get_by_type( 'image' );
$search_results = Attachments::search( 'photo' );

// Form options
$options = Attachments::get_options(); // [123 => 'Title', 456 => 'Another']

// Bulk operations
$results = Attachments::update_meta( [ 123, 456 ], 'custom_field', 'value' );
$results = Attachments::delete_meta( [ 123, 456 ], 'old_field' );
$results = Attachments::delete( [ 123, 456 ] );

// Utilities
$existing  = Attachments::exists( [ 123, 456, 999 ] );    // [123, 456]
$sanitized = Attachments::sanitize( '123,456,invalid' );  // [123, 456]

Media Output

use ArrayPress\MediaUtils\Media;

// Universal media output (auto-detects type)
echo Media::output( 123 );

// Specific media types
echo Media::image( 123, [ 'size' => 'large' ] );
echo Media::video( 123, [ 'width' => 800, 'height' => 450 ] );
echo Media::audio( 123, [ 'controls' => true ] );
echo Media::file( 123, [ 'show_size' => true ] );

// WordPress shortcode embeds
echo Media::embed( 123 ); // [video] or [audio] shortcodes

// Media galleries
echo Media::gallery( [ 123, 456, 789 ], [ 'columns' => 3 ] );

Thumbnail Display

use ArrayPress\MediaUtils\Thumbnail;

// Entity thumbnails
echo Thumbnail::post( 123 );                                    // Post featured image
echo Thumbnail::user( 456, 'profile_image' );                   // User meta thumbnail
echo Thumbnail::term( 789, 'featured_image' );                  // Term meta thumbnail
echo Thumbnail::attachment( 123, 'thumbnail' );                 // Direct attachment
echo Thumbnail::avatar( 456, 48 );                              // User avatar/Gravatar

// With custom attributes
echo Thumbnail::post( 123, 'medium', [ 'class' => 'featured' ], true );

Examples

Admin Column Thumbnails

// In admin list tables
echo Thumbnail::post( $post->ID );
echo Thumbnail::user( $user->ID, 'avatar_attachment_id' );
echo Thumbnail::attachment( $attachment_id );

Frontend Media Display

// Blog post content
echo Media::output( $featured_video_id );
echo Media::gallery( $gallery_attachment_ids, [ 'columns' => 4 ] );

// Portfolio items
if ( Attachment::get_type( $attachment_id ) === 'video' ) {
    echo Media::video( $attachment_id, [ 'controls' => true ] );
} else {
    echo Media::image( $attachment_id, [ 'size' => 'large' ] );
}

Custom Video Player

echo Media::video( $video_id, [
    'width'    => 1280,
    'height'   => 720,
    'controls' => true,
    'preload'  => 'metadata'
]);

File Downloads with Metadata

echo Media::file( $document_id, [
    'show_size' => true,
    'show_icon' => true,
    'text'      => 'Download Report'
]);

Requirements

• PHP 7.4+
• WordPress 5.0+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-2.0-or-later License.

Support

• Documentation
• Issue Tracker