CLASS «ui::» | Class «upload::» | Examples of working with «input type=file»

Links to documentation on classes and helpers:

General

To create «input type=file» fields, methods «input_file» and «input_file_with_save» of the «ui::» class are used.

When creating fields with these methods, the parameter «name» — the «name» attribute of the field — must be passed. The field name must be unique within one module. By the field name, you can later get an array of uploaded files, links to them, or their paths in the file system.

For processing (uploading or deleting) files on the server, methods of the class «upload::» are used.
Also applied is full automatic processing, when using the class «upload::» in your code is not required, the system will do it automatically.

To get an array of links to files uploaded in the field, the helper «upload_links()» is used.

To get an array with links and captions for files uploaded in the field(s), use the helper «upload_links_and_captions()».

To get an array of file system paths to files uploaded in the field, the helper «upload_paths()» is used.

To get an array of all data uploaded in the field, the helper «user_uploads()» is used.

Creating an input type=file field

If the field is inside a form along with other fields:
- use the method «input_file»;
- by default, files are uploaded automatically, no upload-related code is required;
- if you need to upload files manually for additional PHP processing, use methods of the class «upload::» in the form data saving handler.

If the field is single:
- use the method «input_file_with_save»;
- if no additional actions are needed when saving files on the server, you don’t need to create any handlers, the system will upload fully automatically.
By default, the system replaces the file(s) already uploaded in this field. You can change the automatic algorithm to append uploaded files to existing ones by passing the parameter «upload_algo» with the value «keep_old» when creating the field.
- You can also organize manual upload processing. For this, pass your processing identifier in the parameter «handler_upload» when creating the field. Use the class «upload::» in the handler method.

Deleting files from the field

By default, when creating a field using the class «ui::», the parameter «with_delete» is set to «TRUE».
This means:
1) the field will have a button to delete files from the field;
2) deletion after user clicks this button will be done fully automatically, you don’t need to create any handlers.

If you need to perform additional processing when deleting files, pass the processing identifier to this parameter, and in the server handler use the class «upload::» to delete files.

Scheduled automatic file deletion

If you work with user-uploaded files only for a certain period after which the files are no longer needed, you can schedule automatic deletion to free your file system from unnecessary content.
To do this, use the parameter «auto_delete» when creating a field with the class «ui::». See documentation on how to configure it.

Managing uploaded files

All user-uploaded files are stored in the folder «__user_uploads» in the root of your API application.
To manage files, use the «User Uploads» section on the API application main page.

Files you upload on this example page are visible only to you.

In all file examples, we use the parameter «auto_delete» with the value «1». This means all files you upload will be deleted after 1 day.

Automatic and simplest scenario, convenient in most cases.

Upload different types of files in the field.

$args = array();
$args['name'] = input_file_1;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

This example also uses fully automatic file uploading.
We also added the parameter «multiple» to allow uploading multiple files at once, and restricted upload to images only using the parameter «inp_file_only_imgs».

$args = array();
$args['name'] = input_file_2;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['multiple'] = true;
$args['inp_file_only_imgs'] = true;
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

In the next example, we change the algorithm: on re-upload, old files won’t be deleted, new files will be added to old ones. For this, set the parameter «upload_algo» to «keep_old».
Also:
- allow upload of only specific file types instead of images (as in the previous example) using the parameter «inp_file_allowed_types»;
- disable file deletion by setting the parameter «with_delete» to «FALSE».
Upload one or more files, then some more.

$args = array();
$args['name'] = input_file_3;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['multiple'] = true;
$args['upload_algo'] = 'keep_old';
$args['inp_file_allowed_types'] = 'txt,json,csv,doc,docx,pdf';
$args['with_delete'] = false;
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

Sometimes after uploading file(s) you need to forbid replacing or adding them. In other words, if the user already uploaded a file to the field, the field becomes inactive and no file(s) can be replaced or added.
For this, use the parameter «readonly_if_exists» with the value «TRUE», as in this example.
Note, when using «readonly_if_exists» with «TRUE»,
the parameter «with_delete» is by default set to «FALSE» (there will be no delete button). If your business process requires deletion capability, set this parameter to «TRUE» (as in our example).

$args = array();
$args['name'] = input_file_4;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['readonly_if_exists'] = true;
$args['with_delete'] = true;
$args['multiple'] = true;
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

Now we will do semi-automatic file uploading. This means creating a separate handler to upload files and execute your code at the moment of file upload.
Set the parameter «handler_upload» to the processing identifier.

In this example, we will use the method «upload::auto()» to perform the upload. This is used when we do not need to intervene in the upload process but want to run our code before or after upload.
See the documentation for the class «upload::», the method can accept additional arguments.

$args = array();
$args['name'] = input_file_5;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['handler_upload'] = 'my_handler_upload_5';
$args['multiple'] = true;
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

public function my_handler_upload_5() {
	$uploaded_data = upload::auto();
	if($uploaded_data) {
		//... YOUR CODE AFTER UPLOADING FILES
	}
	$msg = "<pre>UPLOADED:\n";
		$msg .= print_r($uploaded_data, true);
	$msg .= "</pre>";
	ojsucc($msg, false);
}

In the next example, in the handler we will use two methods sequentially:
«upload::prepare()»
and «upload::execute()».
This allows us to execute our code during upload: after checking and preparing files, then after their upload.
See documentation for the class «upload::», methods can accept additional arguments.

$args = array();
$args['name'] = input_file_6;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['handler_upload'] = 'my_handler_upload_6';
$args['multiple'] = true;
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

public function my_handler_upload_6() {
	$prepared_data = upload::prepare();
	if($prepared_data) {
		//... YOUR CODE AFTER CHECKING FILES
	}
	$msg = "<pre>PREPARED:\n";
		$msg .= print_r($prepared_data, true);
	$msg .= "</pre>";
	
	$uploaded_data = upload::execute();
	if($uploaded_data) {
		//... YOUR CODE AFTER UPLOADING FILES
	}
	$msg .= "<pre>UPLOADED:\n";
		$msg .= print_r($uploaded_data, true);
	$msg .= "</pre>";
	ojsucc($msg, false);
}

Let's consider an example of semi-automatic file deletion.
By default, file deletion happens automatically, corresponding to the parameter «with_delete» with the value «TRUE» (set by default). You can pass this parameter an identifier of processing instead of «TRUE». On the server handler, use the method «upload::remove()».

Upload files, then delete them.

$args = array();
$args['name'] = input_file_7;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['handler_upload'] = 'my_handler_upload_7';
$args['with_delete'] = 'my_handler_delete_7';
$args['multiple'] = true;
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

public function my_handler_upload_7() {
	$uploaded_data = upload::auto();
	ojsucc();
}

public function my_handler_delete_7() {
	$deleted_data = upload::remove();
	if($deleted_data) {
		//... YOUR CODE AFTER DELETING FILES
	}
	$msg = "<pre>DELETED:\n";
		$msg .= print_r($deleted_data, true);
	$msg .= "</pre>";
	ojsucc($msg, false);
}

This example uses fully automatic upload and deletion.
This example differs from all previous ones in that we use the parameter «with_caption» set to «TRUE». This means the user can (or must) enter captions for files when uploading. You can also pass a string instead of «TRUE» with text that will appear above the caption field instead of the default.

If a caption for the file must be filled, also pass the parameter «with_caption_mand» with the value «TRUE», as in our example.

Use the PHP helper «upload_links_and_captions()», which will return an array of links and captions of the uploaded files of the field (See example of using helpers).

$args = array();
$args['name'] = input_file_8;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['with_caption'] = true;
$args['with_caption_mand'] = true;
$args['multiple'] = true;
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

In this example, we will crop and resize images.
To do this, use the parameters «imagick__crop_image» and «imagick__resize_image».
These parameters apply only when uploading images.

$args = array();
$args['name'] = input_file_9;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['multiple'] = true;
$args['imagick__crop_image'] = array(220, 120, 0, 0);
$args['imagick__resize_image'] = array(580, 930);
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

10.

In this example, we will upload images into a PDF file.
For this, we use the parameter «imgs_to_pdf» with the value «TRUE».
We also set the parameter «upload_algo» to the value «keep_old».
Upload several files, add more files. All files will be uploaded into a single PDF file.

$args = array();
$args['name'] = input_file_10;
$args['label'] = mlang('i_label_upload_your_files').':';
$args['multiple'] = true;
$args['imgs_to_pdf'] = true;
$args['upload_algo'] = 'keep_old';
$args['auto_delete'] = 1;
$str .= ui::input_file_with_save($args);

Files you upload on this example page are visible only to you.

In all file examples, we use the parameter «auto_delete» with the value «1». This means all files you upload will be deleted after 1 day.

In the provided examples, the field values, except for file fields, are not actually saved anywhere.

This section covers examples of using file fields inside forms with other fields.

When creating forms, it is mandatory to use the start and end methods of the class «ui::»: «ui::form_start» and «ui::form_end».

Study the parameters of methods via the links below.

In the server handler, use the method «ui::get_post_VALS()». See the detailed example in the API documentation on how to process forms.
Note, this method performs:

necessary filtering of $_POST data considering data types; you do not need to perform additional filtering;
automatically performs checking and uploading of files if the form contains file fields;
returns an array with filtered field values.

Simple example.

$str .= ui::form_start();
	//--- input
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['name'] = 'my_input';
	$args['label'] = mlang('i_label_name').':';
	$str .= ui::input($args);
	//--- select
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['name'] = 'my_select';
	$args['label'] = mlang('i_label_select_option').':';
	$args['opts'] = array(
		  'opt_1'=>'My Option 1'
		, 'opt_2'=>'My Option 2'
		, 'opt_3'=>'My Option 3'
	);
	$str .= ui::select($args);
	//--- input_file
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['name'] = form_input_file_1;
	$args['label'] = mlang('i_label_upload_your_files').':';
	$args['multiple'] = true;
	$args['auto_delete'] = 1;
	$str .= ui::input_file($args);
$str .= ui::form_end('saves_my_form_1');

public function saves_my_form_1() {
	$values = ui::get_post_VALS();
	//=== Your code
	//...
	//...
	//============ SHOW MESSAGE FOR EXAMPLE
	$msg = '';
	$msg .= "<pre>VALUES:\n";
		$msg .= print_r($values, true);
	$msg .= "</pre>";
	$msg .= '<hr>';
	//===
	$uploaded_data = upload::get_uploaded();
	$msg .= "<pre>UPLOADED:\n";
		$msg .= print_r($uploaded_data, true);
	$msg .= "</pre>";
	//===
	ojsucc($msg, false);
}

A more advanced example. Add another file field, make some fields «required», as well as «with_caption» and «with_caption_mand» for the first file field. Also change the save button.
Note also that for the second file field we set the parameter «upload_algo» to «keep_old», meaning that when uploading new files, old ones won’t be deleted.

$form_args = array();
$form_args['form_validate'] = true;
$str .= ui::form_start($form_args);
	//--- input
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['label'] = mlang('i_label_name').':';
	$args['name'] = 'my_input';
	$str .= ui::input($args);
	//--- select
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['label'] = mlang('i_label_select_option').':';
	$args['name'] = 'my_select';
	$args['opts'] = array(
		  'opt_1'=>'My Option 1'
		, 'opt_2'=>'My Option 2'
		, 'opt_3'=>'My Option 3'
	);
	$args['required'] = true;
	$str .= ui::select($args);
	//--- input_file 1
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['name'] = form_input_file_2-1;
	$args['label'] = mlang('i_label_upload_your_files').':';
	$args['multiple'] = true;
	$args['with_caption'] = true;
	$args['with_caption_mand'] = true;
	$args['required'] = true;
	$args['auto_delete'] = 1;
	$str .= ui::input_file($args);
	//--- input_file 2
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['name'] = form_input_file_2-2;
	$args['label'] = mlang('i_label_upload_your_files').':';
	$args['multiple'] = true;
	$args['upload_algo'] = 'keep_old';
	$args['auto_delete'] = 1;
	$str .= ui::input_file($args);
	//--- btn_save_args
	$btn_save_args = array();
	$btn_save_args['icon'] = array('cloud-upload', 'far');
	$btn_save_args['theme'] = 'warning';
	$btn_save_args['size'] = 'lg';
$str .= ui::form_end('saves_my_form_2', $btn_save_args);

public function saves_my_form_2() {
	$values = ui::get_post_VALS();
	//=== Your code
	//...
	//...
	//============ SHOW MESSAGE FOR EXAMPLE
	$msg = '';
	$msg .= "<pre>VALUES:\n";
		$msg .= print_r($values, true);
	$msg .= "</pre>";
	$msg .= '<hr>';
	//===
	$uploaded_data = upload::get_uploaded();
	$msg .= "<pre>UPLOADED:\n";
		$msg .= print_r($uploaded_data, true);
	$msg .= "</pre>";
	//===
	ojsucc($msg, false);
}

In the next example, consider the case where some file fields are uploaded automatically, and some are uploaded with additional processing.
To implement such a scenario for fields that should not be uploaded automatically and which you will upload in a separate code block, pass the parameter «handler_upload» with the value «TRUE». You must upload files for this field yourself using the class «upload::». In our example, we use the method «upload::auto()» and pass an array argument with field names that must be uploaded in this code block. You can also pass a string with a field name (if only one field upload is required), or pass no arguments to upload files from all fields not automatically uploaded in «ui::get_post_VALS()».

$form_args = array();
$form_args['form_validate'] = true;
$str .= ui::form_start($form_args);
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['name'] = 'my_input';
	$args['label'] = mlang('i_label_name').':';
	$str .= ui::input($args);

	$args = array();
	$args['in_div'] = 'mb-4';
	$args['name'] = 'my_select';
	$args['label'] = mlang('i_label_select_option').':';
	$args['opts'] = array(
		  'opt_1'=>'My Option 1'
		, 'opt_2'=>'My Option 2'
		, 'opt_3'=>'My Option 3'
	);
	$str .= ui::select($args);

	//--- input_file 1
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['name'] = form_input_file_3-1;
	$args['label'] = mlang('i_label_upload_your_files').':';
	$args['multiple'] = true;
	$args['auto_delete'] = 1;
	$str .= ui::input_file($args);
	//--- input_file 2
	$args = array();
	$args['in_div'] = 'mb-4';
	$args['name'] = form_input_file_3-2;
	$args['label'] = mlang('i_label_upload_your_files').':';
	$args['multiple'] = true;
	$args['handler_upload'] = true;
	$args['auto_delete'] = 1;
	$str .= ui::input_file($args);

$str .= ui::form_end('saves_my_form_3');

public function saves_my_form_3() {
	$values = ui::get_post_VALS();
	//=== Your code
	//...
	//...
	//=== CUSTOM upload
	$result_upload = upload::auto(array('form_input_file_3-2'));
	//... your code after uploading 
	//...
	//============ SHOW MESSAGE FOR EXAMPLE
	$msg = '';
	$msg .= "<pre>VALUES:\n";
		$msg .= print_r($values, true);
	$msg .= "</pre>";
	$msg .= '<hr>';
	//===
	$uploaded_data = upload::get_uploaded();
	$msg .= "<pre>UPLOADED:\n";
		$msg .= print_r($uploaded_data, true);
	$msg .= "</pre>";
	//===
	ojsucc($msg, false);
}