HelPHP

Media
in package

Tags
class

Media

The media class take care of all images and video format compatible with navigators in multiple aspects. To use it, you need the GD library at minimum (which is distributed with PHP in general) and if you want to do some process on videos, you'll need to install a recent ffmpeg or make run your HelPHP with our docker container for helPHP tagged with ffmpeg.

Note that a media can be instanciated, and called with its identifier from multiple place of your project. When you call the delete method on a media, it will be totaly deleted if no more referenced in the media_use table.

Note that there is also a media module, which is offerring an UI for this class to offer multiple features : the upload, some modifications on images, a media galery to permit exchange and cloning, but also the streaming of video images and files, some anti-download features on video and security.

so it's better to manage medias directly thru the media module, but the Media class is often used from any module to resize, format, manipulate medias. You can set all process to do as an automated process in a "process" array before calling media admin module to do the same process for every upload, but this system can be used from anywhere.

Send_file is the main streaming function, it support all kind of streaming operations

The global $MEDIA is available from init which is calling create_instance.

Take a look on the training dedicated to media to use correctly this class and Media module

Table of Contents

Constants

audio_ext  = ['mp3', 'm4a', 'aac', 'oga', 'ogg', 'wav', 'flac']
audio extentions accepted, used to filter uploads
image_ext  = ['jpg', 'jpeg', 'png', 'bmp', 'gif', 'svg', 'svgz', 'webp']
image extentions accepted, used to filter uploads
video_ext  = ['mp4', 'ogg', 'avi', 'mpeg', 'mts', 'wmv', 'qt', 'mov', 'mpg', 'mkv', 'ogv', 'ts', 'm4v', 'mxf', 'webm']
video extentions accepted, used to filter uploads

Properties

$base_path  : mixed
$current_media  : mixed

Methods

__construct()  : mixed
check_video_compat()  : bool
Checks if a video file is compatible (codec, pixel format, etc.).
copy_use()  : bool
Copies a usage record from one media identifier to another.
create_instance()  : global
Create the global $MEDIA instance of this class
delete_media()  : bool
Deletes all media for a given field identifier and use key.
encode_video_src()  : string
take the classic video path to create the "pp" variable for public/media/media.php player in the instance
file_to_image()  : resource|false
Creates a GdImage from a file.
get_html()  : mixed
Returns the HTML tag for the media (image or video) for the given field identifier and ID.
get_image_info()  : array<string|int, mixed>
Retrieves image information (width, height) using ffprobe.
get_info()  : array<string|int, mixed>|false
Retrieves media information (width, height, etc.) for a given media ID and use key.
get_last_use_key()  : int
return the last use_key to use or -1 if it's the first one before use, have to increment by one
get_media()  : array<string|int, mixed>|false
Retrieves a media record for the given field identifier and ID.
get_media_list()  : array<string|int, mixed>|false
Retrieves a list of media records in use table for the given field identifier and ID.
get_video_info()  : array<string|int, mixed>
Retrieves video information (width, height, fps, duration, etc.) using ffprobe.
has_media()  : bool
Checks if there is at least one media for the given field identifier and ID.
image_crop()  : resource
Crops an GdImage to the specified rectangle.
image_noprop_resize()  : resource
Resizes a GdImage to exact width and height (non-proportional).
image_process()  : string|null
Process image according to the process array.
image_resize()  : resource
Proportionally resizes a GdImage to fit within max width and height.
image_rotate()  : resource
Rotates an GdImage by a given angle, optionally cropping to original size.
image_to_base64()  : string
Converts an image file to a base64-encoded data URI.
image_to_file()  : bool
Saves a GdImage to a file, with support for transparency and quality.
is_image()  : bool
Checks if the given media ID and use key correspond to an image.
is_video()  : bool
Checks if the given media ID and use key correspond to a video.
jpeg_fix_orientation()  : void
Fixes the orientation of a JPEG image file based on EXIF data.
process_media()  : bool
Process and save media after upload or from a media list.
save_media()  : int
This method inserts or updates a record in the media_data table for the given media file,
save_process()  : int
Save the process done on a file in case we must redo
save_use()  : void
Saves or updates a usage record for a media file in the database.
send_file()  : bool
Streams a file to the browser, supporting range requests and optional locking.
square_crop()  : resource
Crops an GdImage to a square and resizes to the given size.
unshare_media()  : int|false
Unshares a media file for a given field identifier, use key, and process key.
video_process()  : string|null
Processes a video file according to the specified process array.

Constants

audio_ext

audio extentions accepted, used to filter uploads

public array<string|int, mixed> audio_ext = ['mp3', 'm4a', 'aac', 'oga', 'ogg', 'wav', 'flac']

image_ext

image extentions accepted, used to filter uploads

public array<string|int, mixed> image_ext = ['jpg', 'jpeg', 'png', 'bmp', 'gif', 'svg', 'svgz', 'webp']

video_ext

video extentions accepted, used to filter uploads

public array<string|int, mixed> video_ext = ['mp4', 'ogg', 'avi', 'mpeg', 'mts', 'wmv', 'qt', 'mov', 'mpg', 'mkv', 'ogv', 'ts', 'm4v', 'mxf', 'webm']

Properties

$base_path

public mixed $base_path

$current_media

public mixed $current_media = ''

Methods

__construct()

public __construct() : mixed

check_video_compat()

Checks if a video file is compatible (codec, pixel format, etc.).

public check_video_compat(array<string|int, mixed> $videoInfos) : bool
Parameters
$videoInfos : array<string|int, mixed>

The video information array (from ffprobe).

Return values
bool —

True if compatible, false otherwise.

copy_use()

Copies a usage record from one media identifier to another.

public copy_use(string $media_id_to_copy, string $media_id) : bool

Duplicates all entries in the media_use table for the given source media ID to the target media ID.

Parameters
$media_id_to_copy : string

The source logical media identifier.

$media_id : string

The target logical media identifier.

Return values
bool —

True on success, false if no usage found.

create_instance()

Create the global $MEDIA instance of this class

public static create_instance([bool $forceNewInstance = false ]) : global
Parameters
$forceNewInstance : bool = false

to be sure that $MEDIA is restarted from scractch

Return values
global —

$MEDIA

delete_media()

Deletes all media for a given field identifier and use key.

public delete_media([string|false $field_identifier = false ][, string|false $field_id = false ][, int|false $use_key = false ]) : bool

Only deletes the media file if it is not referenced elsewhere.

Parameters
$field_identifier : string|false = false

The field identifier.

$field_id : string|false = false

The field ID.

$use_key : int|false = false

The use key.

Return values
bool —

True on success, false on failure.

encode_video_src()

take the classic video path to create the "pp" variable for public/media/media.php player in the instance

public encode_video_src(array<string|int, mixed> $video_params) : string
Parameters
$video_params : array<string|int, mixed>

The video params

Tags
see
in

media module public, media.php is there to call media for display images or streaming with security options.

Return values
string —

the pp content

file_to_image()

Creates a GdImage from a file.

public file_to_image(string $file) : resource|false

Supports jpg, jpeg, png, bmp, gif, and webp formats.

Parameters
$file : string

Path to the image file.

Return values
resource|false —

GdImage, or false.

get_html()

Returns the HTML tag for the media (image or video) for the given field identifier and ID.

public get_html([string|false $field_identifier = false ][, string|false $field_id = false ][, string $size = 'small' ][, int|false $use_key = false ][, bool $nodl = false ]) : mixed
Parameters
$field_identifier : string|false = false

The field identifier.

$field_id : string|false = false

The field ID.

$size : string = 'small'

The size ('small', 'big', or pixel value).

$use_key : int|false = false

The use key.

$nodl : bool = false

activate secured feature in public/media/media.php to stop download

Return values
mixed —

HTML output or false if not found.

get_image_info()

Retrieves image information (width, height) using ffprobe.

public static get_image_info(string $path) : array<string|int, mixed>
Parameters
$path : string

The path to the image file.

Return values
array<string|int, mixed> —

Image information array.

get_info()

Retrieves media information (width, height, etc.) for a given media ID and use key.

public static get_info([string|false $media_id = false ][, int|false $use_key = false ]) : array<string|int, mixed>|false
Parameters
$media_id : string|false = false

The logical media identifier.

$use_key : int|false = false

The use key.

Return values
array<string|int, mixed>|false —

Array of media info, or false if not found.

get_last_use_key()

return the last use_key to use or -1 if it's the first one before use, have to increment by one

public get_last_use_key(string $media_id) : int
Parameters
$media_id : string

The logical media identifier.

Return values
int —

The last use_key found, or -1 if none exists.

get_media()

Retrieves a media record for the given field identifier and ID.

public static get_media([string|false $field_identifier = false ][, string|false $field_id = false ][, string $size = 'small' ][, int|false $use_key = false ]) : array<string|int, mixed>|false
Parameters
$field_identifier : string|false = false

The field identifier.

$field_id : string|false = false

The field ID.

$size : string = 'small'

The size ('small', 'big', or pixel value).

$use_key : int|false = false

The use key.

Return values
array<string|int, mixed>|false —

Media info array or false if not found.

get_media_list()

Retrieves a list of media records in use table for the given field identifier and ID.

public static get_media_list([string|false $field_identifier = false ][, string|false $field_id = false ][, string $size = 'small' ]) : array<string|int, mixed>|false
Parameters
$field_identifier : string|false = false

The field identifier.

$field_id : string|false = false

The field ID.

$size : string = 'small'

The size ('small', 'big', or pixel value).

Return values
array<string|int, mixed>|false —

List of media info arrays or false if not found.

get_video_info()

Retrieves video information (width, height, fps, duration, etc.) using ffprobe.

public static get_video_info(string $path) : array<string|int, mixed>
Parameters
$path : string

The path to the video file.

Return values
array<string|int, mixed> —

Video information array.

has_media()

Checks if there is at least one media for the given field identifier and ID.

public static has_media([string|false $field_identifier = false ][, string|false $field_id = false ]) : bool
Parameters
$field_identifier : string|false = false

The field identifier.

$field_id : string|false = false

The field ID.

Return values
bool —

True if media exists, false otherwise.

image_crop()

Crops an GdImage to the specified rectangle.

public image_crop(resource $image[, int $x = 0 ][, int $y = 0 ][, int $width = 200 ][, int $height = 200 ]) : resource
Parameters
$image : resource

The GdImage.

$x : int = 0

X coordinate of the crop start.

$y : int = 0

Y coordinate of the crop start.

$width : int = 200

Crop width.

$height : int = 200

Crop height.

Return values
resource —

The cropped GdImage.

image_noprop_resize()

Resizes a GdImage to exact width and height (non-proportional).

public image_noprop_resize(resource $image[, int $width = 200 ][, int $height = 200 ]) : resource
Parameters
$image : resource

The GdImage.

$width : int = 200

Target width.

$height : int = 200

Target height.

Return values
resource —

The resized GdImage.

image_process()

Process image according to the process array.

public image_process(array<string|int, mixed> $process) : string|null

Handles various image operations such as resize, crop, rotate, and saving to file. Supports SVG detection and special handling. Saves processed images and some of their data to the database.

Parameters
$process : array<string|int, mixed>

The process instructions and parameters for the image. Must contain at least 'input', 'media_id', and 'use_key'. May contain 'original', 'output', and 'process' : 'process' is an array, a list of steps, each being an associative array with:

  • type: (string) The operation type. Supported values:
    • 'image_resize' (requires 'max_width', optional 'max_height', optional 'force')
    • 'image_noprop_resize' (requires 'width', 'height') (for a non proportional resize)
    • 'image_rotate' (requires 'angle', optional 'crop')
    • 'image_crop' (requires 'x', 'y', 'width', 'height')
    • 'square_crop' (requires 'size')
    • 'image_to_file' (requires 'output', optional 'quality')
  • Additional keys may include:
    • 'output': (string) Output file path for the step
    • 'suffix': (string) Suffix to add to the output filename
    • 'quality': (int|string) Output quality (0-100 or 'cop' for copy)
    • 'path': (string) Base path for output
    • 'force_jpg': (bool) Force output as JPG Example: [ ['type'=>'image_resize', 'max_width'=>200, 'max_height'=>200], ['type'=>'image_to_file', 'quality'=>80] ]
Return values
string|null —

Returns 'done' on success, or an error message string on failure.

image_resize()

Proportionally resizes a GdImage to fit within max width and height.

public image_resize(resource $image[, int $max_width = 200 ][, int $max_height = 200 ][, bool $force = false ]) : resource
Parameters
$image : resource

The GdImage.

$max_width : int = 200

Maximum width.

$max_height : int = 200

Maximum height.

$force : bool = false

Optional. Force resize even if smaller. Default false.

Return values
resource —

The resized GdImage.

image_rotate()

Rotates an GdImage by a given angle, optionally cropping to original size.

public image_rotate(resource $image, int $angle[, bool $crop = false ]) : resource
Parameters
$image : resource

The GdImage.

$angle : int

The rotation angle in degrees.

$crop : bool = false

Optional. Crop to original size. Default false.

Return values
resource —

The rotated GdImage.

image_to_base64()

Converts an image file to a base64-encoded data URI.

public image_to_base64(string $file[, int|false $width = false ][, int|false $height = false ][, string|false $format = false ][, int|false $quality = false ]) : string

Optionally resizes or reformats the image before encoding.

Parameters
$file : string

The path to the image file.

$width : int|false = false

Optional. Target width for resizing. Default false (no resize).

$height : int|false = false

Optional. Target height for resizing. Default false (no resize).

$format : string|false = false

Optional. Output format ('jpeg', 'png', 'gif', 'webp', 'bmp'). Default false (keep original).

$quality : int|false = false

Optional. Output quality (0-100). Default false (uses 50 if format is set).

Return values
string —

Base64-encoded data URI of the image, or an error message if not compatible.

image_to_file()

Saves a GdImage to a file, with support for transparency and quality.

public image_to_file(resource $image, string $output[, int $quality = 100 ]) : bool
Parameters
$image : resource

The GdImage.

$output : string

The output file path.

$quality : int = 100

Optional. Output quality (0-100). Default 100. 0 : Horrible , 100 : the best (and the heaviest)

Return values
bool —

True on success, false.

is_image()

Checks if the given media ID and use key correspond to an image.

public static is_image([string|false $media_id = false ][, int|false $use_key = false ]) : bool
Parameters
$media_id : string|false = false

The logical media identifier.

$use_key : int|false = false

The use key.

Return values
bool —

True if the media is an image, false otherwise.

is_video()

Checks if the given media ID and use key correspond to a video.

public static is_video([string|false $media_id = false ][, int|false $use_key = false ]) : bool
Parameters
$media_id : string|false = false

The logical media identifier.

$use_key : int|false = false

The use key.

Return values
bool —

True if the media is a video, false otherwise.

jpeg_fix_orientation()

Fixes the orientation of a JPEG image file based on EXIF data.

public static jpeg_fix_orientation(string $filename) : void

Some smartphone record badly the orientation in jpeg format !

Parameters
$filename : string

The path to the JPEG file.

process_media()

Process and save media after upload or from a media list.

public process_media(array<string|int, mixed> $post[, mixed $created_id = false ]) : bool

Handles the processing of images and videos, including moving uploaded files, applying transformations (resize, crop, rotate, etc.), saving processed files, and updating the database with media and usage information. Also manages replacement of existing media, handling of multiple files, and selection of media from an existing list.

Parameters
$post : array<string|int, mixed>

The POST data containing media information and files. it can contain the following keys:

  • media_data (array) : Associative table of media to be processed, indexed by identifier or logical field. Each entry is an array that can contain: :
    • files (array) : Uploaded files (ex: $_FILES-like structure, or temporary path array)...
    • list (array) : List of existing media identifiers to associate.
    • process (array) : Table of operations to apply (ex: [['type'=>'image_resize', ...], ...]).
    • replace (bool|int) : Should the media replace the existing one ?
    • other fields customized according to the call context.
  • media_replace_all (int|bool) : replaces all existing media related to the entity.
$created_id : mixed = false

Optional. If provided, used to update the media identifier.

Return values
bool —

Returns true if all media were processed successfully, false if errors occurred.

save_media()

This method inserts or updates a record in the media_data table for the given media file,

public save_media(string $media_id, int $use_key, int $process_key, string $path, string $filename[, int $original = 0 ][, int $type = 0 ]) : int

It check that the path is relative to the base media directory. If the media already exists for the given identifiers, it updates the record instead of inserting.

Also saves the filename as a short translation value for the current language.

Parameters
$media_id : string

The logical media identifier (ex: 'flag¤123').

$use_key : int

The use key for this media (for multi-use cases).

$process_key : int

The process key (for processed versions), or 0 for original.

$path : string

The file path (relative to the base media directory).

$filename : string

The original filename of the media.

$original : int = 0

1 if this is the original file, 0 otherwise.

$type : int = 0

The media type (1=image, 2=video, etc.).

Return values
int —

The ID of the media record in the database.

save_process()

Save the process done on a file in case we must redo

public save_process(string $process) : int
Parameters
$process : string
Return values
int —

id in DB

save_use()

Saves or updates a usage record for a media file in the database.

public save_use(string $media_id, int $use_key, int $process_key, int $id_media, int $id_process) : void

Associates a media file with an identifier, use_key, and process_key. If it already exists , it updates the media and process IDs.

Parameters
$media_id : string

The logical media identifier (e.g., 'flag¤123').

$use_key : int

The use key for this media (for multi-use cases).

$process_key : int

The process key (for processed versions), or 0 for original.

$id_media : int

The ID of the media in the media_data table.

$id_process : int

The ID of the process in the media_process table.

send_file()

Streams a file to the browser, supporting range requests and optional locking.

public static send_file(string $path[, bool $inline = true ][, bool $lock = false ]) : bool
Parameters
$path : string

The file path to send.

$inline : bool = true

Optional. Whether to display inline or as attachment. Default true.

$lock : bool = false

Optional. Whether to lock the file during transfer. Default false.

Tags
see
in

media module public, media.php is there to call media for display images or streaming with security options.

Return values
bool —

True if the file was sent successfully, false otherwise.

square_crop()

Crops an GdImage to a square and resizes to the given size.

public square_crop(resource $image, int $size) : resource
Parameters
$image : resource

The GdImage.

$size : int

The target square size.

Return values
resource —

The square-cropped and resized GdImage.

unshare_media()

Unshares a media file for a given field identifier, use key, and process key.

public unshare_media([string|false $field_identifier = false ][, int|false $use_key = false ][, int|false $process_key = false ]) : int|false

Copies the media if needed and updates the database.

Parameters
$field_identifier : string|false = false

The field identifier.

$use_key : int|false = false

The use key.

$process_key : int|false = false

The process key.

Return values
int|false —

The new media ID or false on failure.

video_process()

Processes a video file according to the specified process array.

public video_process(array<string|int, mixed> $process[, bool $no_bdd = false ]) : string|null

Handles resizing, recompression, thumbnail generation, and format conversion using ffmpeg. Saves processed videos and their metadata to the database.

Parameters
$process : array<string|int, mixed>

The process instructions and parameters for the video. The $process array can contain the following keys:

  • input (string) : Path to the input video file (required).
  • output (string) : Path to the output video file (optional, auto-generated if not set).
  • media_id (string) : Logical media identifier (required).
  • use_key (int) : Use key for this media (required).
  • original (bool|int) : If true, marks this as the original file (optional).
  • pid (string) : Process identifier for system calls (optional).
  • sequence (array) : Video sequence info (optional, used for image sequences).
  • process (array) : List of processing steps, each being an associative array with:
    • type (string): The operation type. Supported values:
      • 'video_resize' (requires 'max_width', optional 'max_height')
      • 'video_resize_from_height' (requires 'max_height')
      • 'video_from_sequence' (requires 'fps', 'start_number', 'total_images', 'max_height')
      • 'recomp' (forces recompression)
      • 'thumbnails' (requires 'max_width' or 'max_height', 'number')
    • desinterlace (string): 'ok' to enable deinterlacing (optional)
    • Additional keys may be required depending on the type.
  • no_bdd (bool): If true, skips database operations (optional, default false).

Example: $process = [ 'input' => '/tmp/video.mp4', 'output' => '/dest/video.mp4', 'media_id' => 'video¤123', 'use_key' => 0, 'original' => 1, 'process' => [ ['type'=>'video_resize', 'max_width'=>640, 'max_height'=>360], ['type'=>'thumbnails', 'max_width'=>320, 'number'=>5] ] ];

$no_bdd : bool = false

Optional. If true, skips database operations. Default false.

Return values
string|null —

Returns 'done' on success, or an error message string on failure.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results