convertfile.module

<?php

/**
 * @file
 * Automatically convert uploaded or saved files to a different format.
 */

require_once('convertfile.db.conversion.inc');
require_once('convertfile.theme.inc');

/**
 * Implements of hook_menu().
 */
function convertfile_menu() {
  // Create a new category on the admin config page.
  $items['admin/config/convertfile'] = array(
    'title' => 'Convert File',
    'position' => 'left',
    'weight' => -20,
    'page callback' => 'system_admin_menu_block_page',
    'access arguments' => array('administer convertfile settings'),
    'file' => 'system.admin.inc',
    'file path' => drupal_get_path('module', 'system'),
  );
  // Provide a page to handle general settings and configuration.
  $items['admin/config/convertfile/settings'] = array(
    'title' => 'Settings',
    'description' => 'Configure Convert File options and settings.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('convertfile_config_form'),
    'access arguments' => array('administer convertfile settings'),
    'file' => 'convertfile.admin.inc',
    'file path' => drupal_get_path('module', 'convertfile'),
    'weight' => 10,
  );
  $items['admin/config/convertfile/settings/basic'] = array(
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'title' => 'Settings',
  );
  // Provide a page to handle watchdog error messages.
  $items['admin/config/convertfile/settings/watchdog'] = array(
    'type' => MENU_LOCAL_TASK,
    'title' => 'Logs',
    'description' => 'View debug and error messages.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('convertfile_watchdog_form'),
    'access arguments' => array('administer convertfile settings'),
    'file' => 'convertfile.admin.inc',
    'file path' => drupal_get_path('module', 'convertfile'),
    'weight' => 30,
  );
  // Provide a page to show all convertfile related rules.
  $items['admin/config/convertfile/settings/rules'] = array(
    'type' => MENU_LOCAL_TASK,
    'title' => 'Rules',
    'description' => 'View all active and inactive rules related to convertfile.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('convertfile_rules_form'),
    'access arguments' => array('administer convertfile settings'),
    'file' => 'convertfile.admin.inc',
    'file path' => drupal_get_path('module', 'convertfile'),
    'weight' => 20,
  );
  // Provide a page to show all convertfile related rules.
  $items['admin/config/convertfile/settings/convert'] = array(
    'type' => MENU_LOCAL_TASK,
    'title' => 'Convert',
    'description' => 'Manually convert a file through the administrative interface.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('convertfile_convert_form'),
    'access arguments' => array('administer convertfile settings'),
    'file' => 'convertfile.admin.inc',
    'file path' => drupal_get_path('module', 'convertfile'),
    'weight' => 25,
  );
  if (variable_get('convertfile_help', FALSE)) {
    // Redirect rules back to convertfile.
    $items['admin/config/workflow/rules/reaction/convertfile_back'] = array(
      'type' => MENU_LOCAL_ACTION,
      'title' => 'Back to Convert File',
      'page callback' => 'convertfile_redirect_convertfile_rules',
      'access arguments' => array('administer convertfile settings'),
      'file' => 'convertfile.admin.inc',
      'file path' => drupal_get_path('module', 'convertfile'),
      'weight' => 30,
    );
    // Redirect to drupal rules.
    $items['admin/config/convertfile/settings/rules/drupal_rules'] = array(
      'type' => MENU_LOCAL_ACTION,
      'title' => 'Rules',
      'page callback' => 'convertfile_redirect_drupal_rules',
      'access arguments' => array('administer convertfile settings'),
      'file' => 'convertfile.admin.inc',
      'file path' => drupal_get_path('module', 'convertfile'),
      'weight' => 25,
    );
    // Redirect to drupal rules add new rule.
    $items['admin/config/convertfile/settings/rules/drupal_add_new_rule'] = array(
      'type' => MENU_LOCAL_ACTION,
      'title' => 'Add new rule',
      'page callback' => 'convertfile_redirect_drupal_rules_new',
      'access arguments' => array('administer convertfile settings'),
      'file' => 'convertfile.admin.inc',
      'file path' => drupal_get_path('module', 'convertfile'),
      'weight' => 30,
    );
  }
  // Provide a page to display all installed providers and their 
  // configuration.
  $items['admin/config/convertfile/settings/provider'] = array(
    'type' => MENU_LOCAL_TASK,
    'title' => 'Providers',
    'description' => 'All installed file conversion providers.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('convertfile_provider_form'),
    'access arguments' => array('administer convertfile settings'),
    'file' => 'convertfile.admin.inc',
    'file path' => drupal_get_path('module', 'convertfile'),
    'weight' => 35,
  );
  $items['admin/config/convertfile/settings/provider/config'] = array(
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'title' => 'Config',
  );

  return $items;
}

/**
 * Redirect to convertfile rules from drupal rules.
 */
function convertfile_redirect_convertfile_rules() {
  drupal_goto('/admin/config/convertfile/settings/rules');
}

/**
 * Redirect to drupal rules from convertfile rules.
 */
function convertfile_redirect_drupal_rules() {
  drupal_goto('/admin/config/workflow/rules');
}

/**
 * Redirect to drupal new rule from convertfile rules.
 */
function convertfile_redirect_drupal_rules_new() {
  drupal_goto('/admin/config/workflow/rules/reaction/add');
}

/**
 * Implements hook_permission().
 *
 * Create permission to administer convertfile settings.
 * Create permission to download backup files in private file system.
 */
function convertfile_permission() {
  return array(
    'administer convertfile settings' => array(
      'title' => t('Administer Convert File settings'),
    ),
    'download private backup files' => array(
      'title' => t('Download private backup files'),
    ),
    'convertfile use inline conversion' => array(
      'title' => t('Use inline conversion form'),
    ),
  );
}

/**
 * Collates all information on conversion providers and supported extensions.
 *
 * The information may be altered with hook_convertfile_info_alter()
 *
 * @param bool $reset
 *   Bypass all static variables and caching
 *
 * @return array
 *   An assocative array keyed by provider name. Each sub-array contains:
 *   - 'name': (string) Name of the provider.
 *   - 'callback': (string) Name of the callback function.
 *   - 'types': (array) Associative array keyed by file extension that can be
 *     converted to. Value will be the displayed name.
 */
function convertfile_collect_info($reset = FALSE) {
  static $info;

  if (!isset($info) || $reset) {
    if (!$reset && ($cached = cache_get('convertfile_providers', 'cache'))) {
      $info = $cached;
    }
    else {
      $info = module_invoke_all('convertfile_info');
      drupal_alter('convertfile_info', $info);
    }
  }

  return $info;
}

/**
 * Implements hook_field_widget_info().
 *
 * Create two new widgets, one for files, the other for images. The main
 * purpose of the widget is to alter the field validator to which it is
 * attached and to contain information concerning which type of conversion
 * to execute.
 */
function convertfile_field_widget_info() {
  return array(
    'convertfile_file' => array(
      'label' => t('Convert File'),
      'field types' => array('file'),
      'settings' => array(
        'progress_indicator' => 'throbber',
      ),
      'behaviors' => array(
        'multiple values' => FIELD_BEHAVIOR_CUSTOM,
        'default value' => FIELD_BEHAVIOR_NONE,
      ),
    ),
    'convertfile_image' => array(
      'label' => t('Convert Image'),
      'field types' => array('image'),
      'settings' => array(
        'progress_indicator' => 'throbber',
        'preview_image_style' => 'thumbnail',
      ),
      'behaviors' => array(
        'multiple values' => FIELD_BEHAVIOR_CUSTOM,
        'default value' => FIELD_BEHAVIOR_NONE,
      ),
    ),
  );
}

/**
 * Implements hook_element_info().
 *
 * Create convertfile_file element type for form api use. Now forms
 * constructed by hand can also auto convert files.
 */
function convertfile_element_info() {
  $file_path = drupal_get_path('module', 'file');
  $types['convertfile_file'] = array(
    '#input' => TRUE,
    '#process' => array('file_managed_file_process'),
    '#value_callback' => 'convertfile_managed_file_value',
    '#element_validate' => array('file_managed_file_validate'),
    '#pre_render' => array('file_managed_file_pre_render'),
    '#theme' => 'file_managed_file',
    '#theme_wrappers' => array('form_element'),
    '#progress_indicator' => 'throbber',
    '#progress_message' => NULL,
    '#upload_validators' => array(),
    '#upload_location' => NULL,
    '#size' => 22,
    '#extended' => FALSE,
    '#attached' => array(
      'css' => array($file_path . '/file.css'),
      'js' => array($file_path . '/file.js'),
    ),
  );

  return $types;
}

/**
 * Implements hook_element_info_alter().
 *
 * Attatch an extra process callback to managed_file element types for the
 * purpose of adding new buttons and options.
 */
function convertfile_element_info_alter(&$type) {
  $type['managed_file']['#process'][] = 'convertfile_managed_file_process';
}

/**
 * Element process function to expand a file like element with extra features.
 *
 * Create a revert button to restore older version of file. Create convert
 * options and buttons to convert current file to a new format.
 *
 * @see convertfile_element_info_alter()
 * @see file_managed_file_process()
 * @see http://stackoverflow.com/questions/6520775/why-is-the-the-triggering-element-in-form-state-is-the-last-button-on-the-for#6521617
 */
function convertfile_managed_file_process($element, &$form_state, $form) {
  global $user;
  $provider = isset($element['#value']['convertfile_provider']) ?
    $element['#value']['convertfile_provider'] : NULL;
  $fid = isset($element['fid']['#value']) ? $element['fid']['#value'] : NULL;

  // If this element does not contain an active file don't display any
  // features.
  if ($fid) {
    // Add inline revert buttons to this element.
    if (variable_set('convertfile_inline_revert', FALSE)) {
      if ($backups = convertfile_db_conversion_get_backups($fid)) {
        foreach($backups as $backup) {
          $file = file_load($backup);
          $element['convertfile_list_backup_' . $backup] = array(
            '#type' => 'submit',
            '#value' => t('Revert to') . ' ' . $file->filename,
            '#weight' => 18,
            '#submit' => array(
              'convertfile_managed_file_process_remove_submit',
            ),
          );
        }
      }
    }

    if (preg_match('/.*([0-9]+)$/', $element['#id'], $matches)) {
      $delta = $matches[0];
    }

    // Add inline convert options.
    $permission = 'convertfile use inline conversion';
    if (variable_get('convertfile_inline_convert', FALSE) && user_access($permission, $user)) {
      $element['convertfile_provider'] = array(
        '#type' => 'select',
        '#title' => t('Provider'),
        '#options' => convertfile_options_provider(),
        '#weight' => 22,
        '#attached' => array(
          'css' => array(drupal_get_path('module', 'convertfile') . '/css/convertfile.css'),
        ),
        '#ajax' => array(
          'callback' => 'convertfile_managed_file_process_ajax',
          'wrapper' => 'convertfile-format-div',
          'method' => 'replace',
          'effect' => 'fade',
        ),
        '#prefix' => '<div class="convertfile-inline-convert">',
      );
      $element['convertfile_format'] = array(
        '#type' => 'select',
        '#title' => 'Format',
        '#options' => convertfile_options_format($provider),
        '#prefix' => '<div id="convertfile-format-div">',
        '#suffix' => '</div>',
        '#weight' => 24,
      );
      // See url reference in funtion comment concerning '#name' value.
      // In function callback the wrong (last) delta will be present inside
      // '#array_parents' unless each name is unique.
      $element['convertfile_submit'] = array(
        '#type' => 'submit',
        '#default_value' => t('Convert'),
        '#name' => $element['#id'],
        '#weight' => 26,
        '#submit' => array(
          'convertfile_managed_file_process_inline_submit',
        ),
        '#prefix' => '<div class="submit">',
        '#suffix' => '</div></div>',
      );
    }
  }

  return $element;
}

/**
 * AJAX callback to select available formats based on provider.
 *
 * @see convertfile_managed_file_process()
 */
function convertfile_managed_file_process_ajax($form, &$form_state) {
  $element = NULL;
  if (isset($form_state['triggering_element']['#array_parents'])) {
    $element = $form;
    foreach ($form_state['triggering_element']['#array_parents'] as $match) {
      if (strval($match) != 'convertfile_provider') {
        $element = $element[$match];
      }
    }
  }

  return $element['convertfile_format'];
}

/**
 * Form submission handler for revert button of managed_file elements.
 *
 * @see convertfile_managed_file_process().
 * @see file_managed_file_submit().
 */
function convertfile_managed_file_process_remove_submit($form, &$form_state) {
  drupal_set_message('Revert feature not implemented yet', 'warning');
}

/**
 * Form submission handler for converted a file which is already in an
 * managed_file element.
 *
 * @see convertfile_managed_file_process().
 * @see file_managed_file_submit().
 */
function convertfile_managed_file_process_inline_submit($form, &$form_state) {
  $element = NULL;
  if (isset($form_state['triggering_element']['#array_parents'])) {
    $element = $form_state['values'];
    foreach ($form_state['triggering_element']['#array_parents'] as $match) {
      if (strval($match) != 'convertfile_submit') {
        $element = $element[$match];
      }
    }
  }

  $file = file_load($element['fid']);
  $provider = $element['convertfile_provider'];
  $format = $element['convertfile_format'];

  if (convertfile_convert_file($file, $provider, $format, NULL)) {
    drupal_set_message('File has been converted.', 'status');
  }
  else {
    drupal_set_message('File could not be converted.', 'warning');
  }
}

/**
 * The #value_callback for a convertfile_file type element.
 */
function convertfile_managed_file_value(&$element, $input = FALSE, $form_state = NULL) {
  // Insert our pseudo field instance parameter.
  $instance = array(
    'widget' => array(
      'settings' => array(
        'convertfile_provider' => $element['#convertfile_provider'],
        'convertfile_format' => $element['#convertfile_format'],
      ),
    ),
  );
  $element['#upload_validators']['convertfile_validate_conversion'] = array($instance);

  return file_managed_file_value($element, $input, $form_state);
}

/**
 * Implements hook_field_widget_settings_form().
 *
 * Add extra configuration options when editing any fields that use
 * convertfile widgets.
 *
 * @todo fix the dirty little hack!
 */
function convertfile_field_widget_settings_form($field, $instance) {
  $widget = $instance['widget'];
  $settings = $widget['settings'];
  $provider = isset($settings['convertfile_provider']) ? $settings['convertfile_provider'] : NULL;

  if ($field['type'] == 'file') {
    $form['progress_indicator'] = array(
      '#type' => 'radios',
      '#title' => t('Progress indicator'),
      '#options' => array(
        'throbber' => t('Throbber'),
        'bar' => t('Bar with progress meter'),
      ),
      '#default_value' => $settings['progress_indicator'],
      '#description' => t('The throbber display does not show the status of uploads but takes up less space. The progress bar is helpful for monitoring progress on large uploads.'),
      '#weight' => 16,
      '#access' => file_progress_implementation(),
    );
  }
  if ($field['type'] == 'image') {
    // Use the file widget settings form.
    $form = file_field_widget_settings_form($field, $instance);
    $form['preview_image_style'] = array(
      '#title' => t('Preview image style'),
      '#type' => 'select',
      '#options' => image_style_options(FALSE),
      '#empty_option' => '<' . t('no preview') . '>',
      '#default_value' => $settings['preview_image_style'],
      '#description' => t('The preview image will be shown while editing the content.'),
      '#weight' => 15,
    );
  }

  $options = convertfile_options_provider();

  // Add our common custom settings
  $form['convertfile_provider'] = array(
    '#title' => t('Convert using provider'),
    '#type' => 'select',
    '#options' => $options,
    '#default_value' => $provider ? $provider : 'none',
    '#description' => t('The provider used to convert this file.'),
    '#ajax' => array(
      'callback' => 'convertfile_field_widget_settings_form_ajax',
      'wrapper' => 'convertfile-ajax',
      'method' => 'replace',
      'effect' => 'fade',
    ),
    '#weight' => 20,
  );

  // Dirty little hack. Pass the instance information to form_alter().
  $_SESSION['convertfile_instance'] = $instance;

  return $form;
}

/**
 * Implements hook_form_FORM_ID_alter().
 *
 * Place any ajax dependent render arrays here instead of the
 * widget_settings_form. hook_widget_settings_form does not have access to the
 * form_state, the examination of which is required for providing the correct
 * form construction during an ajax callback.
 *
 * @see convertfile_field_widget_settings_form()
 */
function convertfile_form_field_ui_field_edit_form_alter(&$form, &$form_state) {
  $instance = isset($_SESSION['convertfile_instance']) ? $_SESSION['convertfile_instance'] : NULL;

  $settings = isset($instance['widget']['settings']) ? $instance['widget']['settings'] : NULL;
  $provider = isset($settings['convertfile_provider']) ? $settings['convertfile_provider'] : NULL;
  $format = isset($settings['convertfile_ajax']['convertfile_format']) ? $settings['convertfile_ajax']['convertfile_format'] : NULL;
  $specific = isset($settings['convertfile_ajax']['convertfile_specific']) ? $settings['convertfile_ajax']['convertfile_specific'] : NULL;

  $values = isset($form_state['values']['instance']['widget']['settings']) ? 
    $form_state['values']['instance']['widget']['settings'] : NULL;
  $provider = isset($values['convertfile_provider']) ? $values['convertfile_provider'] : $provider;
  $format = isset($values['convertfile_format']) ? $values['convertfile_format'] : $format;

  $form['instance']['widget']['settings']['convertfile_ajax'] = array(
    '#type' => 'markup',
    '#prefix' => '<div id="convertfile-ajax">',
    '#suffix' => '</div>',
    '#weight' => 22,
  );
  $form['instance']['widget']['settings']['convertfile_ajax']['convertfile_format'] = array(
    '#title' => t('Convert to format'),
    '#type' => 'select',
    '#description' => 'The file format that will be converted to.',
    '#options' => convertfile_options_format($provider),
    '#default_value' => isset($format) ? $format : 'none',
  );
  $form['instance']['widget']['settings']['convertfile_ajax']['convertfile_specific'] = convertfile_options_specific($provider, $format, $specific);

}

/**
 * AJAX callback.
 *
 * @see convertfile_form_field_ui_field_edit_form_alter()
 */
function convertfile_field_widget_settings_form_ajax($form, &$form_state) {
  return $form['instance']['widget']['settings']['convertfile_ajax'];
}

/**
 * Implements hook_field_widget_form().
 *
 * Insert a custom validator for any fields managed by our widget.
 *
 * The validator will be responsible for doing the file conversion.
 */
function convertfile_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) {
  $element['#upload_validators']['convertfile_validate_conversion'] = array($instance);
  $element['#upload_validators']['file_validate_extensions'][] = $instance['settings']['file_extensions'];

  if ($field['type'] == 'file') {
    $elements = file_field_widget_form($form, $form_state, $field, $instance, $langcode, $items, $delta, $element);
  }
  if ($field['type'] == 'image') {
    $elements = image_field_widget_form($form, $form_state, $field, $instance, $langcode, $items, $delta, $element);
  }

  return $elements;
}

/**
 * Create associative array keyed by provider machine name and valued with
 * provider name.
 */
function convertfile_options_provider() {
  // Compile array of all file conversion providers.
  $options = array('none' => '- None -');
  if ($results = convertfile_collect_info()) {
    foreach($results as $key => $result) {
      $options[$key] = $result['name'];
    }
  }

  return $options;
}

/**
 * Create associative array keyed by format machine name and valued with
 * format name.
 */
function convertfile_options_format($provider_mn = NULL) {
  // Compile array of all file conversion format.
  $options = array('none' => '- None -');
  if ($results = convertfile_collect_info()) {
    foreach($results as $key => $provider) {
      if (!$provider || ($key == $provider_mn)) {
        foreach($provider['types'] as $format_mn => $format_name) {
          $options[$format_mn] = $format_name;
        }
      }
    }
  }

  return $options;
}

/**
 * Get provider/format specific options for field instance configuration.
 *
 * Executes the provider specific callback function to gather a render array
 * which will be inserted in structure field configuration forms that use
 * the convertfile widget.
 *
 * @param string $provider
 *   The machine name of the requested conversion provider.
 * @param string $format
 *   The machine name of the requested conversion format.
 * @param array $specific
 *   (optional) Any existing form data containing specific configuration settings.
 *
 * @return array|bool
 *   A render array or FALSE if no provider callback was found.
 *
 * @see convertfile_form_field_ui_field_edit_form_alter()
 */
function convertfile_options_specific($provider, $format, $specific = NULL) {
  $options = NULL;

  $info = convertfile_collect_info();
  if ($callback = isset($info[$provider]['options']) ? $info[$provider]['options'] : NULL) {
    if (function_exists($callback)) {
      // Execute provider callback specified in info hook.
      $options = $callback($format, $specific);
    }
    else {
      watchdog('convertfile', "Provider specific options callback not found: {$callback}", NULL, WATCHDOG_ERROR);
    }
  }
  else {
    // No callback is registered. This is not an error.
    $options = array();
  }

  return $options;
}

/**
 * Transform exposed instance submission back to field instance like structure.
 *
 * If the results of cf_imagemagick_options() ever become exposed to a normal
 * user form, and then submitted, what is returned is a flattened array. The
 * managing submit handler for this user exposed form must transform the
 * provider specific configuration variables back into an instance like array
 * before calling the programmatic convert function. The programmatic convert
 * function runs everything through rules, passing an instance as one of the
 * variables.
 *
 * @param string $provider
 *   Machine name of the requested conversion provider.
 * @param array $form
 *   Form that the options have been exposed on.
 * @param array &$form_state
 *   Current values submitted by the form.
 * @param string $format
 *   (optional) Machine name of requested conversion format.
 *
 * @return array|bool
 *   An array formatted exactly as convertfile_options_specific is. or NULL on
 *   error.
 */
function convertfile_options_exposed($provider, $form, &$form_state, $format = NULL) {
  $options = NULL;

  $info = convertfile_collect_info();
  if ($callback = isset($info[$provider]['exposed_options']) ? $info[$provider]['exposed_options'] : NULL) {
    if (function_exists($callback)) {
      // Execute provider callback specified in info hook.
      $options = $callback($form, $form_state, $format);
    }
    else {
      watchdog('convertfile', "Provider specific exposed options callback not found: {$callback}", NULL, WATCHDOG_ERROR);
    }
  }
  else {
    // No callback is registered. This is not an error.
    $options = array();
  }

  return $options;
}

/**
 * Programmatic wrapper for convertfile_validate_conversion().
 *
 * Call this function directly to perform a programmatically based conversion.
 * Rules, and even most programmatic functions, expect file conversion to be
 * initiated by an upload to a file field that has an instance configuration,
 * therefore this configuration must be mocked up if it does not really exist.
 *
 * @param int|stdClass $file
 *   The FID or file object to convert. This object may be modified.
 * @param string $provider
 *   The machine name of the provider.
 * @param string $format
 *   The machine name of the format to convert to.
 * @param array $specific
 *   The exact construction of options is dependent on the provider.
 *
 * @return bool
 *   TRUE on successful conversion, FALSE otherwise. See watchdog for error
 *   details.
 */
function convertfile_convert_file($file, $provider, $format, $extensions = NULL, $specific = NULL) {
  $report = FALSE;

  $file = (is_object($file)) ? $file : file_load($file);
  if ($file) {
    $instance = array(
      'widget' => array(
        'settings' => array(
          'convertfile_provider' => $provider,
          'convertfile_extensions' => $extensions,
          'convertfile_ajax' => array(
            'convertfile_format' => $format,
            'convertfile_specific' => $specific,
          ),
        ),
      ),
    );

    $result = convertfile_validate_conversion($file, $instance);
    if (is_array($result) && empty($result)) {
      $report = TRUE;
    }
  }

  return $report;
}

/**
 * Validator. Will call any registered providers.
 *
 * This is the main function to call when converting a file. In the event of
 * an error the provider should write an error message to
 * $file->convertfile['error'].
 *
 * @param stdClass $file
 *   File object that is being readied to be moved from temporary server
 *   upload bin.
 * @param array $instance
 *   Field instance that this file was submitted to.
 *
 * @return array
 *   An empty array on success. Contains at least one element of error message
 *   on failure. This error message will be displayed by drupal_set_message as
 *   this entire function is a validator.
 *
 * @see convertfile_field_widget_form()
 */
function convertfile_validate_conversion($file, $instance) {
  $report = array();
  $settings = $instance['widget']['settings'];

  // Save original information for any checks done after conversion is over.
  $file_orig = clone $file;

  $info = convertfile_collect_info();
  // If no provider is provided (I.E. None or isset == false), treat the file
  // as a normal upload. Else, actually invoke rules.
  if (isset($info[$settings['convertfile_provider']]['name'])) {
    $name = $info[$settings['convertfile_provider']]['name'];
    $function = isset($info[$settings['convertfile_provider']]['callback']) ?
      $info[$settings['convertfile_provider']]['callback'] : NULL;

    // Save original file to $file->convertfile['backup'] with its own FID.
    $file = convertfile_backup_file($file, $instance);

    // Determine which file should be converted, the current or backup.
    $file_process = (variable_get('convertfile_to_backup', FALSE)) ? $file->convertfile['backup'] : $file;
    $file_process->convertfile['original'] = clone $file;
    $file_process->convertfile['instance'] = $instance;
    $file_process->convertfile['converted'] = TRUE;

    // Post conversion hook. Modules may modify file object or disk image.
    module_invoke_all('convertfile_pre_convert', $file_process, $instance);

    // Only convert if an error does not already exist on this object.
    if (!isset($file_process->convertfile['error'])) {
      // Execute the provider callback function if specified.
      if ($function && function_exists($function)) {
        if (!$function($file_process, $instance)) {
          $file_process->convertfile['error'] = "File conversion by {$name} callback failed.";
        }
      }
      // No provider callback function specified (good). Invoke rules.
      // Everything should be rules based.
      else {
        rules_invoke_event('convertfile_request', $file_process, $instance);
      }
    }

    // Post conversion hook. Modules may modify file object or disk image.
    module_invoke_all('convertfile_post_convert', $file_process);

    // Rename filename and relocate file on disk for new and existing files.
    convertfile_update_file($file_process);

  }
  else {
    if ($settings['convertfile_provider'] != "none") {
      $file_process->convertfile['error'] = "Unknown conversion provider: {$settings['convertfile_provider']}.";
    }
  }

  // Log the success or failure of a file conversion and invoke rules.
  convertfile_log_result($file_process, $file_process->convertfile['original'], $instance);

  // Wrap any file conversion error into an appropriate return value expected
  // from a file validator.
  if (isset($file_process->convertfile['error'])) {
    $report[] = $file_process->convertfile['error'];
    // If a conversion has failed then remove the backup file.
    file_delete($file->convertfile['backup']);
    unset($file->convertfile['backup']);
  }

  return $report;
}

/**
 * Log any conversion attempt to watchdog and invoke success or fail rules.
 *
 * @param stdClass $file
 *   The file object to examine result of conversion on.
 * @param stdClass $file_orig
 *   The original file object before anything was done.
 * @param array $instance
 *   Field instance that this file was submitted to. 
 */
function convertfile_log_result($file, $file_orig, $instance) {
  $settings = $instance['widget']['settings'];

  // Log failed file conversion.
  if (isset($file->convertfile['error'])) {
    watchdog('convertfile', "{$settings['convertfile_provider']} Failed to convert {$file_orig->filename}. {$file->convertfile['error']}", NULL, WATCHDOG_ERROR);
    rules_invoke_event('convertfile_failure', $file, $instance);
  }
  // Log successful file conversion.
  else {
    watchdog('convertfile', "{$settings['convertfile_provider']} Saved: {$file_orig->filename} To: {$file->filename} " . 
      "({$file->uri})", NULL, WATCHDOG_INFO);
    rules_invoke_event('convertfile_success', $file, $instance);
  }
}

/**
 * Update a file object's filename or location on the disk.
 *
 * After a conversion both the title of the file and its location on the disk
 * may have been altered. This new information needs to be checked and updated
 * in the database.
 *
 * @param stdObject $file
 *   The file object that possibly contains an updated uri or filename.
 *
 * @return bool
 *   returns TRUE on success, FALSE on failure. On failure the file object
 *   $file->convertfile['error'] will contain an error message.
 */
function convertfile_update_file($file) {
  $report = TRUE;

  // If file has a FID then it is not a new upload.
  if (isset($file->fid) && $file->fid) {
    // We must resave the file information. Because this is not a new upload
    // nobody else is going to resave this.
    file_save($file);
    $dir = drupal_dirname($file->uri);
    // "move" the file to record any changes to the filename on disk.
    if ($moved_file = file_move($file, $dir . $file->filename, FILE_EXISTS_RENAME)) {
      $file->uri = $moved_file->uri;
    }
    else {
      $file->convertfile['error'] = 'Unable to rename file.';
      $report = FALSE;
    }
  }
  // This is a new upload. Because the destination was messed with, make 
  // sure its still unique.
  else {
    $file->destination = file_destination($file->destination, FILE_EXISTS_RENAME);
  }

  return $report;
}

/**
 * Clone the file object and save clone as independant copy of original.
 *
 * If the file object argument already references an existing managed file
 * then a managed copy will be made, the resulting new file object being
 * assigned to $file->convertfile['backup']. If the file object contains a
 * file that has just been uploaded (has not yet been formally saved and has
 * no fid) then a copy of the object will be made, saved formally as a managed
 * file and also assigned to $file->convertfile['backup']. If the original
 * file object is already managed then the new backup will be associated to
 * the original, otherwise this will be left for a hook_insert to care for.
 *
 * @param stdClass $file
 *   Drupal file object or FID to create backup for.
 * @param array $instance
 *   The field instance that contains specific configuration for this file.
 *
 * @return stdClass|bool
 *   The file object or NULL on failure. On success the original file object
 *   will have the newly created and saved backup object, containing its own
 *   fid, assigned to $file->convertfile['backup'].
 */
function convertfile_backup_file($file, $instance) {
  $report = NULL;
  $file = (is_object($file)) ? $file : file_load($file);

  if (!isset($file->convertfile)) {
    $file->convertfile = array();
  }

  // If the file is already managed then make another managed copy.
  if (isset($file->fid)) {
    $dir = drupal_dirname($file->uri);
    $file->convertfile['backup'] = file_copy($file, $dir . $file->filename, FILE_EXISTS_RENAME);
    if (isset($file->convertfile['backup']->fid)) {
      $settings = $instance['widget']['settings'];
      $report = $file;
      // Track backup file against original.
      convertfile_db_convertion_insert($file->convertfile['backup']->fid, $file->fid, $file->uid, $settings['convertfile_provider'], $file->convertfile['backup']->filemime);
    }
  }
  // If the file has just been uploaded then we must save a new managed copy.
  // as the backup. This results in the non intuitive effect of assigning the
  // backup an FID that precedes the actual uploaded file's eventual FID.
  else {
    $original_file = clone $file;
    if (copy($original_file->uri, $original_file->destination)) {
      $original_file->uri = $original_file->destination;
      unset($original_file->destination);
      file_save($original_file);
      if (isset($original_file->fid)) {
        $file->convertfile['backup'] = $original_file;
        $report = $file;
      }
    }
  }

  return $report;
}

/**
 * Search out and find all fields that use our widgets.
 */
function convertfile_find_widgets($widget, $reset = FALSE) {
  if (!$reset && ($cache = cache_get('convertfile_find_widget_' . $widget, 'cache'))) {
    $data = $cache->data;
  }
  else {
    $data = array();
    $instances = field_info_instances();
    foreach($instances as $entity_key => $entity) {
      foreach($entity as $bundle_key => $bundle) {
        foreach($bundle as $field_key => $field) {
          $type = $field['widget']['type'];
          if ($type == $widget) {
            $data[] = "{$entity_key} : {$bundle_key} : {$field_key}";
          }
        }
      }
    }
    cache_set('convertfile_find_widgets', $data, 'cache');
  }

  return $data;
}

/**
 * Implements hook_help().
 */
function convertfile_help($path, $arg) {
  // If help is empty at end of function then NULL will be returned.
  $help = '';

  // Only return help text if configured to do so.
  if (variable_get('convertfile_help', FALSE)) {

    // Rules page.
    if ($path == 'admin/config/convertfile/settings/rules') {
      // Help text if rules_admin is not turned on.
      if (!module_exists('rules_admin')) {
        $help .= '<p><a href="/admin/modules">Rules UI</a> (rules_admin) ' . t('module must be enabled to edit or examine the details of rules.') . '</p>';
      }
    }

    // Settings page and all children.
    if (strpos($path, 'admin/config/convertfile/settings') !== FALSE) { 
      // Warn if no providers are enabled.
      $providers = convertfile_collect_info();
      if (empty($providers)) {
        $help .= '<p>' . t('You must have at least one conversion provider enabled for this module to do anything useful. Visit the <a href="/admin/modules">modules page</a> and enable a conversion provider.') . '</p>';
      }
      // Warn if no cURL is found.
      if (!function_exists('curl_version')) {
        $help .= '<p>' . t('cURL must first be installed as a PHP extension in order for this module to operate.') . '</p>';
      }
    }

    // Settings page only.
    if ($path == 'admin/config/convertfile/settings') {
      // Always reference the wiki.
      $help .= '<p><a href="https://github.com/delphian/drupal-convert-file/wiki">Consult the wiki pages for help or to submit issues</a>.</p>';
      // Help text if no widgets have been configured yet.
      $images = convertfile_find_widgets('convertfile_image');
      $files = convertfile_find_widgets('convertfile_file');
      if (empty($images) && empty($files)) {
        $help .= '<p>' . t('Edit a <a href="@convertfile">content type</a> and set a file or image field to use the new <u>Convert File</u> or <u>Convert Image</u> widgets. Include the converted format file extension in the accepted formats field.', array('@convertfile' => url('admin/structure/types'))) . '</p>';
      }
    }

    // Main module help for the convertfile module
    if ($path == 'admin/help#convertfile') {
      $help .= '<p>' . t('Convert File adds a new widget for file and image fields named <u>Convert File</u> and <u>Convert Image</u>. The settings for these widget operate exactly as the default except for providing extra configuration that allow for automatic conversion of the file submitted to the field. See <a href="@convertfile">Convert File Settings</a> for more information.', array('@convertfile' => url('admin/config/convertfile/settings'))) . '</p>';
    }
  }

  return (strlen($help)) ? $help : NULL;
}

/**
 * Implements hook_file_insert().
 *
 * Backups will always be saved first and enter into this hook. Ignore them as
 * there is no way to determine who the parent is.
 *
 * The purpose of this hook is to manage new uploads, and associate their
 * backup file. Association for existing files is handled in the conversion
 * function itself.
 */
function convertfile_file_insert($file) {
  // Conversion has run, and there is a backup.
  if (isset($file->convertfile['backup'])) {
    $settings = (isset($file->convertfile['converted'])) ? 
      $file->convertfile['instance']['widget']['settings'] :
      $file->convertfile['backup']->convertfile['instance']['widget']['settings'];
    // Make sure the convert function itself didn't already associate.
    if (!convertfile_db_conversion_is_backup($file->convertfile['backup']->fid)) {
      convertfile_db_convertion_insert($file->convertfile['backup']->fid, $file->fid, $file->uid, $settings['convertfile_provider'], $file->convertfile['backup']->filemime);
    }
  }
}

/**
 * Implements hook_file_update().
 *
 * Change the status of all backups to match current file status.
 */
function convertfile_file_update($file) {
  if (isset($file->fid)) {
    if ($fids = convertfile_db_conversion_get_backups($file->fid)) {
      foreach ($fids as $fid) {
        if ($bfile = file_load($fid)) {
          $bfile->status = $file->status;
          file_save($bfile);
        }
      }
    }
  }
}

/**
 * Implements hook_file_delete().
 *
 * Delete all the backups of a file when it is removed.
 *
 * @param stdObject $file
 *   Drupal file object.
 */
function convertfile_file_delete($file) {
  if (isset($file->fid)) {
    // Delete all the backups for this file if it is primary.
    if ($cids = convertfile_db_conversion_get_backups($file->fid)) {
      foreach ($cids as $cid => $fid) {
        if ($file = file_load($fid)) {
          file_delete($file);
          convertfile_db_conversion_delete($cid);
        }
      }
    }
  }
}

/**
 * Implements hook_field_formatter_info().
 *
 * Create a custom field formatter. This may be selected under the manage
 * display tab when editing an entity structure. View this field as a file
 * link, and links to all previous file backups as well.
 */
function convertfile_field_formatter_info() {
  return array(
    'convertfile_file_default' => array(
      'label' => t('Convert File Generic file'),
      'field types' => array('file'),
    ),
  );
}

/**
 * Implements hook_field_formatter_view().
 *
 * @see convertfile_field_formatter_info()
 */
function convertfile_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
  $element = NULL;

  if ($display['type'] == 'convertfile_file_default') {
    foreach ($items as $delta => $item) {
      $element[$delta] = array(
        '#theme' => 'convertfile_link',
        '#file' => (object) $item,
      );
    }
  }

  return $element;
}

/**
 * Implements hook_file_download().
 *
 * Allow the download is backup files even if they are in private directory.
 *
 * Will examine the database for files based on the uri. If the UID of the
 * file record matches global $user, or the user is admin, then the
 * download will be allowed.
 *
 * @param string $uri
 *   The file URI prefaced with the private: schema.
 *
 * @return mixed
 *   NULL if this module should not comment on this file. -1 If the file
 *   is restricted, or an associative array if permission is granted:
 *   - 'Content-Type': (string) The mime type of the file.
 */
function convertfile_file_download($uri) {
  global $user;
  $access = NULL;
  $permission = 'download private backup files';

  // Only act if private downloads are enabled.
  if (variable_get('convertfile_private_downloads', FALSE)) {
    $file = db_select('file_managed', 'f')
      ->fields('f')
      ->condition('f.uri', $uri)
      ->execute()
      ->fetchAssoc();

    if ($file && isset($file['uid'])) {
      // User must be owner of file, user 1, or have the permission assigned.
      if (($file['uid'] == $user->uid) || (user_access($permission, $user))) {
        $access = array('Content-Type' => file_get_mimetype($uri));
      }
    }
  }

  return $access;
}