Coding standards
Security in ResourceSpace
Developer reference
Database
Action functions
Admin functions
Ajax functions
Annotation functions
API functions
Collections functions
Comment functions
Config functions
CSV export functions
Dash functions
Debug functions
Encryption functions
Facial recognition functions
File functions
General functions
Language functions
Log functions
Login functions
Message functions
Migration functions
Node functions
PDF functions
Plugin functions
Render functions
Reporting functions
Request functions
Research functions
Slideshow functions
Theme permission functions
User functions
Video functions
Database functions
Metadata functions
Resource functions
Search functions
Map functions
Job functions
Tab functions
Test functions

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

ColumnTypeDefaultDescription
$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 7845 to 7929

Definition

 
function get_download_filename(int $ref, string $size, int $alternative, string $ext): string
{
    resource_type_config_override(get_resource_data($ref)['resource_type']);
    [$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] = i18n_get_translated($field_data);
            } else {
                // No data, just remove placeholder
                $bind[$placeholder] = "";
            }
        }
    }

    // Build the filename
    $filename = preg_replace_callback(
        '/%(field(\d+)|resource|extension|size|alternative|filename)/',
        fn($matches) => $bind[$matches[0]],
        $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');
    }

    // Extra check that the generated filename extension matches the requested extension e.g. if using $filename_field value previews it may have the extension of the original resource file, rather than jpg or the field data was too long and the extension has been removed by truncation.
    $filename_parts = pathinfo($filename);
    if (!isset($filename_parts["extension"]) || strtolower($filename_parts["extension"]) != strtolower($ext)) {
        $filename = mb_strcut($filename_parts["basename"], 0, (254 - strlen($ext)), 'UTF-8') . "." . $ext;
    }

    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 21st May 2025 10:35 Europe/London time based on the source file dated 15th May 2025 09:45 Europe/London time.