Developer Hooks

• hook_convertfile_info()
• hook_convertfile_info_alter()
• hook_convertfile_pre_convert()
• hook_convertfile_post_convert()

hook_convertfile_info()

Declare a new provider and conversion formats. Provider and associated formats will be available as options when configuring file field instances, on the inline conversion form, and on the admin convert tab. Unless a callback is specified, new rules must be created to perform the actual conversion.

Example implementation uses a callback for documentation only. The actual imagemagick hook_convertfile_info() makes use of rules and therefore does not specify a callback function.

Example implementation:

/**
 * Implements hook_convertfile_info().
 *
 * Register our provider and formats with convertfile module.
 *
 * @see convertfile_collect_info()
 */
function cf_imagemagick_convertfile_info() {
  return array(
    // Preface array structure with module machine name.
    'cf_imagemagick' => array(
      // Human friendly name of provider.
      'name' => 'ImageMagick',
      // Extensions that this provider will convert to.
      'types' => array(
        'png' => '.png (image/png)',
        'jpg' => '.jpg (image/jpeg)',
      ),
      // Provider specific options callback (optional).
      'options' => 'cf_imagemagick_options',
      // Provider specific options submission formatter callback (optional).
      'exposed_options' => 'cf_imagemagick_options_exposed',
      // Friendly link for help with this provider (optional).
      'help' => array(
        'url' => 'https://github.com/delphian/drupal-convert-file/wiki/ImageMagick',
      ),
    ),
  );
}

hook_convertfile_info_alter()

Alter any registered providers.

Example implementation:

/**
 * Implements hook_convertfile_info_alter()
 *
 * Disable ImageMagick's ability to provide the format option of .png
 *
 * @param array $info
 *   The current provider registry. This value will be altered.
 */
function convertfile_convertfile_info_alter(&$info) {
  if (isset($info['imagemagick']['types']['png'])) {
    unset($info['imagemagick']['types']['png']);
  }
}

hook_convertfile_pre_convert()

Perform operations on the file before it is converted. As $file is an object it will retain any changes made to it. The pending conversion itself may be aborted by setting $file->convertfile['error'] to any value (an error message is suggested).

Example implementation:

/**
 * Implements hook_convertfile_pre_convert().
 *
 * For some strange undisclosed reason abort any conversion to pdf documents
 * before it happens.
 *
 * @param stdObject $file
 *   The file object on which to operate. We will be altering this value. Pass
 *   by reference operator is not required for objects.
 * @param array $instance
 *   The file field configuration instance associated with this file.
 *
 * @return void
 *   We return nothing.
 */
function convertfile_convertfile_pre_convert($file, $instance) {
  // Only for newly uploaded files via the 'upload' button.
  if (!isset($file->fid)) {
    $to_format = $instance['widget']['settings']['convertfile_ajax']['convertfile_format'];
    if ($to_format == 'pdf') {
      // Set an error message. The existance of an error message will bypass
      // any conversion. Error messages will also trip form validation.
      $file->convertfile['error'] = "Conversion to PDF not allowed!";
    }
  }
}

hook_convertfile_post_convert()

Operate on a file object (and its disk image) after a conversion has been performed. Do not save the file object, the calling function will do so. If $file-convertfile['error'] is set then the previously attempted file conversion failed, otherwise it succeeded.

Example implementation:

/**
 * Implements hook_convertfile_post_convert().
 *
 * I always want to gzip files that have been converted to pdf precisely
 * because it makes absolutely no sense to do so.
 *
 * @param stdObject $file
 *   The file object on which to operate. We will be altering this value. Pass
 *   by reference operator is not required for objects.
 * @param array $instance
 *   The file field configuration instance associated with this file.
 *
 * @return void
 *   We return nothing.
 */
function convertfile_convertfile_post_convert($file, $instance) {
  $success = FALSE;
  $to_format = $instance['widget']['settings']['convertfile_ajax']['convertfile_format'];

  if ($to_format == 'pdf') {
    if (($contents = file_get_contents($file->uri)) !== FALSE) {
      if ($fp = gzopen($file->uri, 'w9')) {
        if (gzwrite($fp, $contents)) {
          $file->filename = $file->filename . '.gz';
          $file->filesize = filesize($file->uri);
          $file->filemime = file_get_mimetype($file->filename);
          $file->destination = $file->destination . '.gz';
          $success = TRUE;
        }
        gzclose($fp);
      }
    }
    if (!$success) {
      $file->convertfile['error'] = "Can't gzip file!";
    }
  }
}