file.module 34.1 KB
Newer Older
1
2
3
4
5
6
7
8
<?php
// $Id$

/**
 * @file
 * Defines a "managed_file" Form API field and a "file" field for Field module.
 */

9
10
11
// Load all Field module hooks for File.
require_once DRUPAL_ROOT . '/modules/file/file.field.inc';

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
/**
 * Implements hook_help().
 */
function file_help($path, $arg) {
  switch ($path) {
    case 'admin/help#file':
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('The File module defines a <em>File</em> field type for the Field module, which lets you manage and validate uploaded files attached to content on your site (see the <a href="@field-help">Field module help page</a> for more information about fields). For more information, see the online handbook entry for <a href="@file">File module</a>.', array('@field-help' => url('admin/help/field'), '@file' => 'http://drupal.org/handbook/modules/file')) . '</p>';
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t('Attaching files to content') . '</dt>';
      $output .= '<dd>' . t('The File module allows users to attach files to content (e.g., PDF files, spreadsheets, etc.), when a <em>File</em> field is added to a given content type using the <a href="@fieldui-help">Field UI module</a>. You can add validation options to your File field, such as specifying a maximum file size and allowed file extensions.', array('@fieldui-help' => url('admin/help/field_ui'))) . '</dd>';
      $output .= '<dt>' . t('Managing attachment display') . '</dt>';
      $output .= '<dd>' . t('When you attach a file to content, you can specify whether it is <em>listed</em> or not. Listed files are displayed automatically in a section at the bottom of your content; non-listed files are available for embedding in your content, but are not included in the list at the bottom.') . '</dd>';
      $output .= '<dt>' . t('Managing file locations') . '</dt>';
      $output .= '<dd>' . t("When you create a File field, you can specify a directory where the files will be stored, which can be within either the <em>public</em> or <em>private</em> files directory. Files in the public directory can be accessed directly through the web server; when public files are listed, direct links to the files are used, and anyone who knows a file's URL can download the file. Files in the private directory are not accessible directly through the web server; when private files are listed, the links are Drupal path requests. This adds to server load and download time, since Drupal must start up and resolve the path for each file download request, but allows for access restrictions.") . '</dd>';
      $output .= '</dl>';
      return $output;
  }
}

34
/**
35
 * Implements hook_menu().
36
37
38
39
40
41
 */
function file_menu() {
  $items = array();

  $items['file/ajax'] = array(
    'page callback' => 'file_ajax_upload',
42
    'delivery callback' => 'ajax_deliver',
43
44
45
46
47
    'access arguments' => array('access content'),
    'type' => MENU_CALLBACK,
  );
  $items['file/progress'] = array(
    'page callback' => 'file_ajax_progress',
48
    'delivery callback' => 'ajax_deliver',
49
50
51
52
53
54
55
56
    'access arguments' => array('access content'),
    'type' => MENU_CALLBACK,
  );

  return $items;
}

/**
57
 * Implements hook_element_info().
58
59
 *
 * The managed file element may be used independently anywhere in Drupal.
60
 */
61
function file_element_info() {
62
  $file_path = drupal_get_path('module', 'file');
63
  $types['managed_file'] = array(
64
65
66
67
68
69
70
71
72
73
74
    '#input' => TRUE,
    '#process' => array('file_managed_file_process'),
    '#value_callback' => 'file_managed_file_value',
    '#element_validate' => array('file_managed_file_validate'),
    '#theme' => 'file_managed_file',
    '#theme_wrappers' => array('form_element'),
    '#progress_indicator' => 'throbber',
    '#progress_message' => NULL,
    '#upload_validators' => array(),
    '#upload_location' => NULL,
    '#extended' => FALSE,
75
76
77
78
    '#attached' => array(
      'css' => array($file_path . '/file.css'),
      'js' => array($file_path . '/file.js'),
    ),
79
  );
80
  return $types;
81
82
83
}

/**
84
 * Implements hook_theme().
85
86
87
88
89
 */
function file_theme() {
  return array(
    // file.module.
    'file_link' => array(
90
      'variables' => array('file' => NULL),
91
92
    ),
    'file_icon' => array(
93
      'variables' => array('file' => NULL),
94
95
    ),
    'file_managed_file' => array(
96
      'render element' => 'element',
97
98
99
100
    ),

    // file.field.inc.
    'file_widget' => array(
101
      'render element' => 'element',
102
103
    ),
    'file_widget_multiple' => array(
104
      'render element' => 'element',
105
    ),
106
107
108
    'file_formatter_table' => array(
      'variables' => array('items' => NULL),
    ),
109
    'file_upload_help' => array(
110
      'variables' => array('description' => NULL, 'upload_validators' => NULL),
111
112
113
114
115
    ),
  );
}

/**
116
 * Implements hook_file_download().
117
118
119
 *
 * This function takes an extra parameter $field_type so that it may
 * be re-used by other File-like modules, such as Image.
120
 */
121
function file_file_download($uri, $field_type = 'file') {
122
123
124
125
126
127
128
129
130
131
132
133
  global $user;

  // Get the file record based on the URI. If not in the database just return.
  $files = file_load_multiple(array(), array('uri' => $uri));
  if (count($files)) {
    $file = reset($files);
  }
  else {
    return;
  }

  // Find out which (if any) file fields contain this file.
134
  $references = file_get_file_references($file, NULL, FIELD_LOAD_REVISION, $field_type);
135
136
137

  // TODO: Check field-level access if available here.

138
  $denied = $file->status ? NULL : FALSE;
139
140
141
  // Check access to content containing the file fields. If access is allowed
  // to any of this content, allow the download.
  foreach ($references as $field_name => $field_references) {
142
    foreach ($field_references as $entity_type => $type_references) {
143
144
145
146
147
      foreach ($type_references as $reference) {
        // If access is allowed to any object, immediately stop and grant
        // access. If access is denied, continue through in case another object
        // grants access.
        // TODO: Switch this to a universal access check mechanism if available.
148
        if ($entity_type == 'node' && ($node = node_load($reference->nid))) {
149
150
151
152
153
154
155
156
          if (node_access('view', $node)) {
            $denied = FALSE;
            break 3;
          }
          else {
            $denied = TRUE;
          }
        }
157
        if ($entity_type == 'user') {
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
          if (user_access('access user profiles') || $user->uid == $reference->uid) {
            $denied = FALSE;
            break 3;
          }
          else {
            $denied = TRUE;
          }
        }
      }
    }
  }

  // No access was denied or granted.
  if (!isset($denied)) {
    return;
  }
  // Access specifically denied and not granted elsewhere.
  elseif ($denied == TRUE) {
    return -1;
  }

  // Access is granted.
  $name = mime_header_encode($file->filename);
  $type = mime_header_encode($file->filemime);
  // Serve images, text, and flash content for display rather than download.
  $inline_types = variable_get('file_inline_types', array('^text/', '^image/', 'flash$'));
  $disposition = 'attachment';
  foreach ($inline_types as $inline_type) {
    // Exclamation marks are used as delimiters to avoid escaping slashes.
    if (preg_match('!' . $inline_type . '!', $file->filemime)) {
      $disposition = 'inline';
    }
  }

  return array(
    'Content-Type' => $type . '; name="' . $name . '"',
    'Content-Length' => $file->filesize,
    'Content-Disposition' => $disposition . '; filename="' . $name . '"',
    'Cache-Control' => 'private',
  );
}

/**
 * Menu callback; Shared AJAX callback for file uploads and deletions.
 *
 * This rebuilds the form element for a particular field item. As long as the
 * form processing is properly encapsulated in the widget element the form
 * should rebuild correctly using FAPI without the need for additional callbacks
 * or processing.
 */
function file_ajax_upload() {
  $form_parents = func_get_args();
  $form_build_id = (string) array_pop($form_parents);

  if (empty($_POST['form_build_id']) || $form_build_id != $_POST['form_build_id']) {
    // Invalid request.
    drupal_set_message(t('An unrecoverable error occurred. The uploaded file likely exceeded the maximum file size (@size) that this server supports.', array('@size' => format_size(file_upload_max_size()))), 'error');
    $commands = array();
    $commands[] = ajax_command_replace(NULL, theme('status_messages'));
217
    return array('#type' => 'ajax', '#commands' => $commands, '#header' => FALSE);
218
219
220
221
222
223
224
225
226
  }

  list($form, $form_state, $form_id, $form_build_id) = ajax_get_form();

  if (!$form) {
    // Invalid form_build_id.
    drupal_set_message(t('An unrecoverable error occurred. Use of this form has expired. Try reloading the page and submitting again.'), 'error');
    $commands = array();
    $commands[] = ajax_command_replace(NULL, theme('status_messages'));
227
    return array('#type' => 'ajax', '#commands' => $commands, '#header' => FALSE);
228
229
230
231
232
233
234
235
236
237
238
239
240
241
  }

  // Get the current element and count the number of files.
  $current_element = $form;
  foreach ($form_parents as $parent) {
    $current_element = $current_element[$parent];
  }
  $current_file_count = isset($current_element['#file_upload_delta']) ? $current_element['#file_upload_delta'] : 0;

  // Build, validate and if possible, submit the form.
  drupal_process_form($form_id, $form, $form_state);

  // This call recreates the form relying solely on the form_state that the
  // drupal_process_form() set up.
242
  $form = drupal_rebuild_form($form_id, $form_state, $form);
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263

  // Retrieve the element to be rendered.
  foreach ($form_parents as $parent) {
    $form = $form[$parent];
  }

  // Add the special AJAX class if a new file was added.
  if (isset($form['#file_upload_delta']) && $current_file_count < $form['#file_upload_delta']) {
    $form[$current_file_count]['#attributes']['class'][] = 'ajax-new-content';
  }
  // Otherwise just add the new content class on a placeholder.
  else {
    $form['#suffix'] .= '<span class="ajax-new-content"></span>';
  }

  $output = theme('status_messages') . drupal_render($form);
  $js = drupal_add_js();
  $settings = call_user_func_array('array_merge_recursive', $js['settings']['data']);

  $commands = array();
  $commands[] = ajax_command_replace(NULL, $output, $settings);
264
  return array('#type' => 'ajax', '#commands' => $commands, '#header' => FALSE);
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
}

/**
 * Menu callback for upload progress.
 *
 * @param $key
 *   The unique key for this upload process.
 */
function file_ajax_progress($key) {
  $progress = array(
    'message' => t('Starting upload...'),
    'percentage' => -1,
  );

  $implementation = file_progress_implementation();
  if ($implementation == 'uploadprogress') {
    $status = uploadprogress_get_info($key);
    if (isset($status['bytes_uploaded']) && !empty($status['bytes_total'])) {
      $progress['message'] = t('Uploading... (@current of @total)', array('@current' => format_size($status['bytes_uploaded']), '@total' => format_size($status['bytes_total'])));
      $progress['percentage'] = round(100 * $status['bytes_uploaded'] / $status['bytes_total']);
    }
  }
  elseif ($implementation == 'apc') {
    $status = apc_fetch('upload_' . $key);
    if (isset($status['current']) && !empty($status['total'])) {
      $progress['message'] = t('Uploading... (@current of @total)', array('@current' => format_size($status['current']), '@total' => format_size($status['total'])));
      $progress['percentage'] = round(100 * $status['current'] / $status['total']);
    }
  }

295
  drupal_json_output($progress);
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
}

/**
 * Determine the preferred upload progress implementation.
 *
 * @return
 *   A string indicating which upload progress system is available. Either "apc"
 *   or "uploadprogress". If neither are available, returns FALSE.
 */
function file_progress_implementation() {
  static $implementation;
  if (!isset($implementation)) {
    $implementation = FALSE;

    // We prefer the PECL extension uploadprogress because it supports multiple
    // simultaneous uploads. APC only supports one at a time.
    if (extension_loaded('uploadprogress')) {
      $implementation = 'uploadprogress';
    }
    elseif (extension_loaded('apc') && ini_get('apc.rfc1867')) {
      $implementation = 'apc';
    }
  }
  return $implementation;
}

/**
323
 * Implements hook_file_references().
324
325
 */
function file_file_references($file) {
326
  $count = file_get_file_reference_count($file, NULL, 'file');
327
328
329
330
  return $count ? array('file' => $count) : NULL;
}

/**
331
 * Implements hook_file_delete().
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
 */
function file_file_delete($file) {
  // TODO: Remove references to a file that is in-use.
}

/**
 * Process function to expand the managed_file element type.
 *
 * Expands the file type to include Upload and Remove buttons, as well as
 * support for a default value.
 */
function file_managed_file_process($element, &$form_state, $form) {
  $fid = isset($element['#value']['fid']) ? $element['#value']['fid'] : 0;

  // Set some default element properties.
  $element['#progress_indicator'] = empty($element['#progress_indicator']) ? 'none' : $element['#progress_indicator'];
  $element['#file'] = $fid ? file_load($fid) : FALSE;
  $element['#tree'] = TRUE;

  $ajax_settings = array(
    'path' => 'file/ajax/' . implode('/', $element['#parents']) . '/' . $form['form_build_id']['#value'],
    'wrapper' => $element['#id'] . '-ajax-wrapper',
    'method' => 'replace',
    'effect' => 'fade',
    'progress' => array(
      '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'] = array(
    '#name' => implode('_', $element['#parents']) . '_upload_button',
    '#type' => 'submit',
    '#value' => t('Upload'),
    '#validate' => array(),
    '#submit' => array('file_managed_file_submit'),
369
    '#limit_validation_errors' => array($element['#parents']),
370
371
372
373
374
375
376
377
378
379
380
381
382
    '#ajax' => $ajax_settings,
    '#weight' => -5,
  );

  $ajax_settings['progress']['type'] ? $ajax_settings['progress']['type'] == 'bar' : 'throbber';
  $ajax_settings['progress']['message'] = NULL;
  $ajax_settings['effect'] = 'none';
  $element['remove_button'] = array(
    '#name' => implode('_', $element['#parents']) . '_remove_button',
    '#type' => 'submit',
    '#value' => t('Remove'),
    '#validate' => array(),
    '#submit' => array('file_managed_file_submit'),
383
    '#limit_validation_errors' => array($element['#parents']),
384
385
386
387
    '#ajax' => $ajax_settings,
    '#weight' => -5,
  );

388
389
390
391
392
393
  // @todo It is not good to call these private functions. This should be
  //   refactored so that the file deletion happens during a submit handler,
  //   and form changes affected by that (such as toggling the upload and remove
  //   buttons) happens during the 2nd run of this function that is triggered by
  //   a form rebuild: http://drupal.org/node/736298.
  if (_form_button_was_clicked($element['remove_button'], $form_state) || _form_element_triggered_scripted_submission($element['remove_button'], $form_state)) {
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
    // If it's a temporary file we can safely remove it immediately, otherwise
    // it's up to the implementing module to clean up files that are in use.
    if ($element['#file'] && $element['#file']->status == 0) {
      file_delete($element['#file']);
    }
    $element['#file'] = FALSE;
    $fid = 0;
  }

  // Set access on the buttons.
  $element['upload_button']['#access'] = empty($fid);
  $element['remove_button']['#access'] = !empty($fid);

  $element['fid'] = array(
    '#type' => 'hidden',
    '#value' => $fid,
  );

  // Add progress bar support to the upload if possible.
  if ($element['#progress_indicator'] == 'bar' && $implementation = file_progress_implementation()) {
    $upload_progress_key = md5(mt_rand());

    if ($implementation == 'uploadprogress') {
      $element['UPLOAD_IDENTIFIER'] = array(
        '#type' => 'hidden',
        '#value' => $upload_progress_key,
        '#attributes' => array('class' => array('file-progress')),
      );
    }
    elseif ($implementation == 'apc') {
      $element['APC_UPLOAD_PROGRESS'] = array(
        '#type' => 'hidden',
        '#value' => $upload_progress_key,
        '#attributes' => array('class' => array('file-progress')),
      );
    }

    // Add the upload progress callback.
    $element['upload_button']['#ajax']['progress']['path'] = 'file/progress/' . $upload_progress_key;
  }

  // The file upload field itself.
  $element['upload'] = array(
    '#name' => 'files[' . implode('_', $element['#parents']) . ']',
    '#type' => 'file',
    '#size' => 22,
    '#access' => empty($fid),
    '#theme_wrappers' => array(),
    '#weight' => -10,
  );

  if ($fid && $element['#file']) {
    $element['filename'] = array(
      '#type' => 'markup',
448
      '#markup' => theme('file_link', array('file' => $element['#file'])) . ' ',
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
      '#weight' => -10,
    );
  }

  // The "accept" attribute is valid XHTML, but not enforced in browsers.
  // We use it for our own purposes in our JavaScript validation.
  if (isset($element['#upload_validators']['file_validate_extensions'][0])) {
    $element['upload']['#attributes']['accept'] = implode(',', array_filter(explode(' ', $element['#upload_validators']['file_validate_extensions'][0])));
  }

  // Prefix and suffix used for AJAX replacement.
  $element['#prefix'] = '<div id="' . $element['#id'] . '-ajax-wrapper">';
  $element['#suffix'] = '</div>';

  return $element;
}

/**
 * The #value_callback for a managed_file type element.
 */
function file_managed_file_value(&$element, $input = FALSE, $form_state = NULL) {
  $fid = 0;

  // Find the current value of this field from the form state.
  $form_state_fid = $form_state['values'];
  foreach ($element['#parents'] as $parent) {
    $form_state_fid = isset($form_state_fid[$parent]) ? $form_state_fid[$parent] : 0;
  }

  if ($element['#extended'] && isset($form_state_fid['fid'])) {
    $fid = $form_state_fid['fid'];
  }
  elseif (is_numeric($form_state_fid)) {
    $fid = $form_state_fid;
  }

  // Process any input and save new uploads.
  if ($input !== FALSE) {
    $return = $input;

    // Uploads take priority over all other values.
    if ($file = file_managed_file_save_upload($element)) {
      $fid = $file->fid;
    }
    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);
        }
      }
      // Load file if the FID has changed to confirm it exists.
      if (isset($input['fid']) && $file = file_load($input['fid'])) {
        $fid = $file->fid;
      }
    }
  }

  // If there is no input, set the default value.
  else {
    if ($element['#extended']) {
      $default_fid = isset($element['#default_value']['fid']) ? $element['#default_value']['fid'] : 0;
      $return = isset($element['#default_value']) ? $element['#default_value'] : array('fid' => 0);
    }
    else {
      $default_fid = isset($element['#default_value']) ? $element['#default_value'] : 0;
      $return = array('fid' => 0);
    }

    // Confirm that the file exists when used as a default value.
    if ($default_fid && $file = file_load($default_fid)) {
      $fid = $file->fid;
    }
  }

  $return['fid'] = $fid;

  return $return;
}

/**
 * An #element_validate callback for the managed_file element.
 */
function file_managed_file_validate(&$element, &$form_state) {
  // 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.
  $clicked_button = end($form_state['clicked_button']['#parents']);
  if ($clicked_button != 'remove_button' && !empty($element['fid']['#value'])) {
    if ($file = file_load($element['fid']['#value'])) {
      if ($file->status == FILE_STATUS_PERMANENT) {
        $reference_count = 0;
        foreach (module_invoke_all('file_references', $file) as $module => $references) {
          $reference_count += $references;
        }
        if ($reference_count == 0) {
          form_error($element, t('Referencing to the file used in the !name field is not allowed.', array('!name' => $element['#title'])));
        }
      }
    }
    else {
      form_error($element, t('The file referenced by the !name field does not exist.', array('!name' => $element['#title'])));
    }
  }

  // Check required property based on the FID.
  if ($element['#required'] && empty($element['fid']['#value']) && !in_array($clicked_button, array('upload_button', 'remove_button'))) {
    form_error($element['upload'], t('!name field is required.', array('!name' => $element['#title'])));
  }

  // Consolidate the array value of this field to a single FID.
  if (!$element['#extended']) {
    form_set_value($element, $element['fid']['#value'], $form_state);
  }
}

/**
 * Submit handler for non-JavaScript uploads.
 */
function file_managed_file_submit($form, &$form_state) {
  // Do not redirect and leave the page after uploading a file. This keeps
  // all the current form values in place. The file is saved by the
  // #value_callback on the form element.
  $form_state['redirect'] = FALSE;
}

/**
 * Given a managed_file element, save any files that have been uploaded into it.
 *
 * @param $element
 *   The FAPI element whose values are being saved.
 * @return
 *   The file object representing the file that was saved, or FALSE if no file
 *   was saved.
 */
function file_managed_file_save_upload($element) {
  $upload_name = implode('_', $element['#parents']);
  if (empty($_FILES['files']['name'][$upload_name])) {
    return FALSE;
  }

  $destination = isset($element['#upload_location']) ? $element['#upload_location'] : NULL;
  if (isset($destination) && !file_prepare_directory($destination, FILE_CREATE_DIRECTORY)) {
    watchdog('file', 'The upload directory %directory for the file field !name could not be created or is not accessible. A newly uploaded file could not be saved in this directory as a consequence, and the upload was canceled.', array('%directory' => $destination, '!name' => $element['#field_name']));
    form_set_error($upload_name, t('The file could not be uploaded.'));
    return FALSE;
  }

  if (!$file = file_save_upload($upload_name, $element['#upload_validators'], $destination)) {
    watchdog('file', 'The file upload failed. %upload', array('%upload' => $upload_name));
    form_set_error($upload_name, t('The file in the !name field was unable to be uploaded.', array('!name' => $element['#title'])));
    return FALSE;
  }

  return $file;
}

/**
 * Theme a managed file element.
 */
612
613
614
function theme_file_managed_file($variables) {
  $element = $variables['element'];

615
616
617
618
619
620
621
622
623
624
625
  // This wrapper is required to apply JS behaviors and CSS styling.
  $output = '';
  $output .= '<div class="form-managed-file">';
  $output .= drupal_render_children($element);
  $output .= '</div>';
  return $output;
}

/**
 * Output a link to a file.
 *
626
627
628
 * @param $variables
 *   An associative array containing:
 *   - file: A file object to which the link will be created.
629
 */
630
631
632
function theme_file_link($variables) {
  $file = $variables['file'];

633
  $url = file_create_url($file->uri);
634
  $icon = theme('file_icon', array('file' => $file));
635
636
637
638
639
640
641
642
643
644

  // Set options as per anchor format described at
  // http://microformats.org/wiki/file-format-examples
  $options = array(
    'attributes' => array(
      'type' => $file->filemime . '; length=' . $file->filesize,
    ),
  );

  // Use the description as the link text if available.
645
  if (empty($file->description)) {
646
647
648
    $link_text = check_plain($file->filename);
  }
  else {
649
    $link_text = check_plain($file->description);
650
651
652
653
654
655
656
657
658
    $options['attributes']['title'] = check_plain($file->filename);
  }

  return '<span class="file">' . $icon . ' ' . l($link_text, $url, $options) . '</span>';
}

/**
 * Return an image with an appropriate icon for the given file.
 *
659
660
661
 * @param $variables
 *   An associative array containing:
 *   - file: A file object for which to make an icon.
662
 */
663
664
665
function theme_file_icon($variables) {
  $file = $variables['file'];

666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
  $mime = check_plain($file->filemime);
  $icon_url = file_icon_url($file);
  return '<img class="file-icon" alt="" title="' . $mime . '" src="' . $icon_url . '" />';
}

/**
 * Given a file object, create a URL to a matching icon.
 *
 * @param $file
 *   A file object.
 * @param $icon_directory
 *   (optional) A path to a directory of icons to be used for files. Defaults to
 *   the value of the "file_icon_directory" variable.
 * @return
 *   A URL string to the icon, or FALSE if an appropriate icon cannot be found.
 */
function file_icon_url($file, $icon_directory = NULL) {
  if ($icon_path = file_icon_path($file, $icon_directory)) {
    return base_path() . $icon_path;
  }
  return FALSE;
}

/**
 * Given a file object, create a path to a matching icon.
 *
 * @param $file
 *   A file object.
 * @param $icon_directory
 *   (optional) A path to a directory of icons to be used for files. Defaults to
 *   the value of the "file_icon_directory" variable.
 * @return
 *   A string to the icon as a local path, or FALSE if an appropriate icon could
 *   not be found.
 */
function file_icon_path($file, $icon_directory = NULL) {
  // Use the default set of icons if none specified.
  if (!isset($icon_directory)) {
    $icon_directory = variable_get('file_icon_directory', drupal_get_path('module', 'file') . '/icons');
  }

  // If there's an icon matching the exact mimetype, go for it.
  $dashed_mime = strtr($file->filemime, array('/' => '-'));
  $icon_path = $icon_directory . '/' . $dashed_mime . '.png';
  if (file_exists($icon_path)) {
    return $icon_path;
  }

  // For a few mimetypes, we can "manually" map to a generic icon.
  $generic_mime = (string) file_icon_map($file);
  $icon_path = $icon_directory . '/' . $generic_mime . '.png';
  if ($generic_mime && file_exists($icon_path)) {
    return $icon_path;
  }

  // Use generic icons for each category that provides such icons.
  foreach (array('audio', 'image', 'text', 'video') as $category) {
    if (strpos($file->filemime, $category . '/') === 0) {
      $icon_path = $icon_directory . '/' . $category . '-x-generic.png';
      if (file_exists($icon_path)) {
        return $icon_path;
      }
    }
  }

  // Try application-octet-stream as last fallback.
  $icon_path = $icon_directory . '/application-octet-stream.png';
  if (file_exists($icon_path)) {
    return $icon_path;
  }

  // No icon can be found.
  return FALSE;
}

/**
 * Determine the generic icon MIME package based on a file's MIME type.
 *
 * @param $file
 *   A file object.
 * @return
 *   The generic icon MIME package expected for this file.
 */
function file_icon_map($file) {
  switch ($file->filemime) {
    // Word document types.
    case 'application/msword':
    case 'application/vnd.ms-word.document.macroEnabled.12':
    case 'application/vnd.oasis.opendocument.text':
    case 'application/vnd.oasis.opendocument.text-template':
    case 'application/vnd.oasis.opendocument.text-master':
    case 'application/vnd.oasis.opendocument.text-web':
    case 'application/vnd.openxmlformats-officedocument.wordprocessingml.document':
    case 'application/vnd.stardivision.writer':
    case 'application/vnd.sun.xml.writer':
    case 'application/vnd.sun.xml.writer.template':
    case 'application/vnd.sun.xml.writer.global':
    case 'application/vnd.wordperfect':
    case 'application/x-abiword':
    case 'application/x-applix-word':
    case 'application/x-kword':
    case 'application/x-kword-crypt':
      return 'x-office-document';

    // Spreadsheet document types.
    case 'application/vnd.ms-excel':
    case 'application/vnd.ms-excel.sheet.macroEnabled.12':
    case 'application/vnd.oasis.opendocument.spreadsheet':
    case 'application/vnd.oasis.opendocument.spreadsheet-template':
    case 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':
    case 'application/vnd.stardivision.calc':
    case 'application/vnd.sun.xml.calc':
    case 'application/vnd.sun.xml.calc.template':
    case 'application/vnd.lotus-1-2-3':
    case 'application/x-applix-spreadsheet':
    case 'application/x-gnumeric':
    case 'application/x-kspread':
    case 'application/x-kspread-crypt':
      return 'x-office-spreadsheet';

    // Presentation document types.
    case 'application/vnd.ms-powerpoint':
    case 'application/vnd.ms-powerpoint.presentation.macroEnabled.12':
    case 'application/vnd.oasis.opendocument.presentation':
    case 'application/vnd.oasis.opendocument.presentation-template':
    case 'application/vnd.openxmlformats-officedocument.presentationml.presentation':
    case 'application/vnd.stardivision.impress':
    case 'application/vnd.sun.xml.impress':
    case 'application/vnd.sun.xml.impress.template':
    case 'application/x-kpresenter':
      return 'x-office-presentation';

    // Compressed archive types.
    case 'application/zip':
    case 'application/x-zip':
    case 'application/stuffit':
    case 'application/x-stuffit':
    case 'application/x-7z-compressed':
    case 'application/x-ace':
    case 'application/x-arj':
    case 'application/x-bzip':
    case 'application/x-bzip-compressed-tar':
    case 'application/x-compress':
    case 'application/x-compressed-tar':
    case 'application/x-cpio-compressed':
    case 'application/x-deb':
    case 'application/x-gzip':
    case 'application/x-java-archive':
    case 'application/x-lha':
    case 'application/x-lhz':
    case 'application/x-lzop':
    case 'application/x-rar':
    case 'application/x-rpm':
    case 'application/x-tzo':
    case 'application/x-tar':
    case 'application/x-tarz':
    case 'application/x-tgz':
      return 'package-x-generic';

    // Script file types.
    case 'application/ecmascript':
    case 'application/javascript':
    case 'application/mathematica':
    case 'application/vnd.mozilla.xul+xml':
    case 'application/x-asp':
    case 'application/x-awk':
    case 'application/x-cgi':
    case 'application/x-csh':
    case 'application/x-m4':
    case 'application/x-perl':
    case 'application/x-php':
    case 'application/x-ruby':
    case 'application/x-shellscript':
    case 'text/vnd.wap.wmlscript':
    case 'text/x-emacs-lisp':
    case 'text/x-haskell':
    case 'text/x-literate-haskell':
    case 'text/x-lua':
    case 'text/x-makefile':
    case 'text/x-matlab':
    case 'text/x-python':
    case 'text/x-sql':
    case 'text/x-tcl':
      return 'text-x-script';

    // HTML aliases.
    case 'application/xhtml+xml':
      return 'text-html';

    // Executable types.
    case 'application/x-macbinary':
    case 'application/x-ms-dos-executable':
    case 'application/x-pef-executable':
      return 'application-x-executable';

    default:
      return FALSE;
  }
}

/**
 * @defgroup file-module-api File module public API functions
 * @{
 * These functions may be used to determine if and where a file is in use.
 */

/**
873
 * Count the number of times the file is referenced.
874
875
876
877
 *
 * @param $file
 *   A file object.
 * @param $field
878
879
880
881
882
 *   (optional) A CCK field array or field name as a string. If provided,
 *   limits the reference check to the given field.
 * @param $field_type
 *   (optional) The name of a field type. If provided, limits the reference
 *   check to fields of the given type.
883
884
885
 * @return
 *   An integer value.
 */
886
function file_get_file_reference_count($file, $field = NULL, $field_type = NULL) {
887
888
889
890
891
892
893
894
895
896
897
898
  // Determine the collection of fields to check.
  if (isset($field)) {
    // Support $field as 'field name'.
    if (is_string($field)) {
      $field = field_info_field($field);
    }
    $fields = array($field['field_name'] => $field);
  }
  else {
    $fields = field_info_fields();
  }

899
  $types = entity_get_info();
900
901
902
  $reference_count = 0;

  foreach ($fields as $field) {
903
904
905
906
    if (empty($field_type) || $field['type'] == $field_type) {
      // TODO: Use a more efficient mechanism rather than actually retrieving
      // all the references themselves, such as using a COUNT() query.
      $references = file_get_file_references($file, $field, FIELD_LOAD_REVISION, $field_type);
907
      foreach ($references as $entity_type => $type_references) {
908
909
        $reference_count += count($type_references);
      }
910

911
912
913
914
915
      // If a field_name is present in the file object, the file is being deleted
      // from this field.
      if (isset($file->file_field_name) && $field['field_name'] == $file->file_field_name) {
        // If deleting the entire piece of content, decrement references.
        if (isset($file->file_field_type) && isset($file->file_field_id)) {
916
917
          if ($file->file_field_type == $entity_type) {
            $info = entity_get_info($entity_type);
918
            $id = $types[$entity_type]['entity keys']['id'];
919
920
921
922
            foreach ($type_references as $reference) {
              if ($file->file_field_id == $reference->$id) {
                $reference_count--;
              }
923
924
925
            }
          }
        }
926
927
928
929
        // Otherwise we're just deleting a single reference in this field.
        else {
          $reference_count--;
        }
930
931
932
933
934
935
936
937
938
      }
    }
  }

  return $reference_count;
}


/**
939
 * Get a list of references to a file.
940
941
942
943
 *
 * @param $file
 *   A file object.
 * @param $field
944
945
 *   (optional) A field array to be used for this check. If given, limits the
 *   reference check to the given field.
946
947
948
949
 * @param $age
 *   (optional) A constant that specifies which references to count. Use
 *   FIELD_LOAD_REVISION to retrieve all references within all revisions or
 *   FIELD_LOAD_CURRENT to retrieve references only in the current revisions.
950
951
952
 * @param $field_type
 *   Optional. The name of a field type. If given, limits the reference check to
 *   fields of the given type.
953
954
955
 * @return
 *   An integer value.
 */
956
function file_get_file_references($file, $field = NULL, $age = FIELD_LOAD_REVISION, $field_type = 'file') {
957
  $references = drupal_static(__FUNCTION__, array());
958
  $fields = isset($field) ? array($field['field_name'] => $field) : field_info_fields();
959
960

  foreach ($fields as $field_name => $file_field) {
961
    if ((empty($field_type) || $field['type'] == $field_type) && !isset($references[$field_name])) {
962
963
      // Get each time this file is used within a field.
      $cursor = 0;
964
      $references[$field_name] = field_attach_query($file_field['id'], array(array('fid', $file->fid)), array('limit' => FIELD_QUERY_NO_LIMIT, 'cursor' => &$cursor, 'age'=> $age));
965
966
967
968
969
970
971
972
973
    }
  }

  return isset($field) ? $references[$field['field_name']] : $references;
}

/**
 * @} End of "defgroup file-module-api".
 */