Knowledge Base

get_download_filename()

Description

Work out the filename to use, based on the download_filename_format configuration option, when downloading the
specified resource file with the given settings

Parameters

Column	Type	Default	Description
$ref	int		Resource ID
$size	string		size code
$alternative	int		Alternative file ID
$ext:	string
$ext	string		File extension
$dff]		array_map'trim'
[$size
	true;
$GLOBALS['filename_field']

Return

string

Filename to use

Location

include/resource_functions.php lines 8431 to 8511

Definition

 
function get_download_filename(int $ref, string $size, int $alternative, string $ext): string
    {
    [$size, $ext, $dff] = array_map('trim', [$size, $ext, $GLOBALS['download_filename_format']]);
    $fallback_filename = "RS{$ref}.{$ext}";
    $formatted_str = $dff ?: DEFAULT_DOWNLOAD_FILENAME_FORMAT;

    $bind['%resource'] = $ref;
    $bind['%extension'] = $ext;
    $bind['%size'] = $size !== '' ? "_$size" : '';
    $bind['%alternative'] = $alternative > 0 ? "_$alternative" : '';

    // Get (original) filename value
    $filename_val = get_data_by_field($ref, $GLOBALS['filename_field'], true);
    if ($alternative > 0)
        {
        $alt_file = get_alternative_file($ref, $alternative);
        $filename_val = $alt_file !== false ? $alt_file['name'] : '';
        }
    $bind['%filename'] = strip_extension(mb_basename($filename_val), true);

    // Legacy: do an extra check to see if the filename has an uppercase extension that could be preserved
    $filename_val_ext = pathinfo($filename_val, PATHINFO_EXTENSION);
    if ($filename_val_ext !== '' && mb_strtolower($filename_val_ext) === mb_strtolower($ext))
        {
        $bind['%extension'] = $filename_val_ext;
        }

    // Get specific field value
    $matching_fields = []; 
    if (preg_match_all('/%field(\d+)/', $formatted_str, $matching_fields, PREG_SET_ORDER))
        {
        foreach($matching_fields as [$placeholder, $field_id])
            {
            if (!metadata_field_view_access($field_id))
                {
                $bind[$placeholder] = '';
                continue;
                }

            $field_data = trim(get_data_by_field($ref, $field_id, true));
            if ($field_data !== '')
                {
                $bind[$placeholder] = $field_data;
                }
            }
        }

    // Build the filename
    $filename = str_replace(array_keys($bind), array_values($bind), $formatted_str);

    // Allow plugins to completely overwrite it
    $hook_downloadfilenamealt = hook('downloadfilenamealt', '', [$ref, $size, $alternative, $ext]);
    if (is_string($hook_downloadfilenamealt) && $hook_downloadfilenamealt !== '')
        {
        debug('[get_download_filename] Filename overriden by a hook');
        $filename = $hook_downloadfilenamealt;
        }

    // Remove invalid characters
    $filename = (string) preg_replace(
        '/(:|\r\n|\r|\n)/',
        '_',
        trim(strip_tags(nl2br($filename)))
    );

    /**
     * If required, truncate to 255 characters - {@see https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits}
     */
    if (mb_strlen($filename, 'UTF-8') > 255)
        {
        $filename = mb_strcut($filename, 0, 255, 'UTF-8');
        }

    if ($filename !== '')
        {
        return $filename;
        }

    debug('[get_download_filename] Invalid download filename, fall back.');
    return (string) preg_replace('/(:|\r\n|\r|\n)/', '_', strip_tags(nl2br($fallback_filename)));
    }


This article was last updated 11th December 2023 10:05 Europe/London time based on the source file dated 8th December 2023 13:55 Europe/London time.