Issue #3437514 by kim.pepper, alexpott: Deprecate hook_file_validate() API docs

 * Using \Drupal\file\Element\ManagedFile field with a defined list of allowed

 * extensions is best way to provide a file upload field. It will ensure that:

 * - File names are sanitized by the FileUploadSanitizeNameEvent event.

 * - Files are validated by hook implementations of hook_file_validate().

 * - Files are validated by \Drupal\file\Validation\FileValidatorInterface().

 * - Files with insecure extensions will be blocked by default even if they are

 *   listed. If .txt is an allowed extension such files will be renamed.

 *

 *   '#type' => 'file',

 *   '#title' => $this->t('Upload file'),

 *   '#upload_validators' => [

 *     'file_validate_extensions' => [

 *       'png gif jpg',

 *     'FileExtension' => [

 *        'extensions' => 'png gif jpg',

 *       ],

 *     ],

 *   ],

 * ];

 * @endcode

 * - Use file_save_upload() to trigger the FileUploadSanitizeNameEvent event and

 *   hook_file_validate().

 *   \Drupal\file\Validation\FileValidatorInterface::validate().

 *

 * Important considerations, regardless of the form element used:

 * - Always use and validate against a list of allowed extensions.

 *   recommended.

 *

 * @see https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html

 * @see \hook_file_validate()

 * @see \Drupal\file\Validation\FileValidatorInterface

 * @see file_save_upload()

 * @see \Drupal\Core\File\Event\FileUploadSanitizeNameEvent

 * @see \Drupal\system\EventSubscriber\SecurityFileUploadEventSubscriber

 *   An array of error messages. If there are no problems with the file return

 *   an empty array.

 *

 * @see file_validate()

 * @deprecated in drupal:10.2.0 and is removed from drupal:11.0.0. Use the

 *    'file.validator' service instead.

 *

 * @see https://www.drupal.org/node/3363700

 * @see \Drupal\file\Validation\FileValidatorInterface

 */

function hook_file_validate(\Drupal\file\FileInterface $file) {

  $errors = [];