class ManagedFile

Same name in other branches

9 core/modules/file/src/Element/ManagedFile.php \Drupal\file\Element\ManagedFile
8.9.x core/modules/file/src/Element/ManagedFile.php \Drupal\file\Element\ManagedFile
10 core/modules/file/src/Element/ManagedFile.php \Drupal\file\Element\ManagedFile

Provides an AJAX/progress aware widget for uploading and saving a file.

Hierarchy

class \Drupal\Component\Plugin\PluginBase implements \Drupal\Component\Plugin\PluginInspectionInterface, \Drupal\Component\Plugin\DerivativeInspectionInterface
- class \Drupal\Core\Plugin\PluginBase extends \Drupal\Component\Plugin\PluginBase uses \Drupal\Core\StringTranslation\StringTranslationTrait, \Drupal\Core\DependencyInjection\DependencySerializationTrait, \Drupal\Core\Messenger\MessengerTrait
  - class \Drupal\Core\Render\Element\RenderElementBase extends \Drupal\Core\Plugin\PluginBase implements \Drupal\Core\Render\Element\ElementInterface
    - class \Drupal\Core\Render\Element\FormElementBase extends \Drupal\Core\Render\Element\RenderElementBase implements \Drupal\Core\Render\Element\FormElementInterface
      - class \Drupal\file\Element\ManagedFile extends \Drupal\Core\Render\Element\FormElementBase

Expanded class hierarchy of ManagedFile

1 file declares its use of ManagedFile

FileWidget.php in core/modules/file/src/Plugin/Field/FieldWidget/FileWidget.php

2 string references to 'ManagedFile'

ClaroPreRender::trustedCallbacks in core/themes/claro/src/ClaroPreRender.php: Lists the trusted callbacks provided by the implementing class.
claro_element_info_alter in core/themes/claro/claro.theme: Implements hook_element_info_alter().

File

core/modules/file/src/Element/ManagedFile.php, line 24

Namespace

Drupal\file\Element

View source

class ManagedFile extends FormElementBase {
    
    /**
     * {@inheritdoc}
     */
    public function getInfo() {
        $class = static::class;
        return [
            '#input' => TRUE,
            '#process' => [
                [
                    $class,
                    'processManagedFile',
                ],
            ],
            '#element_validate' => [
                [
                    $class,
                    'validateManagedFile',
                ],
            ],
            '#pre_render' => [
                [
                    $class,
                    'preRenderManagedFile',
                ],
            ],
            '#theme' => 'file_managed_file',
            '#theme_wrappers' => [
                'form_element',
            ],
            '#progress_indicator' => 'throbber',
            '#progress_message' => NULL,
            '#upload_validators' => [],
            '#upload_location' => NULL,
            '#size' => 22,
            '#multiple' => FALSE,
            '#extended' => FALSE,
            '#attached' => [
                'library' => [
                    'file/drupal.file',
                ],
            ],
            '#accept' => NULL,
        ];
    }
    
    /**
     * {@inheritdoc}
     */
    public static function valueCallback(&$element, $input, FormStateInterface $form_state) {
        // Find the current value of this field.
        $fids = !empty($input['fids']) ? explode(' ', $input['fids']) : [];
        foreach ($fids as $key => $fid) {
            $fids[$key] = (int) $fid;
        }
        $force_default = FALSE;
        // Process any input and save new uploads.
        if ($input !== FALSE) {
            $input['fids'] = $fids;
            $return = $input;
            // Uploads take priority over all other values.
            if ($files = file_managed_file_save_upload($element, $form_state)) {
                if ($element['#multiple']) {
                    $fids = array_merge($fids, array_keys($files));
                }
                else {
                    $fids = array_keys($files);
                }
            }
            else {
                // Check for #filefield_value_callback values.
                // Because FAPI does not allow multiple #value_callback values like it
                // does for #element_validate and #process, this fills the missing
                // functionality to allow File fields to be extended through FAPI.
                if (isset($element['#file_value_callbacks'])) {
                    foreach ($element['#file_value_callbacks'] as $callback) {
                        $callback($element, $input, $form_state);
                    }
                }
                // Load files if the FIDs have changed to confirm they exist.
                if (!empty($input['fids'])) {
                    $fids = [];
                    foreach ($input['fids'] as $fid) {
                        if ($file = File::load($fid)) {
                            $fids[] = $file->id();
                            if (!$file->access('download')) {
                                $force_default = TRUE;
                                break;
                            }
                            // Temporary files that belong to other users should never be
                            // allowed.
                            if ($file->isTemporary()) {
                                if ($file->getOwnerId() != \Drupal::currentUser()->id()) {
                                    $force_default = TRUE;
                                    break;
                                }
                                elseif (\Drupal::currentUser()->isAnonymous()) {
                                    $token = NestedArray::getValue($form_state->getUserInput(), array_merge($element['#parents'], [
                                        'file_' . $file->id(),
                                        'fid_token',
                                    ]));
                                    $file_hmac = Crypt::hmacBase64('file-' . $file->id(), \Drupal::service('private_key')->get() . Settings::getHashSalt());
                                    if ($token === NULL || !hash_equals($file_hmac, $token)) {
                                        $force_default = TRUE;
                                        break;
                                    }
                                }
                            }
                        }
                    }
                    if ($force_default) {
                        $fids = [];
                    }
                }
            }
        }
        // If there is no input or if the default value was requested above, use the
        // default value.
        if ($input === FALSE || $force_default) {
            if ($element['#extended']) {
                $default_fids = $element['#default_value']['fids'] ?? [];
                $return = $element['#default_value'] ?? [
                    'fids' => [],
                ];
            }
            else {
                $default_fids = $element['#default_value'] ?? [];
                $return = [
                    'fids' => [],
                ];
            }
            // Confirm that the file exists when used as a default value.
            if (!empty($default_fids)) {
                $fids = [];
                foreach ($default_fids as $fid) {
                    if ($file = File::load($fid)) {
                        $fids[] = $file->id();
                    }
                }
            }
        }
        $return['fids'] = $fids;
        return $return;
    }
    
    /**
     * #ajax callback for managed_file upload forms.
     *
     * This ajax callback takes care of the following things:
     *   - Ensures that broken requests due to too big files are caught.
     *   - Adds a class to the response to be able to highlight in the UI, that a
     *     new file got uploaded.
     *
     * @param array $form
     *   The build form.
     * @param \Drupal\Core\Form\FormStateInterface $form_state
     *   The form state.
     * @param \Symfony\Component\HttpFoundation\Request $request
     *   The current request.
     *
     * @return \Drupal\Core\Ajax\AjaxResponse
     *   The ajax response of the ajax upload.
     */
    public static function uploadAjaxCallback(&$form, FormStateInterface &$form_state, Request $request) {
        
        /** @var \Drupal\Core\Render\RendererInterface $renderer */
        $renderer = \Drupal::service('renderer');
        $form_parents = explode('/', $request->query
            ->get('element_parents'));
        // Sanitize form parents before using them.
        $form_parents = array_filter($form_parents, [
            Element::class,
            'child',
        ]);
        // Retrieve the element to be rendered.
        $form = NestedArray::getValue($form, $form_parents);
        // Add the special AJAX class if a new file was added.
        $current_file_count = $form_state->get('file_upload_delta_initial');
        if (isset($form['#file_upload_delta']) && $current_file_count < $form['#file_upload_delta']) {
            $form[$current_file_count]['#attributes']['class'][] = 'ajax-new-content';
        }
        $status_messages = [
            '#type' => 'status_messages',
        ];
        $form['#prefix'] .= $renderer->renderRoot($status_messages);
        $output = $renderer->renderRoot($form);
        $response = new AjaxResponse();
        $response->setAttachments($form['#attached']);
        return $response->addCommand(new ReplaceCommand(NULL, $output));
    }
    
    /**
     * Render API callback: Expands the managed_file element type.
     *
     * Expands the file type to include Upload and Remove buttons, as well as
     * support for a default value.
     */
    public static function processManagedFile(&$element, FormStateInterface $form_state, &$complete_form) {
        // This is used sometimes so let's implode it just once.
        $parents_prefix = implode('_', $element['#parents']);
        $fids = $element['#value']['fids'] ?? [];
        // Set some default element properties.
        $element['#progress_indicator'] = empty($element['#progress_indicator']) ? 'none' : $element['#progress_indicator'];
        $element['#files'] = !empty($fids) ? File::loadMultiple($fids) : [];
        $element['#tree'] = TRUE;
        // Generate a unique wrapper HTML ID.
        $ajax_wrapper_id = Html::getUniqueId('ajax-wrapper');
        $ajax_settings = [
            'callback' => [
                static::class,
                'uploadAjaxCallback',
            ],
            'options' => [
                'query' => [
                    'element_parents' => implode('/', $element['#array_parents']),
                ],
            ],
            'wrapper' => $ajax_wrapper_id,
            'effect' => 'fade',
            'progress' => [
                'type' => $element['#progress_indicator'],
                'message' => $element['#progress_message'],
            ],
        ];
        // Set up the buttons first since we need to check if they were clicked.
        $element['upload_button'] = [
            '#name' => $parents_prefix . '_upload_button',
            '#type' => 'submit',
            '#value' => t('Upload'),
            '#attributes' => [
                'class' => [
                    'js-hide',
                ],
            ],
            '#validate' => [],
            '#submit' => [
                'file_managed_file_submit',
            ],
            '#limit_validation_errors' => [
                $element['#parents'],
            ],
            '#ajax' => $ajax_settings,
            '#weight' => -5,
        ];
        // Force the progress indicator for the remove button to be either 'none' or
        // 'throbber', even if the upload button is using something else.
        $ajax_settings['progress']['type'] = $element['#progress_indicator'] == 'none' ? 'none' : 'throbber';
        $ajax_settings['progress']['message'] = NULL;
        $ajax_settings['effect'] = 'none';
        $element['remove_button'] = [
            '#name' => $parents_prefix . '_remove_button',
            '#type' => 'submit',
            '#value' => $element['#multiple'] ? t('Remove selected') : t('Remove'),
            '#validate' => [],
            '#submit' => [
                'file_managed_file_submit',
            ],
            '#limit_validation_errors' => [
                $element['#parents'],
            ],
            '#ajax' => $ajax_settings,
            '#weight' => 1,
        ];
        $element['fids'] = [
            '#type' => 'hidden',
            '#value' => $fids,
        ];
        // Add progress bar support to the upload if possible.
        if ($element['#progress_indicator'] == 'bar' && extension_loaded('uploadprogress')) {
            $upload_progress_key = mt_rand();
            $element['UPLOAD_IDENTIFIER'] = [
                '#type' => 'hidden',
                '#value' => $upload_progress_key,
                '#attributes' => [
                    'class' => [
                        'file-progress',
                    ],
                ],
                // Uploadprogress extension requires this field to be at the top of
                // the form.
'#weight' => -20,
            ];
            // Add the upload progress callback.
            $element['upload_button']['#ajax']['progress']['url'] = Url::fromRoute('file.ajax_progress', [
                'key' => $upload_progress_key,
            ]);
            // Set a custom submit event so we can modify the upload progress
            // identifier element before the form gets submitted.
            $element['upload_button']['#ajax']['event'] = 'fileUpload';
        }
        // Use a manually generated ID for the file upload field so the desired
        // field label can be associated with it below. Use the same method for
        // setting the ID that the form API autogenerator does.
        // @see \Drupal\Core\Form\FormBuilder::doBuildForm()
        $id = Html::getUniqueId('edit-' . implode('-', array_merge($element['#parents'], [
            'upload',
        ])));
        // The file upload field itself.
        $element['upload'] = [
            '#name' => 'files[' . $parents_prefix . ']',
            '#type' => 'file',
            // This #title will not actually be used as the upload field's HTML label,
            // since the theme function for upload fields never passes the element
            // through theme('form_element'). Instead the parent element's #title is
            // used as the label (see below). That is usually a more meaningful label
            // anyway.
'#title' => t('Choose a file'),
            '#title_display' => 'invisible',
            '#id' => $id,
            '#size' => $element['#size'],
            '#multiple' => $element['#multiple'],
            '#theme_wrappers' => [],
            '#weight' => -10,
            '#error_no_message' => TRUE,
        ];
        if (!empty($element['#description'])) {
            $element['upload']['#attributes']['aria-describedby'] = $element['#id'] . '--description';
        }
        if (!empty($element['#accept'])) {
            $element['upload']['#attributes'] = [
                'accept' => $element['#accept'],
            ];
        }
        // Indicate that $element['#title'] should be used as the HTML label for the
        // file upload field.
        $element['#label_for'] = $element['upload']['#id'];
        if (!empty($fids) && $element['#files']) {
            foreach ($element['#files'] as $delta => $file) {
                $file_link = [
                    '#theme' => 'file_link',
                    '#file' => $file,
                ];
                if ($element['#multiple']) {
                    $element['file_' . $delta]['selected'] = [
                        '#type' => 'checkbox',
                        '#title' => \Drupal::service('renderer')->renderInIsolation($file_link),
                    ];
                }
                else {
                    $element['file_' . $delta]['filename'] = $file_link + [
                        '#weight' => -10,
                    ];
                }
                // Anonymous users who have uploaded a temporary file need a
                // non-session-based token added so $this->valueCallback() can check
                // that they have permission to use this file on subsequent submissions
                // of the same form (for example, after an Ajax upload or form
                // validation error).
                if ($file->isTemporary() && \Drupal::currentUser()->isAnonymous()) {
                    $element['file_' . $delta]['fid_token'] = [
                        '#type' => 'hidden',
                        '#value' => Crypt::hmacBase64('file-' . $delta, \Drupal::service('private_key')->get() . Settings::getHashSalt()),
                    ];
                }
            }
        }
        // Add the extension list to the page as JavaScript settings.
        if (isset($element['#upload_validators']['FileExtension']['extensions'])) {
            $allowed_extensions = $element['#upload_validators']['FileExtension']['extensions'];
            $extension_list = implode(',', array_filter(explode(' ', $allowed_extensions)));
            $element['upload']['#attached']['drupalSettings']['file']['elements']['#' . $id] = $extension_list;
        }
        // Prefix and suffix used for Ajax replacement.
        $element['#prefix'] = '<div id="' . $ajax_wrapper_id . '">';
        $element['#suffix'] = '</div>';
        return $element;
    }
    
    /**
     * Render API callback: Hides display of the upload or remove controls.
     *
     * Upload controls are hidden when a file is already uploaded. Remove controls
     * are hidden when there is no file attached. Controls are hidden here instead
     * of in \Drupal\file\Element\ManagedFile::processManagedFile(), because
     * #access for these buttons depends on the managed_file element's #value. See
     * the documentation of \Drupal\Core\Form\FormBuilderInterface::doBuildForm()
     * for more detailed information about the relationship between #process,
     * #value, and #access.
     *
     * Because #access is set here, it affects display only and does not prevent
     * JavaScript or other untrusted code from submitting the form as though
     * access were enabled. The form processing functions for these elements
     * should not assume that the buttons can't be "clicked" just because they are
     * not displayed.
     *
     * @see \Drupal\file\Element\ManagedFile::processManagedFile()
     * @see \Drupal\Core\Form\FormBuilderInterface::doBuildForm()
     */
    public static function preRenderManagedFile($element) {
        // If we already have a file, we don't want to show the upload controls.
        if (!empty($element['#value']['fids'])) {
            if (!$element['#multiple']) {
                $element['upload']['#access'] = FALSE;
                $element['upload_button']['#access'] = FALSE;
            }
        }
        else {
            $element['remove_button']['#access'] = FALSE;
        }
        return $element;
    }
    
    /**
     * Render API callback: Validates the managed_file element.
     */
    public static function validateManagedFile(&$element, FormStateInterface $form_state, &$complete_form) {
        $triggering_element = $form_state->getTriggeringElement();
        $clicked_button = isset($triggering_element['#parents']) ? end($triggering_element['#parents']) : '';
        if ($clicked_button != 'remove_button' && !empty($element['fids']['#value'])) {
            $fids = $element['fids']['#value'];
            foreach ($fids as $fid) {
                if ($file = File::load($fid)) {
                    // If referencing an existing file, only allow if there are existing
                    // references. This prevents unmanaged files from being deleted if
                    // this item were to be deleted. When files that are no longer in use
                    // are automatically marked as temporary (now disabled by default),
                    // it is not safe to reference a permanent file without usage. Adding
                    // a usage and then later on removing it again would delete the file,
                    // but it is unknown if and where it is currently referenced. However,
                    // when files are not marked temporary (and then removed)
                    // automatically, it is safe to add and remove usages, as it would
                    // simply return to the current state.
                    // @see https://www.drupal.org/node/2891902
                    if ($file->isPermanent() && \Drupal::config('file.settings')->get('make_unused_managed_files_temporary')) {
                        $references = static::fileUsage()->listUsage($file);
                        if (empty($references)) {
                            // We expect the field name placeholder value to be wrapped in t()
                            // here, so it won't be escaped again as it's already marked safe.
                            $form_state->setError($element, t('The file used in the @name field may not be referenced.', [
                                '@name' => $element['#title'],
                            ]));
                        }
                    }
                }
                else {
                    // We expect the field name placeholder value to be wrapped in t()
                    // here, so it won't be escaped again as it's already marked safe.
                    $form_state->setError($element, t('The file referenced by the @name field does not exist.', [
                        '@name' => $element['#title'],
                    ]));
                }
            }
        }
        // Check required property based on the FID.
        if ($element['#required'] && empty($element['fids']['#value']) && !in_array($clicked_button, [
            'upload_button',
            'remove_button',
        ])) {
            // We expect the field name placeholder value to be wrapped in t()
            // here, so it won't be escaped again as it's already marked safe.
            $form_state->setError($element, t('@name field is required.', [
                '@name' => $element['#title'],
            ]));
        }
        // Consolidate the array value of this field to array of FIDs.
        if (!$element['#extended']) {
            $form_state->setValueForElement($element, $element['fids']['#value']);
        }
    }
    
    /**
     * Wraps the file usage service.
     *
     * @return \Drupal\file\FileUsage\FileUsageInterface
     */
    protected static function fileUsage() {
        return \Drupal::service('file.usage');
    }

}

Members

Title Sort descending	Modifiers	Object type	Summary	Overriden Title	Overrides
FormElementBase::processAutocomplete	public static	function	Adds autocomplete functionality to elements.		1
FormElementBase::processPattern	public static	function	#process callback for #pattern form element property.		1
FormElementBase::validatePattern	public static	function	#element_validate callback for #pattern form element property.		1
ManagedFile::fileUsage	protected static	function	Wraps the file usage service.
ManagedFile::getInfo	public	function	Returns the element properties for this element.	Overrides ElementInterface::getInfo
ManagedFile::preRenderManagedFile	public static	function	Render API callback: Hides display of the upload or remove controls.
ManagedFile::processManagedFile	public static	function	Render API callback: Expands the managed_file element type.
ManagedFile::uploadAjaxCallback	public static	function	#ajax callback for managed_file upload forms.
ManagedFile::validateManagedFile	public static	function	Render API callback: Validates the managed_file element.
ManagedFile::valueCallback	public static	function	Determines how user input is mapped to an element's #value property.	Overrides FormElementBase::valueCallback
PluginInspectionInterface::getPluginDefinition	public	function	Gets the definition of the plugin implementation.		7
PluginInspectionInterface::getPluginId	public	function	Gets the plugin ID of the plugin instance.		3
RenderElementBase::preRenderAjaxForm	public static	function	Adds Ajax information about an element to communicate with JavaScript.		2
RenderElementBase::preRenderGroup	public static	function	Adds members of this group as actual elements for rendering.		2
RenderElementBase::processAjaxForm	public static	function	Form element processing handler for the #ajax form property.		3
RenderElementBase::processGroup	public static	function	Arranges elements into groups.		2
RenderElementBase::setAttributes	public static	function	Sets a form element's class attribute.	Overrides ElementInterface::setAttributes	2

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.

class ManagedFile

Hierarchy

File

Namespace

Members

Search drupal 11.x

API Navigation

Breadcrumb

class ManagedFile

Hierarchy

File

Namespace

Members

Search drupal 11.x

API Navigation