X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=api%2Fv3%2FAttachment.php;h=078d0fada84ba6d2a590ba746f2a5d9d867b7923;hb=c28e17683c9a697a035d17c26f337c2229275673;hp=fe61be8d29984103dfe4ddda4542b8156e50c82a;hpb=e00273a917f1ab4b43d0a8a7eb78c295026e3126;p=civicrm-core.git diff --git a/api/v3/Attachment.php b/api/v3/Attachment.php index fe61be8d29..078d0fada8 100644 --- a/api/v3/Attachment.php +++ b/api/v3/Attachment.php @@ -1,8 +1,7 @@ 'civicrm_activity', * 'entity_id' => 123, @@ -44,6 +45,20 @@ * @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("View %s", $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, @@ -65,34 +80,38 @@ * * @package CiviCRM_APIv3 * @subpackage API_Attachment - * @copyright CiviCRM LLC (c) 2004-2014 - * $Id: $ - * */ /** - * Adjust metadata for "create" action + * Adjust metadata for "create" action. * - * @param array $spec list of fields + * @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_table']['api.required'] = 1; $spec['entity_id']['api.required'] = 1; $spec['upload_date']['api.default'] = 'now'; } /** - * Create an attachment + * Create an attachment. + * + * @param array $params * - * @param array $params - * @return array of newly created file property values. - * @access public + * @return array + * Array of newly created file property values. * @throws API_Exception validation errors */ 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); @@ -145,24 +164,37 @@ function civicrm_api3_attachment_create($params) { rename($moveFile, $path); } + // 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) + $fileDao->id => _civicrm_api3_attachment_format_result($fileDao, $entityFileDao, $returnContent, $isTrusted), ); return civicrm_api3_create_success($result, $params, 'Attachment', 'create'); } /** - * Adjust metadata for "create" action + * Adjust metadata for get action. * - * @param array $spec list of fields + * @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 + * + * @return array + * per APIv3 * @throws API_Exception validation errors */ function civicrm_api3_attachment_get($params) { @@ -176,6 +208,11 @@ function civicrm_api3_attachment_get($params) { 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(); @@ -186,7 +223,10 @@ function _civicrm_api3_attachment_delete_spec(&$spec) { } /** - * @param $params + * Delete attachment. + * + * @param array $params + * * @return array * @throws API_Exception */ @@ -208,7 +248,7 @@ function civicrm_api3_attachment_delete($params) { $filePaths = array(); $fileIds = array(); while ($dao->fetch()) { - $filePaths [] = $config->customFileUploadDir . DIRECTORY_SEPARATOR . $dao->uri; + $filePaths[] = $config->customFileUploadDir . DIRECTORY_SEPARATOR . $dao->uri; $fileIds[] = $dao->id; } @@ -230,11 +270,16 @@ function civicrm_api3_attachment_delete($params) { } /** + * 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-supllied values of the entity-file (entity_table, entity_id) + * @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 */ @@ -260,14 +305,14 @@ function __civicrm_api3_attachment_find($params, $id, $file, $entityFile, $isTru if ($id) { $select->where('cf.id = #id', array('#id' => $id)); } - // recall: $file is filtered by parse_params + // 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 + // Recall: $entityFile is filtered by parse_params. foreach ($entityFile as $key => $value) { $select->where('cef.!field = @value', array( '!field' => $key, @@ -288,14 +333,19 @@ function __civicrm_api3_attachment_find($params, $id, $file, $entityFile, $isTru } /** + * 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 + * + * @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) { @@ -318,6 +368,11 @@ function _civicrm_api3_attachment_parse_params($params) { } } + 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'])) { @@ -349,10 +404,17 @@ function _civicrm_api3_attachment_parse_params($params) { } /** - * @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 + * 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) { @@ -385,7 +447,10 @@ function _civicrm_api3_attachment_format_result($fileDao, $entityFileDao, $retur } /** - * @return array list of fields (indexed by name) + * Attachment getfields helper. + * + * @return array + * list of fields (indexed by name) */ function _civicrm_api3_attachment_getfields() { $fileFields = CRM_Core_DAO_File::fields(); @@ -398,11 +463,17 @@ function _civicrm_api3_attachment_getfields() { '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']; - $spec['entity_table']['title'] = CRM_Utils_Array::value('title', $spec['entity_table'], 'Entity Table') . ' (write-once)'; // would be hard to securely handle changes + // 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(