Merge pull request #10988 from jmcclelland/CRM-21194

[civicrm-core.git] / api / v3 / Attachment.php

<?php
/*
 +--------------------------------------------------------------------+
 | CiviCRM version 4.7                                                |
 +--------------------------------------------------------------------+
 | Copyright CiviCRM LLC (c) 2004-2017                                |
 +--------------------------------------------------------------------+
 | This file is a part of CiviCRM.                                    |
 |                                                                    |
 | CiviCRM is free software; you can copy, modify, and distribute it  |
 | under the terms of the GNU Affero General Public License           |
 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
 |                                                                    |
 | CiviCRM is distributed in the hope that it will be useful, but     |
 | WITHOUT ANY WARRANTY; without even the implied warranty of         |
 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
 | See the GNU Affero General Public License for more details.        |
 |                                                                    |
 | You should have received a copy of the GNU Affero General Public   |
 | License and the CiviCRM Licensing Exception along                  |
 | with this program; if not, contact CiviCRM LLC                     |
 | at info[AT]civicrm[DOT]org. If you have questions about the        |
 | GNU Affero General Public License or the licensing of CiviCRM,     |
 | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
 +--------------------------------------------------------------------+
 */

/**
 * "Attachment" is a pseudo-entity which represents a record in civicrm_file
 * combined with a record in civicrm_entity_file as well as the underlying
 * file content.
 * For core fields use "entity_table", for custom fields use "field_name"
 *
 * @code
 * // Create an attachment for a core field
 * $result = civicrm_api3('Attachment', 'create', array(
 *   'entity_table' => 'civicrm_activity',
 *   'entity_id' => 123,
 *   'name' => 'README.txt',
 *   'mime_type' => 'text/plain',
 *   'content' => 'Please to read the README',
 * ));
 * $attachment = $result['values'][$result['id']];
 * echo sprintf("<a href='%s'>View %s</a>", $attachment['url'], $attachment['name']);
 * @endcode
 *
 * @code
 * // Create an attachment for a custom file field
 * $result = civicrm_api3('Attachment', 'create', array(
 *   'field_name' => 'custom_6',
 *   'entity_id' => 123,
 *   'name' => 'README.txt',
 *   'mime_type' => 'text/plain',
 *   'content' => 'Please to read the README',
 * ));
 * $attachment = $result['values'][$result['id']];
 * echo sprintf("<a href='%s'>View %s</a>", $attachment['url'], $attachment['name']);
 * @endcode
 *
 * @code
 * // Move an existing file and save as an attachment
 * $result = civicrm_api3('Attachment', 'create', array(
 *   'entity_table' => 'civicrm_activity',
 *   'entity_id' => 123,
 *   'name' => 'README.txt',
 *   'mime_type' => 'text/plain',
 *   'options' => array(
 *      'move-file' => '/tmp/upload1a2b3c4d',
 *    ),
 * ));
 * $attachment = $result['values'][$result['id']];
 * echo sprintf("<a href='%s'>View %s</a>", $attachment['url'], $attachment['name']);
 * @endcode
 *
 * Notes:
 *  - File content is not returned by default. One must specify 'return => content'.
 *  - Features which deal with local file system (e.g. passing "options.move-file"
 *    or returning a "path") are only valid when executed as a local API (ie
 *    "check_permissions"==false)
 *
 * @package CiviCRM_APIv3
 */

/**
 * Adjust metadata for "create" action.
 *
 * @param array $spec
 *   List of fields.
 */
function _civicrm_api3_attachment_create_spec(&$spec) {
  $spec = array_merge($spec, _civicrm_api3_attachment_getfields());
  $spec['name']['api.required'] = 1;
  $spec['mime_type']['api.required'] = 1;
  $spec['entity_id']['api.required'] = 1;
  $spec['upload_date']['api.default'] = 'now';
}

/**
 * Create an Attachment.
 *
 * @param array $params
 *
 * @return array
 * @throws API_Exception validation errors
 * @see Civi\API\Subscriber\DynamicFKAuthorization
 */
function civicrm_api3_attachment_create($params) {
  if (empty($params['id'])) {
    // When creating we need either entity_table or field_name.
    civicrm_api3_verify_one_mandatory($params, NULL, array('entity_table', 'field_name'));
  }

  $config = CRM_Core_Config::singleton();
  list($id, $file, $entityFile, $name, $content, $moveFile, $isTrusted, $returnContent) = _civicrm_api3_attachment_parse_params($params);

  $fileDao = new CRM_Core_BAO_File();
  $entityFileDao = new CRM_Core_DAO_EntityFile();

  if ($id) {
    $fileDao->id = $id;
    if (!$fileDao->find(TRUE)) {
      throw new API_Exception("Invalid ID");
    }

    $entityFileDao->file_id = $id;
    if (!$entityFileDao->find(TRUE)) {
      throw new API_Exception("Cannot modify orphaned file");
    }
  }

  if (!$id && !is_string($content) && !is_string($moveFile)) {
    throw new API_Exception("Mandatory key(s) missing from params array: 'id' or 'content' or 'options.move-file'");
  }
  if (!$isTrusted && $moveFile) {
    throw new API_Exception("options.move-file is only supported on secure calls");
  }
  if (is_string($content) && is_string($moveFile)) {
    throw new API_Exception("'content' and 'options.move-file' are mutually exclusive");
  }
  if ($id && !$isTrusted && isset($file['upload_date']) && $file['upload_date'] != CRM_Utils_Date::isoToMysql($fileDao->upload_date)) {
    throw new API_Exception("Cannot modify upload_date" . var_export(array($file['upload_date'], $fileDao->upload_date, CRM_Utils_Date::isoToMysql($fileDao->upload_date)), TRUE));
  }
  if ($id && $name && $name != CRM_Utils_File::cleanFileName($fileDao->uri)) {
    throw new API_Exception("Cannot modify name");
  }

  $fileDao->copyValues($file);
  if (!$id) {
    $fileDao->uri = CRM_Utils_File::makeFileName($name);
  }
  $fileDao->save();

  $entityFileDao->copyValues($entityFile);
  $entityFileDao->file_id = $fileDao->id;
  $entityFileDao->save();

  $path = $config->customFileUploadDir . DIRECTORY_SEPARATOR . $fileDao->uri;
  if (is_string($content)) {
    file_put_contents($path, $content);
  }
  elseif (is_string($moveFile)) {
    // CRM-17432 Do not use rename() since it will break file permissions.
    // Also avoid move_uplaoded_file() because the API can use options.move-file.
    copy($moveFile, $path);
    unlink($moveFile);
  }

  // Save custom field to entity
  if (!$id && empty($params['entity_table']) && isset($params['field_name'])) {
    civicrm_api3('custom_value', 'create', array(
      'entity_id' => $params['entity_id'],
      $params['field_name'] => $fileDao->id,
    ));
  }

  $result = array(
    $fileDao->id => _civicrm_api3_attachment_format_result($fileDao, $entityFileDao, $returnContent, $isTrusted),
  );
  return civicrm_api3_create_success($result, $params, 'Attachment', 'create');
}

/**
 * Adjust metadata for get action.
 *
 * @param array $spec
 *   List of fields.
 */
function _civicrm_api3_attachment_get_spec(&$spec) {
  $spec = array_merge($spec, _civicrm_api3_attachment_getfields());
}

/**
 * Get Attachment.
 *
 * @param array $params
 *
 * @return array
 *   per APIv3
 * @throws API_Exception validation errors
 */
function civicrm_api3_attachment_get($params) {
  list($id, $file, $entityFile, $name, $content, $moveFile, $isTrusted, $returnContent) = _civicrm_api3_attachment_parse_params($params);

  $dao = __civicrm_api3_attachment_find($params, $id, $file, $entityFile, $isTrusted);
  $result = array();
  while ($dao->fetch()) {
    $result[$dao->id] = _civicrm_api3_attachment_format_result($dao, $dao, $returnContent, $isTrusted);
  }
  return civicrm_api3_create_success($result, $params, 'Attachment', 'create');
}

/**
 * Adjust metadata for Attachment delete action.
 *
 * @param $spec
 */
function _civicrm_api3_attachment_delete_spec(&$spec) {
  unset($spec['id']['api.required']);
  $entityFileFields = CRM_Core_DAO_EntityFile::fields();
  $spec['entity_table'] = $entityFileFields['entity_table'];
  $spec['entity_table']['title'] = CRM_Utils_Array::value('title', $spec['entity_table'], 'Entity Table') . ' (write-once)';
  $spec['entity_id'] = $entityFileFields['entity_id'];
  $spec['entity_id']['title'] = CRM_Utils_Array::value('title', $spec['entity_id'], 'Entity ID') . ' (write-once)';
}

/**
 * Delete Attachment.
 *
 * @param array $params
 *
 * @return array
 * @throws API_Exception
 */
function civicrm_api3_attachment_delete($params) {
  if (!empty($params['id'])) {
    // ok
  }
  elseif (!empty($params['entity_table']) && !empty($params['entity_id'])) {
    // ok
  }
  else {
    throw new API_Exception("Mandatory key(s) missing from params array: id or entity_table+entity_table");
  }

  $config = CRM_Core_Config::singleton();
  list($id, $file, $entityFile, $name, $content, $moveFile, $isTrusted, $returnContent) = _civicrm_api3_attachment_parse_params($params);
  $dao = __civicrm_api3_attachment_find($params, $id, $file, $entityFile, $isTrusted);

  $filePaths = array();
  $fileIds = array();
  while ($dao->fetch()) {
    $filePaths[] = $config->customFileUploadDir . DIRECTORY_SEPARATOR . $dao->uri;
    $fileIds[] = $dao->id;
  }

  if (!empty($fileIds)) {
    $idString = implode(',', array_filter($fileIds, 'is_numeric'));
    CRM_Core_DAO::executeQuery("DELETE FROM civicrm_entity_file WHERE file_id in ($idString)");
    CRM_Core_DAO::executeQuery("DELETE FROM civicrm_file WHERE id in ($idString)");
  }

  // unlink is non-transactional, so we do this as the last step -- just in case the other steps produce errors
  if (!empty($filePaths)) {
    foreach ($filePaths as $filePath) {
      unlink($filePath);
    }
  }

  $result = array();
  return civicrm_api3_create_success($result, $params, 'Attachment', 'create');
}

/**
 * Attachment find helper.
 *
 * @param array $params
 * @param int|null $id the user-supplied ID of the attachment record
 * @param array $file
 *   The user-supplied vales for the file (mime_type, description, upload_date).
 * @param array $entityFile
 *   The user-supplied values of the entity-file (entity_table, entity_id).
 * @param bool $isTrusted
 *
 * @return CRM_Core_DAO
 * @throws API_Exception
 */
function __civicrm_api3_attachment_find($params, $id, $file, $entityFile, $isTrusted) {
  foreach (array('name', 'content', 'path', 'url') as $unsupportedFilter) {
    if (!empty($params[$unsupportedFilter])) {
      throw new API_Exception("Get by $unsupportedFilter is not currently supported");
    }
  }

  $select = CRM_Utils_SQL_Select::from('civicrm_file cf')
    ->join('cef', 'INNER JOIN civicrm_entity_file cef ON cf.id = cef.file_id')
    ->select(array(
      'cf.id',
      'cf.uri',
      'cf.mime_type',
      'cf.description',
      'cf.upload_date',
      'cef.entity_table',
      'cef.entity_id',
    ));

  if ($id) {
    $select->where('cf.id = #id', array('#id' => $id));
  }
  // Recall: $file is filtered by parse_params.
  foreach ($file as $key => $value) {
    $select->where('cf.!field = @value', array(
      '!field' => $key,
      '@value' => $value,
    ));
  }
  // Recall: $entityFile is filtered by parse_params.
  foreach ($entityFile as $key => $value) {
    $select->where('cef.!field = @value', array(
      '!field' => $key,
      '@value' => $value,
    ));
  }
  if (!$isTrusted) {
    // FIXME ACLs: Add any JOIN or WHERE clauses needed to enforce access-controls for the target entity.
    //
    // The target entity is identified by "cef.entity_table" (aka $entityFile['entity_table']) and "cef.entity_id".
    //
    // As a simplification, we *require* the "get" actions to filter on a single "entity_table" which should
    // avoid the complexity of matching ACL's against multiple entity types.
  }

  $dao = CRM_Core_DAO::executeQuery($select->toSQL());
  return $dao;
}

/**
 * Attachment parsing helper.
 *
 * @param array $params
 *
 * @return array
 *   (0 => int $id, 1 => array $file, 2 => array $entityFile, 3 => string $name, 4 => string $content,
 *    5 => string $moveFile, 6 => $isTrusted, 7 => bool $returnContent)
 *    - array $file: whitelisted fields that can pass through directly to civicrm_file
 *    - array $entityFile: whitelisted fields that can pass through directly to civicrm_entity_file
 *    - string $name: the printable name
 *    - string $moveFile: the full path to a local file whose content should be loaded
 *    - bool $isTrusted: whether we trust the requester to do sketchy things (like moving files or reassigning entities)
 *    - bool $returnContent: whether we are expected to return the full content of the file
 * @throws API_Exception validation errors
 */
function _civicrm_api3_attachment_parse_params($params) {
  $id = CRM_Utils_Array::value('id', $params, NULL);
  if ($id && !is_numeric($id)) {
    throw new API_Exception("Malformed id");
  }

  $file = array();
  foreach (array('mime_type', 'description', 'upload_date') as $field) {
    if (array_key_exists($field, $params)) {
      $file[$field] = $params[$field];
    }
  }

  $entityFile = array();
  foreach (array('entity_table', 'entity_id') as $field) {
    if (array_key_exists($field, $params)) {
      $entityFile[$field] = $params[$field];
    }
  }

  if (empty($params['entity_table']) && isset($params['field_name'])) {
    $tableInfo = CRM_Core_BAO_CustomField::getTableColumnGroup(intval(str_replace('custom_', '', $params['field_name'])));
    $entityFile['entity_table'] = $tableInfo[0];
  }

  $name = NULL;
  if (array_key_exists('name', $params)) {
    if ($params['name'] != basename($params['name']) || preg_match(':[/\\\\]:', $params['name'])) {
      throw new API_Exception('Malformed name');
    }
    $name = $params['name'];
  }

  $content = NULL;
  if (isset($params['content'])) {
    $content = $params['content'];
  }

  $moveFile = NULL;
  if (isset($params['options']['move-file'])) {
    $moveFile = $params['options']['move-file'];
  }
  elseif (isset($params['options.move-file'])) {
    $moveFile = $params['options.move-file'];
  }

  $isTrusted = empty($params['check_permissions']);

  $returns = isset($params['return']) ? $params['return'] : array();
  $returns = is_array($returns) ? $returns : array($returns);
  $returnContent = in_array('content', $returns);

  return array($id, $file, $entityFile, $name, $content, $moveFile, $isTrusted, $returnContent);
}

/**
 * Attachment result formatting helper.
 *
 * @param CRM_Core_DAO_File $fileDao
 *   Maybe "File" or "File JOIN EntityFile".
 * @param CRM_Core_DAO_EntityFile $entityFileDao
 *   Maybe "EntityFile" or "File JOIN EntityFile".
 * @param bool $returnContent
 *   Whether to return the full content of the file.
 * @param bool $isTrusted
 *   Whether the current request is trusted to perform file-specific operations.
 *
 * @return array
 */
function _civicrm_api3_attachment_format_result($fileDao, $entityFileDao, $returnContent, $isTrusted) {
  $config = CRM_Core_Config::singleton();
  $path = $config->customFileUploadDir . DIRECTORY_SEPARATOR . $fileDao->uri;

  $result = array(
    'id' => $fileDao->id,
    'name' => CRM_Utils_File::cleanFileName($fileDao->uri),
    'mime_type' => $fileDao->mime_type,
    'description' => $fileDao->description,
    'upload_date' => is_numeric($fileDao->upload_date) ? CRM_Utils_Date::mysqlToIso($fileDao->upload_date) : $fileDao->upload_date,
    'entity_table' => $entityFileDao->entity_table,
    'entity_id' => $entityFileDao->entity_id,
    'icon' => CRM_Utils_File::getIconFromMimeType($fileDao->mime_type),
  );
  $result['url'] = CRM_Utils_System::url(
    'civicrm/file', 'reset=1&id=' . $result['id'] . '&eid=' . $result['entity_id'],
    TRUE,
    NULL,
    FALSE,
    TRUE
  );
  if ($isTrusted) {
    $result['path'] = $path;
  }
  if ($returnContent) {
    $result['content'] = file_get_contents($path);
  }
  return $result;
}

/**
 * Attachment getfields helper.
 *
 * @return array
 *   list of fields (indexed by name)
 */
function _civicrm_api3_attachment_getfields() {
  $fileFields = CRM_Core_DAO_File::fields();
  $entityFileFields = CRM_Core_DAO_EntityFile::fields();

  $spec = array();
  $spec['id'] = $fileFields['id'];
  $spec['name'] = array(
    'title' => 'Name (write-once)',
    'description' => 'The logical file name (not searchable)',
    'type' => CRM_Utils_Type::T_STRING,
  );
  $spec['field_name'] = array(
    'title' => 'Field Name (write-once)',
    'description' => 'Alternative to "entity_table" param - sets custom field value.',
    'type' => CRM_Utils_Type::T_STRING,
  );
  $spec['mime_type'] = $fileFields['mime_type'];
  $spec['description'] = $fileFields['description'];
  $spec['upload_date'] = $fileFields['upload_date'];
  $spec['entity_table'] = $entityFileFields['entity_table'];
  // Would be hard to securely handle changes.
  $spec['entity_table']['title'] = CRM_Utils_Array::value('title', $spec['entity_table'], 'Entity Table') . ' (write-once)';
  $spec['entity_id'] = $entityFileFields['entity_id'];
  $spec['entity_id']['title'] = CRM_Utils_Array::value('title', $spec['entity_id'], 'Entity ID') . ' (write-once)'; // would be hard to securely handle changes
  $spec['url'] = array(
    'title' => 'URL (read-only)',
    'description' => 'URL for downloading the file (not searchable, expire-able)',
    'type' => CRM_Utils_Type::T_STRING,
  );
  $spec['path'] = array(
    'title' => 'Path (read-only)',
    'description' => 'Local file path (not searchable, local-only)',
    'type' => CRM_Utils_Type::T_STRING,
  );
  $spec['content'] = array(
    'title' => 'Content',
    'description' => 'File content (not searchable, not returned by default)',
    'type' => CRM_Utils_Type::T_STRING,
  );

  return $spec;
}