uc_file.api.php in Ubercart 8.4
Same filename and directory in other branches
Hooks provided by the File Downloads module.
File
uc_file/uc_file.api.phpView source
<?php
/**
* @file
* Hooks provided by the File Downloads module.
*/
/**
* @addtogroup hooks
* @{
*/
use Drupal\Core\Session\AccountInterface;
/**
* Gives clearance to a user to download a file.
*
* By default the uc_file module can implement 3 restrictions on downloads: by
* number of IP addresses downloaded from, by number of downloads, and by a set
* expiration date. Developers wishing to add further restrictions can do so by
* implementing this hook. After the 3 aforementioned restrictions are checked,
* the uc_file module will check for implementations of this hook.
*
* @param \Drupal\Core\Session\AccountInterface $user
* The Drupal user object that has requested the download.
* @param $file_download
* The file download object as defined as a row from the uc_file_users table
* that grants the user the download
*
* @return bool
* TRUE or FALSE depending on whether the user is to be permitted download of
* the requested files. When a implementation returns FALSE it should set an
* error message in Drupal using \Drupal::messenger() to inform customers of
* what is going on.
*/
function hook_uc_download_authorize(AccountInterface $user, $file_download) {
if (!$user->status) {
\Drupal::messenger()
->addError(t("This account has been banned and can't download files anymore."));
return FALSE;
}
else {
return TRUE;
}
}
/**
* Performs actions on file products.
*
* The uc_file module comes with a file manager (found at Administer » Store
* administration » Products » View file downloads) that provides some basic
* functionality: deletion of multiple files and directories, and upload of
* single files (those looking to upload multiple files should just directly
* upload them to their file download directory then visit the file manager
* which automatically updates new files found in its directory). Developers
* that need to create more advanced actions with this file manager can do so
* by using this hook.
*
* @param string $op
* The operation being taken by the hook, possible ops defined below.
* - info: Called before the uc_file module builds its list of possible file
* actions. This op is used to define new actions that will be placed in
* the file action select box.
* - insert: Called after uc_file discovers a new file in the file download
* directory.
* - form: When any defined file action is selected and submitted to the form
* this function is called to render the next form. Because this is called
* whenever a module-defined file action is selected, the variable
* $args['action'] can be used to define a new form or append to an existing
* form.
* - upload: After a file has been uploaded, via the file manager's built in
* file upload function, and moved to the file download directory this op
* can perform any remaining operations it needs to perform on the file
* before its placed into the uc_files table.
* - upload_validate: This op is called to validate the uploaded file that
* was uploaded via the file manager's built in file upload function. At
* this point, the file has been uploaded to PHP's temporary directory.
* Files passing this upload validate function will be moved into the file
* downloads directory.
* - validate: This op is called to validate the file action form.
* - submit: This op is called to submit the file action form.
* @param array $args
* A keyed array of values that varies depending on the op being performed,
* possible values defined below.
* - info: None.
* - insert:
* - file_object: The file object of the newly discovered file.
* - form:
* - action: The file action being performed as defined by the key in the
* array sent by hook_uc_file_action($op = 'info').
* - file_ids: The file ids (as defined in the uc_files table) of the
* selected files to perform the action on.
* - upload:
* - file_object: The file object of the file moved into file downloads
* directory.
* - form_id: The form_id variable of the form_submit function.
* - form_values: The form_values variable of the form_submit function.
* - upload_validate:
* - file_object: The file object of the file that has been uploaded into
* PHP's temporary upload directory.
* - form_id: The form_id variable of the form_validate function.
* - form_values: The form_values variable of the form_validate function.
* - validate:
* - form_id: The form_id variable of the form_validate function.
* - form_values: The form_values variable of the form_validate function.
* - submit:
* - form_id: The form_id variable of the form_submit function.
* - form_values: The form_values variable of the form_submit function.
*
* @return array|null
* The return value of hook depends on the op being performed, possible return
* values defined below:
* - info: The associative array of possible actions to perform. The keys are
* unique strings that defines the actions to perform. The values are the
* text to be displayed in the file action select box.
* - insert: None.
* - form: This op should return an array of drupal form elements as defined
* by the drupal form API.
* - upload: None.
* - upload_validate: None.
* - validate: None.
* - submit: None.
*/
function hook_uc_file_action($op, array $args) {
switch ($op) {
case 'info':
return [
'uc_image_watermark_add_mark' => 'Add Watermark',
];
case 'insert':
// Automatically adds watermarks to any new files that are uploaded to
// the file download directory.
_add_watermark($args['file_object']->uri);
break;
case 'form':
if ($args['action'] == 'uc_image_watermark_add_mark') {
$form['watermark_text'] = [
'#type' => 'textfield',
'#title' => t('Watermark text'),
];
$form['actions'] = [
'#type' => 'actions',
];
$form['actions']['submit_watermark'] = [
'#type' => 'submit',
'#value' => t('Add watermark'),
];
}
return $form;
case 'upload':
_add_watermark($args['file_object']->uri);
break;
case 'upload_validate':
// Given a file path, function checks if file is valid JPEG.
if (!_check_image($args['file_object']->uri)) {
$form_state
->setErrorByName('upload', t('Uploaded file is not a valid JPEG'));
}
break;
case 'validate':
if ($args['form_values']['action'] == 'uc_image_watermark_add_mark') {
if (empty($args['form_values']['watermark_text'])) {
$form_state
->setErrorByName('watermark_text', t('Must fill in text'));
}
}
break;
case 'submit':
if ($args['form_values']['action'] == 'uc_image_watermark_add_mark') {
foreach ($args['form_values']['file_ids'] as $file_id) {
$filename = db_query("SELECT filename FROM {uc_files} WHERE fid = :fid", [
':fid' => $file_id,
])
->fetchField();
// Function adds watermark to image.
_add_watermark($filename);
}
}
break;
}
}
/**
* Makes changes to a file before it is downloaded by the customer.
*
* Stores, either for customization, copy protection or other reasons, might
* want to send customized downloads to customers. This hook will allow this
* to happen. Before a file is opened to be transferred to a customer, this
* hook will be called to make any altercations to the file that will be used
* to transfer the download to the customer. This, in effect, will allow a
* developer to create a new, personalized, file that will get transferred to
* a customer.
*
* @param $file_user
* The file_user object (i.e. an object containing a row from the
* uc_file_users table) that corresponds with the user download being
* accessed.
* @param $ip
* The IP address from which the customer is downloading the file.
* @param $fid
* The file id of the file being transferred.
* @param string $file
* The file path of the file to be transferred.
*
* @return string
* The path of the new file to transfer to customer.
*/
function hook_uc_file_transfer_alter($file_user, $ip, $fid, $file) {
// For large files this might be too memory intensive.
$file_data = file_get_contents($file) . " [insert personalized data]";
$new_file = tempnam(file_directory_temp(), 'tmp');
file_put_contents($new_file, $file_data);
return $new_file;
}
/**
* @} End of "addtogroup hooks".
*/
Functions
Name | Description |
---|---|
hook_uc_download_authorize | Gives clearance to a user to download a file. |
hook_uc_file_action | Performs actions on file products. |
hook_uc_file_transfer_alter | Makes changes to a file before it is downloaded by the customer. |