CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – VI

In the previous articles of this series about an Ajax controlled file upload with PHP progress tracking

CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – V
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – IV
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – III
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – II
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – I

we have shown how we can measure and display the progress of a file upload process with a series of Ajax controlled polling jobs and the progress tracking features of PHP > 5.4. At least in our test example this worked perfectly.

However, for practical purposes and especially when our server users deal with large files we must in addition take better care of some limiting PHP parameters on the server. Both a good server admin and a program developer would, of course, try to find out what file sizes are to be expected on a regular basis and adjust the server parameters accordingly. However, you never know what our beloved users may do. What happens if we talked about file sizes of less than 100MB and suddenly a file with 200MB is transferred to the server?

For which limiting PHP parameters on the server may we run into serious trouble?

Due to security considerations the PHP module interaction with incoming data streams is limited by parameters set for the Apache server. The relevant configuration file is e.g. on Opensuse located at

/etc/php5/apache2/php.ini

The most important limits (set in different sections of the file) are:

; Maximum amount of time each script may spend parsing request data. It's a good
; idea to limit this time on productions servers in order to eliminate unexpectedly
; long running scripts.
; Default Value: -1 (Unlimited)
; Production Value: 60 (60 seconds)
; http://php.net/max-input-time
max_input_time = 200
 
; Maximum size of POST data that PHP will accept.
; Its value may be 0 to disable the limit. It is ignored if POST data reading
; is disabled through enable_post_data_reading.
; http://php.net/post-max-size
post_max_size = 200M
 
; Maximum allowed size for uploaded files.
; http://php.net/upload-max-filesize
upload_max_filesize =150M
 
; Maximum amount of memory a script may consume (128MB)
; http://php.net/memory-limit
memory_limit = 500M

The description of the first parameter above is somewhat unclear. What is meant by the "time spent on parsing request data"? Is this a part of the (also limited) execution time of the PHP target program of our Ajax transaction? Or is this limit imposed on the time required to read incoming POST data and to fill the $_POST array? If the latter were true a small bandwidth could lead to a violation of the "max_input_time" limit ...

Regarding the second parameter the question turns up, whether this limit is imposed on all transferred POST data including the file data?

The third parameter seems to speak for itself. There is a limit for the size of a file that can be transmitted to the server. However, it is not clear how this parameter affects real world scenarios. Does it stop a transfer already before it starts or only when the limit is reached during the transfer?

Regarding the 4th parameter we may suspect that it becomes important already during the handling (reading, parsing) of the incoming POST data. So, how much of memory (RAM) do we need at the server to handle large files during an upload process?

Warning regarding PHP parameter changes for multi-user situation on real world servers

We were and are discussing a privileged situation in this article series: Only one user uploads exactly one big Zip-container file to a server.

In such a situation it is relatively safe to fiddle around with PHP parameters of the central "php.ini" file (or PHP parameter settings in directory specific files; see the last section of this article). However, as an administrator of a server you should always be aware of the consequences of PHP parameter changes, e.g for memory limits, in a multi-user environment.

In addition you must also take into account that our code examples may be extended towards the case that one user may upload multiple files in parallel in one Ajax transaction.

Remarks on "max_input_time" - you can probably ignore it!

If you look up information about "max_input_time" available on the Internet you may experience that some confusion over the implications of this parameter remains. Especially as PHP's own documentation is a bit contradictory - just compare what is said in the following manual pages:

 
Therefore, I tested a bit with files up to 1 GByte over slow and fast connections to PHP servers on the Internet. I came to the conclusion that the answer in the following "stackoverflow" discussion
http://stackoverflow.com/questions/11387113/php-file-upload-affected-or-not-by-max-input-time
describes the server behavior correctly. This means:

This parameter has no consequences with respect to connection bandwidth and the resulting upload time required for file data: It does not limit the required upload time. Neither does it reduce the amount of allowed maximum execution time of the PHP program triggered at the end of the file transfer process to the server.

"max_input_time" imposes a limit on the time to read/parse the data

  • after they have completely arrived at the server
  • and before the PHP program, which shall work with the data, is started.

This "parsing" time normally is very small and the standard value of 60 secs should be enough under most circumstances. If these findings are true we do not need to care much about this parameter during our file transfer process to the server. A value of 60 secs should work even for large files of 1 GB ore more on modern servers. At least for a server with sufficient resources under average load.

See also:

 
However, I can imagine circumstances on a server with many users under heavy load, for which this parameter nevertheless needs to be adjusted.

What does the PHP documentation say about the parameters "post_max_size", "upload_max_filesize" and "memory_limit"?

Regarding these parameters we get at least some clear - though disputable - recommendation from the PHP documentation. At

 
we find the following explanation for "post_max_size":

Sets max size of post data allowed. This setting also affects file upload. To upload large files, this value must be larger than upload_max_filesize. If memory limit is enabled by your configure script, memory_limit also affects file uploading. Generally speaking, memory_limit should be larger than post_max_size. When an integer is used, the value is measured in bytes. Shorthand notation, as described in this FAQ, may also be used. If the size of post data is greater than post_max_size, the $_POST and $_FILES superglobals are empty. This can be tracked in various ways, e.g. by passing the $_GET variable to the script processing the data, i.e. <form action="edit.php?processed=1">, and then checking if $_GET['processed'] is set.

Off topic: For those who find the track-recommendation in the last sentence confusing as it refers to $_GET, see e.g.

 
You can add parameters to your URL and these parameters will appear in $_GET, but if you decided to use the POST mechanism for data transfer these URL-parameters are included in the POST data mechanism of HTTP.

The recommendation for memory sizing is misleading in case of file uploads!

Following the recommendation quoted above would lead to the following relation for the PHP setup:

memory_limit > post_max_size > ( upload_max_file_size * number of files uploaded in parallel ).

Regarding the right side: My understanding is that "upload_max_file_size" sets a limit for each individual file during an upload process. See

 
Actually, I find the recommendation for the parameter "memory_limit" very strange. This would mean that somebody who has to deal with an upload file with a size of 2 GByte would have to allow for memory allocation for a single PHP process in the RAM > 2 GByte. Shall we take such a requirement seriously?

My answer is NO ! But, of course, you should always test yourself ....

To me only the last relation on the right side of the relation chain makes sense during an upload process. Of course PHP needs some RAM and during file uploads also buffering requires sufficient server RAM. But several GByte to control a continuous incoming stream of data which shall be saved as a file into a directory (for temporary files) on the server? No way! I did some tests - e.g. limit the memory to 32 MB and successfully upload a 1 GB file. Therefore, I agree completely with the findings in the following article:

 
See also:

 
So:

Despite you need RAM for buffering during file uploads it is NOT required to use as much physical RAM as the size of the file you want to upload.

However, it may be wise to have as much RAM as possible if you intend to operate on the file as a whole. This may e.g. become important during phases when a PHP program wants to rewrite file data or read them as fast as possible for whatever purpose. A typical example where you may need sufficient memory is image manipulation.

Nevertheless: Regarding the file transfer process to the server itself the quoted recommendation is in my opinion really misleading. And: Do not forget that a high value for "memory_limit" may lead to server problems in a multi-user situation.

"post_max_size" and "upload_max_filesize" as the main limiting PHP parameters for file uploads

So, only the following condition remains:

post_max_size > upload_max_file_size * number of files uploaded in parallel

But this condition should be taken seriously! There are several things that need to be said about these parameters.

  1. A quick test shows: "post_max_size" imposes a limit on all POST data transferred from client - including file data.
  2. Even for situations in which only one file is uploaded I personally would choose "post_max_size" to be several MBs bigger than "upload_max_filesize". Just to account for overhead.
  3. In case of an upload of multiple files in parallel (i.e. a situation, which we have not studied in this article series) you have to get an idea about the typical size and number of files to be uploaded in parallel. In such a situation you may also want to adjust the parameter

    ; Maximum number of files that can be uploaded via a single request
    max_file_uploads = 20

  4. There may be differences depending on the PHP version of how and when the server reacts to a violation of either of both parameters. For PHP 5.4 it seems that the server does not allow for an upload if either of the parameters is violated by the size of the transferred file(s) - meaning: the upload does not even start. This in turn may lead to different error situations on the server and messages issued by the server - depending on which parameter was violated.
  5. From a developer's perspective it is a bit annoying that the PHP servers reaction to a violation of "upload_max_filesize" is indeed very different from its reaction a violation of "post_max_size". See below.

Server reactions to violations of "post_max_size" and "upload_max_filesize"

We need to discuss a bit the reactions of a PHP server towards a violation of the named parameters before we can decide how to react within our PHP or Javascript programs in the course of an Ajax transaction.

Server reaction to a violation of "upload_max_filesize"
The Apache/PHP server reacts to a violation of "upload_max_filesize" by a clear message in

$_FILES['userfile']["error"]

where 'userfile' corresponds to the "name" attribute of the HTML file input element. A reasonable way how to react to PHP error messages in $_FILES by PHP applications is described in the highest ranked comment of
http://php.net/manual/en/features.file-upload.errors.php
and also here
https://blog.hqcodeshop.fi/archives/185-PHP-large-file-uploads.html

Server reaction to a violation of "post_max_size"
What about a violation of "post_max_size"? We can only react reliably to an error via our PHP target programs if an error number or a clear, structured message is provided. Unfortunately, this is not the case when the sum of uploaded data via POST becomes bigger than "post_max_size". When the server detects the violation no content at all is made available in $_POST or $_FILES. So, we have no error-message there a PHP program could react to.

However, we can combine

  • a test for emptiness of the superglobals $POST and $_FILES
  • with some HTTP information from the client, which is saved in $_SERVER,

to react properly in our PHP programs. Such a reaction within our Ajax transactions would naturally include

  • the creation of an error code and an error-message
  • and sending both back within the JSON response to the Javascript client for error control.

When we make a POST request to the server a value of the POST content size is provided by the client and available via the variable

$_SERVER['CONTENT_LENGTH'].

See:

 
So, for the purpose of error control we will need to add some test code to the "initial" PHP target program "handle_uploaded_init_files.php5" of our Ajax transaction which started the file upload.

Reasonable reactions of our PHP upload and polling programs to a violation of "post_max_size"

Remember that our initial Ajax transaction for upload triggered the server file "handle_uploaded_init_files.php5". Therefore, we should some additional code that investigates the violation of post_max_size" there. This would probably look similar to:

if (
	isset( $_SERVER['REQUEST_METHOD'] )      &&
        ($_SERVER['REQUEST_METHOD'] === 'POST' ) &&
        isset( $_SERVER['CONTENT_LENGTH'] )      &&
        ( empty( $_POST ) )
 ) {
	$max_post_size = ini_get('post_max_size');
	$content_length = $_SERVER['CONTENT_LENGTH'] / 1024 / 1024;
	if ($content_length > $max_post_size ) {
		....
		// Our error treatment ....
		$err_code = ....;
		// create an error message and send it to the Ajax client 
		$err_post_size_msg = ".....";
		....
	}

	....
	....
	// transfer the error code and error message to some named element of the JSON object 
	....
	$ajax_response['err_code'] = $err_code;
	$ajax_response['err_msg'] = $err_post_size_msg;
	.....
	$response = json_encode($ajax_response);
	echo $response;
	exit;
}

 
See also:

&nbsP;
Note that we cannot assume a certain timing of the reaction of the main program in comparison to our polling jobs. It may happen that we have already started the polling sequence before the error messages from our first Ajax transaction arrive at the client. Therefore, also our polling jobs "check_progress.php5" should be able to react to empty superglobals $_POST and $_FILES :

if ( ( empty( $_POST ) ) && empty ( $_FILES ) ) {
	// Our error treatment ....
	// create an error message and send it to the Ajax client 
	// refer to messages that may turn up in parallel from the main PHP program
	....
}

 
The different Javascript client methods which receive their respective Ajaj messages should evaluate the error messages and error numbers from the server, display them and, of course, stop the polling loop in case it is still active. As these are trivial programming steps we do not look deeper into them.

Avoid trouble with limiting PHP parameters before starting the file upload

Although we can react to error situations as described above I think it is better to avoid them. Therefore, I suggest to check file size limits before starting any upload process.

In our special situation with just one big Zip-file to upload we can initiate a file size limit check on the server as soon as we choose the file on the client. This means that the Javascript client must be enabled to react to the file selection action and request some information about the parameters "post_max_size" and "upload_max_filesize" from the server. In addition we need a method to compare the server limits with the size of the chosen file.

Looking into
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress control – II
we see that we had defined a proper Javascript Control Object [CtrlO] for the upload form

<form id="form_upload" name="init_file_form"  action="handle_uploaded_init_files.php5" method="POST" enctype="multipart/form-data" >

 
which - among other things - contains the file selection input tag:

<input type="file" name="init_file" id="inp_upl_file" >

 
However, we had not assigned any method to the file selection process itself. We are changing this now:

function Ctrl_File_Upl(my_name) {
	
	this.obj_name = "Obj_" + my_name; 
	
	// Controls related to GOC and dispatched object addresses
	this.GOC = GOC;
        this.SO_Tbl_Info = null; 
        this.SO_Msg      = null; 
			
	// ay to keep the selected file handles 
	this.ay_files = new Array(); 
		
	// msg for 1st Ajax phasefor file upload; 
	this.msg1 = ''; 
		
	// Timeout for file transfer process
	// this.timeout = 500000; // internet servers  
	this.timeout = 300000; 
		
	// define selectors (form, divs) 
	this.div_upload_cont_sel 	= "#" + "div_upload_cont";
	this.div_upload_sel 		= "#" + "div_upload";
	this.p_header_upload_sel 	= "#" + "upl_header" + " > span";
			
	this.form_upload_sel 		= "#" + "form_upload";
	this.input_file_sel 		= "#" + "inp_upl_file";
	this.upl_submit_but 		= "#" + "but_submit_upl";

	this.hinp_upl_tbl_num_sel	= "#" + "hinp_upl_tbl_num";			
	this.hinp_upl_tbl_name_sel	= "#" + "hinp_upl_tbl_name";			
	this.hinp_upl_tbl_snr_sel	= "#" + "hinp_upl_tbl_snr";			
	this.hinp_upl_succ_sel 		= "#" + "hinp_upl_succ";			
	this.hinp_upl_run_type_sel 	= "#" + "hinp_upl_run_type";			
	this.hinp_upl_file_name_sel 	= "#" + "hinp_upl_file_name";			
	this.hinp_upl_file_pipe_sel 	= "#" + "hinp_upl_file_pipe";

	// display the number of extracted and processed files 
	this.num_open_files_sel		= '#' + "num_open_files";
	this.num_extracted_files_sel 	= '#' + "num_extracted_files";
	
	// Other objects on the web page - progress area 
	this.trf_msg_cont	= '#' + "trf_msg_cont";
	this.trf_msg		= '#' + "trf_msg";
	this.imp_msg_cont	= '#' + "imp_msg_cont";
	this.imp_msg		= '#' + "imp_msg";
				
	// Status (!) message box (not the right msg box) 
	this.status_div_cont = '#' + "status_div_cont";
	this.id_progr_msg_p  = "#progr_msg"; 
	
	//progress bar 
	this.id_bar = "#bar"; 
			
	// right msg block
	this.span_main_msg	= "span_msg"; 
	
	// variables to control the obligatory check of the file size 
	this.file_size_is_ok = 1; 
			
	// variables for the Ajax response 
	this.upl_file_succ 	= 0; 
	this.upl_file_name 	= ''; 
        
	// File associated variables
	this.file_name      = '';
        this.file_size_js   = 0; 	// file size detected by JS
        this.file_size      = '';	// file size detected by server
        this.allowed_file_size = 0;	// allowed file size for uploads on the server  
        
	// Processing of files     
        this.num_extracted_files = 0;
	this.file_pipeline 	 = 0; 
	this.import_time 	 = 0; 
	this.transfer_time 	 = 0; 
        
	this.name_succ_dir = ''; 
	this.num_open_files = 1;  

	// transfer time measurement 
	this.date_start = 0;   
	this.date_end = 0; 
	this.ajax_transfer_start = 0; 
	this.ajax_transfer_end 	 = 0; 
			
	// database import time measurement 
	this.date_data_import_start = 0; 
	this.date_data_import_end = 0; 
	this.data_import_start = 0; 
	this.data_import_end = 0; 
			
	this.transfer_time	= 0; 
	this.processing_time = 0; 
	this.time_start = 0; 
			
	// Determine URL for the Form 
	this.url = $(this.form_upload_sel).attr('action'); 
	console.log("Form_Upload_file - url = " + this.url);  				

	// Register methods for event handling 
	this.register_form_events(); 
			 
}	
	
// Method to start uploading the file  
// -------------------------------------------------------------------
Ctrl_File_Upl.prototype.register_form_events = function() {
			
	$(this.input_file_sel).click(
		$.proxy(this, 'select_file') 
	);
			
	$(this.input_file_sel).change(
		$.proxy(this, 'fetch_allowed_file_size') 
	);
	
	$(this.upl_submit_but).click(
		$.proxy(this, 'submit_form') 
	);
				
	$(this.form_upload_sel).submit( 
		$.proxy(this, 'upl_file') 
	); 
					
}; 

 
The reader recognizes that in contrast to the version of the CtrlO "Ctrl_File_Upl" discussed in previous articles of this series we have added some selector IDs for fields of some other web page areas. But the really important change is an extension of the methods for additional events in "Ctrl_File_Upl.prototype.register_form_events()":

First, we react to a click of the file selection button of the file input field. This only serves the purpose of resetting fields and message areas on the web page. But we react also to the file selection itself by using the change event of the file input field. This triggers a method "fetch_allowed_file_size()" which retrieves the parameter "upload_max_filesize" from the server.

Note:
We assume here that the server admin was clever enough to set post_max_size > upload_max_filesize!
Therefore, we only will perform a file size comparison with the value of "upload_max_filesize". If you do not trust your server admin just extend the methods and programs presented below by an additional and separate check for file sizes bigger than "post_max_size". This should be an easy exercise for you.

Now, let us have a look at the new methods of our Javascript CtrlO :

	
// Method to react to a click on the file selection box 
// ---------------------------------------------------- 
Ctrl_File_Upl.prototype.select_file = function (e) {
	// Call method to reset information and message fields 
	// Note: The following method also deactivates the file submit button !  
	this.reset_upl_info(); 
};

	
// Method to check whether file size is too big   
// ---------------------------------------------
// We check whether the file size is too big 
Ctrl_File_Upl.prototype.fetch_allowed_file_size = function (e) {
			
	this.file_size_is_ok = 0; 
			
	// size of the file im MByte determined on the client 
	this.file_size_js = $(this.input_file_sel)[0].files[0].size/1024/1024;
	console.log("actual file size of chosen file = " + this.file_size_js); 	
			
	// Now trigger an Ajaj transaction 
	var ajax_url = "../func/get_allowed_file_size.php5"; 
	var form_data = ''; 
			
	// 03.07.2015: we avoid setup as this would be taken as the standard for subsequent Ajax jobs 
	$.ajax({
                //contentType: "application/x-www-form-urlencoded; charset=ISO-8859-1",
                // context:  Ctrl_Status
                url: ajax_url, 
		context:  this, 
		data: form_data, 
		type: 'POST', 
		dataType: 'json', 
                success: this.response_allowed_file_size, 
                error: this.error_allowed_file_size
        });
};

// Method for Ajaj error handling during file size check transaction 		
// --------------------------------------------------------------	
Ctrl_File_Upl.prototype.error_allowed_file_size = function(jqxhr, error_type) {
			
	// Reset the cursor 
	$('body').css('cursor', 'default' ); 

	// Error handling
	console.log("From Ctrl_File_Upl ::  got Ajax error for fetch_allowed_file_size" );  
	var status = jqxhr.status; 
	var status_txt = jqxhr.statusText; 
	console.log("From Ctrl_File_Upl.prototype.error_allowed_file_size() ::  status = " + status );  
	console.log("From Ctrl_File_Upl.prototype.allowed_file_size ::  status_text = " + status_txt ); 
	console.log("From Ctrl_File_Upl.prototype.allowed_file_size ::  error_type = " + error_type ); 
			
	var msg = "<br>Status: " + status + "  Status text: " + status_txt;    
	this.SO_Msg.show_msg(1, msg); 
};

// Method for Ajaj rsponse handling after file size check transaction 		
// --------------------------------------------------------------			
Ctrl_File_Upl.prototype.response_allowed_file_size = function (json_response, success_code, jqxhr) {
	
	// Reset the cursor 
	$('body').css('cursor', 'default' ); 
				
	var new_msg; 
	var status = jqxhr.status; 
	var status_txt = jqxhr.statusText; 
	console.log("response_allowed_fsize: status = " + status + " , status_text = " + status_txt ); 	

	// The allowed file size on the server
	this.allowed_file_size = json_response['allowed_size'];	
	// parseInt required due to possible MB or GB endings on the server 
	this.allowed_file_size = parseInt(this.allowed_file_size); 
	console.log("allowed file size on server = " + this.allowed_file_size); 	

	// size comparison
	// ----------------
	if ( this.file_size_js > this.allowed_file_size ) {
		this.file_size_is_ok = 0; 
		new_msg = $(this.span_main_msg).html();
		if (new_msg == undefined) {
			new_msg = ""; 
		}
		new_msg += "<br><span style=\"color:#A90000;\">File size too big.</span><br>" +
		"The server allows for files with a size ≤ " +  	
		parseFloat(this.allowed_file_size).toFixed(2) + " MB." + "<br>" + 
		"The size of the chosen file is " + parseFloat(this.file_size_js).toFixed(2) + " MB." + "<br><br>" + 
		"<span style=\"color:#A90000;\">Please choose a different file or reduce the contents !</span>" + "<br><br>" + 
		"If you permanently need a bigger file size limit on the server, please contact your administrator"; 
					
		this.SO_Msg.show_msg(0, new_msg); 
				
	// file size within limits 
	// -------------------------
	else {
		this.file_size_is_ok = 1; 
					
		new_msg = $(this.span_main_msg).html();
		if (new_msg == undefined) {
			new_msg = ""; 
		}
		new_msg += "<br><span style=\"color:#007700;\">File size within server limits.</span><br>" +
		"The server allows for files with a size ≤ " +  parseFloat(this.allowed_file_size).toFixed(2) + " MB." + "<br>" + 
		"The size of the chosen file is " + parseFloat(this.file_size_js).toFixed(2) + " MB." + "<br><br>" + 
		"<span style=\"color:#007700;\">Use the "Start Upload" button to start the file upload!</span>"; 
					
		this.SO_Msg.show_msg(0, new_msg); 
					
		// reactivate the submit button 
		// -----------------------------
		$(this.upl_submit_but).on("click", $.proxy(this, 'submit_form') ); 
		$(this.upl_submit_but).css("color", "#990000"); 
	}
};
	
// Method to reset some form and information fields on the web page 
// ---------------------------------------------------------------
// We have to reset some form and message fields
Ctrl_File_Upl.prototype.reset_upl_info = function() {
				
	var msg_progr = ''; 
	$(this.id_progr_msg_p).html('');
				
	var msg_trf = ''; 
	$(this.trf_msg_cont).css('display', 'none');
	$(this.trf_msg).css('color: #666'); 
	$(this.trf_msg).html(msg_trf);
		    	
	var msg_imp = ''; 
	$(this.imp_msg_cont).css('display', 'none'); 
	$(this.imp_msg).css('color: #666'); 
	$(this.imp_msg).html(msg_imp); 
		    	
	// Deactivate the "Start Upload" Button 
	// ------------------------------------
	$(this.upl_submit_but).off("click"); 
	$(this.upl_submit_but).css("color", "#BBB"); 

	// Reset also the main message area  
	// ----------------------------------------------
	this.SO_Msg.show_msg(0, ''); 

};	

 
This is all pretty straightforward and parts of it are already well known of our previous descriptions for handling the Ajaj interactions with the server by the help of jQuery functionality.

A short description of what happens is:

  • When you click on the button of the file selection input field contents of fields in the message area of our web page and information fields about upload progress are reset as we assume that a new upload will be started.
  • During reset also the form's submit button to start a file upload via Ajax/Ajaj is disabled. Note that we use jQuery's "off('event')"-functionality to to this.
  • As soon as the user selects a specific file we trigger a method which determines and saves the size of the chosen file to a variable and starts an Ajax transaction afterwards. This Ajax interaction calls a target PHP program "get_allowed_file_size.php5" in some directory.
  • The JSON-response of the PHP program is handled by the method
    Ctrl_File_Upl.prototype.response_allowed_file_size.

      The main purpose of this method is to make a comparison of the already determined file size with the limit set on the server and issue some warnings or positive messages. If the file size of the chosen file is within the server's limit we reactivate our "submit" button of the upload form. (Note that we use jQuery's "on('event')"-functionality to to this.) Otherwise we keep it inactive - until a more suitable file is chosen by the user.

Thus, by very simple means we prevent any unreasonable upload process already before it can be started by the user.

It remains to show an excerpt of the simple PHP target file:

<?php

// start session and output buffer
session_start();
ob_start(); 

$file_size_limit = ini_get("upload_max_filesize");
$ajax_response = array();
$ajax_response['allowed_size'] = $file_size_limit; 

$ajax_response['sys_msg'] .= ob_get_contents();
ob_end_clean();

$response = json_encode($ajax_response);
echo $response;
exit; 

?>

Nothing special to discuss here.

Can we change the limiting parameters during PHP program execution?

No, we can not. But as a developer you may be able to define directory specific settings both for "post_max_size" and "upload_max_filesize" on the server by uploading ".htaccess"-files or ".user.ini"-files to program directories - if this is allowed by the administrator.

The web page php.net/manual/en/ini.core.php shows a column "Changeable" for all important parameters and the respective allowed change mechanisms.
See also:
http://php.net/manual/en/ini.list.php

Different methods of how to change PHP parameters as a user are described here:

 
However, if you are not a developer but a server admin, preventing users from changing PHP ini-paramters may even be more important for you:

 
Enough for today. In the next article of this series

CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – VII

we shall have a look at possible problems resulting from timeout limits set for our Ajax transactions.

CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – V

In the previous articles of this series about an Ajax controlled file upload with PHP progress tracking

CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – IV
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – III
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – II
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – I

we have studied elements of an Ajax controlled setup to trigger the upload itself and additional independent jobs for progress tracking.

On the Javascript side we first became acquainted with Control objects [CtrlOs] to fully control HTML elements and the Ajax communication of different forms and objects with the PHP server. We then learned that our main PHP job [handle_uploaded_init_files.php5] triggered from the file upload form is of no use for progress tracking.

In the last article we therefore discussed some Javascript methods to start a sequence of independent Ajax controlled polling jobs. Such jobs can retrieve information about the progress of the file upload from the server periodically and in the background. We learned in addition that we may need some adaption of our polling time interval to the measured data transfer rate. We expect to get the rate information from the server together with some standard progress information as e.g. the sum of bytes uploaded at the moment of polling.

The progress information for the file transfer is continuously updated in the $_SESSION array on the LAMP server according to settings in the php.ini configuration file. In this article we now discuss the rather simple PHP job for fetching the information and sending it back to the client (browser).

The PHP polling job to read progress information and send it to the client

The periodically called PHP job, which we named "check_progress.php5", basically contains four steps:

  • Access the session and start output buffering,
  • instantiate an object which controls information gathering,
  • fetch information from the $_SESSION array,
  • encode and send the JSON object to the Ajax client

PHP program "check_progress.php5"

// start session and output buffer
session_start();
ob_start(); 

// Instantiate progress checker object 
$PC = new ProgressChecker();  

// retrieve and send information 
$PC->check_progr(); 
$PC->encodeAndSendJson(); 
exit; 

// ------------------------------
class ProgressChecker  
{
	//Some variables 
	...
	function __construct() {
		....
	}
	function check_progr() {
		....
	}
	function encodeAndSendJson() {
		....
	}
}

Why did we need the output buffering ob_start()? By using the buffer we control unwanted output produced e.g. by warnings of the PHP interpreter! We want to guarantee that our Ajax client really receives a JSON object (which it expects!) and nothing else. See the third article of this series for more remarks on this point.

Remark, 05.07.2015: We have corrected a mistake in the originally published code. "ob_end_clean()" was removed from the main program code. Note that "ob_end_clean()" must be performed just before the Ajax response is sent. This happens in the method encodeAndSendJson(); see below.

Although not required we put all functionality into a class. This will give us more flexibility in case we need to extend the functionality of the object for progress tracking later on.

Some variables of the class "ProgressChecker"

In our class we first set some initial values of elements of an array "$ajax_response[]". This array will later on be encoded as the JSON response object of our Ajax transaction.

	// The array to build the JSON object from 
	var $ajax_response = array();
	// Some useful variables 
	var $percentage = -1;
	// Error handling 
	var $err = 0;
	// variables to compose the key of progress information in $_SESSION
	var $sess_key_progress 	= '';
	var $key_POST = "progress_key";
	
	function __construct() {
		
		$this->ajax_response['sess_key_progress'] = '';
		
		$this->ajax_response['msg'] = '';
		$this->ajax_response['err'] = 0;
		$this->ajax_response['err_msg'] = '';
		$this->ajax_response['sys_msg'] = '';
		
		$this->ajax_response['finalized'] = 0;
		$this->ajax_response['time'] = '';
		$this->ajax_response['secs'] = 0.0;
		$this->ajax_response['diff_secs'] = 0.0;
		$this->ajax_response['end_time'] = '';
		$this->ajax_response['end_secs'] = 0.0;
	
		$this->ajax_response['bytes'] = -1;
		$this->ajax_response['diff_bytes'] = -1;
		$this->ajax_response['total'] = -1;
		$this->ajax_response['percentage'] = -1;
		$this->ajax_response['rate'] = -1.0;
	
		$this->ajax_response['fs_limit'] = -1;
		$this->ajax_response['max_inp_time'] = -1;
	}

 
We organize the information that may be required by the client: the composed key to access progress information in $_SESSION, some time information and real progress information.

"bytes" represents the number of Bytes received so far on the server, "total" is the total number of bytes of the transferred file (i.e. its size), "percentage" is calculated from "bytes" and "total". In addition we deliver a measured data transfer "rate" in [Bytes/msec]. The reader may compare this with the result handling on the Javascript client side described in the last article of this series.

Last but not least we initialize some variables which shall deliver useful information about parameters set in the "php.ini" file on the server.

You see that we intentionally set some variables to negative values. Such an initialization can help to analyze potential errors on the server and especially after some response has been returned on the client.

Reading progress information from the $_SESSION array

The core of our class is the method check_progress():

function check_progr() {
	
	// Compose the key for the information in the $_SESSION array  
	if (!isset( $_POST[$this->key_POST] ) ) {
		$this->err++;
		$this->ajax_response['err'] = 1;
		$this->ajax_response['err_msg'] .= '<br>The required key was not delivered in $_POST';
	}
		
	if ( $this->err == 0 ) {
		$this->sess_key_progress .= ini_get("session.upload_progress.prefix"). $_POST[$this->key_POST];
		$this->ajax_response['sess_key_progress'] = $this->sess_key_progress;
	}
		
	// Check for progr. information 
		// We have set session.upload_progress.cleanup = Off
		// So we do have some information here
			
	if (!isset($_SESSION[$this->sess_key_progress]) || empty($_SESSION[$this->sess_key_progress])) {
		$this->err++;
		$this->ajax_response['err'] = 2;
		$this->ajax_response['err_msg'] .= '<br>Error: The progress information could not be read from $_SESSION';
		return; 
	}
			
	// Save some information at the first poll for later rate calculations 	
	if (!isset($_SESSION['first_secs'])) {
		$_SESSION['first_secs'] = microtime(true);
	}
	if (!isset($_SESSION['first_bytes'])) {
		$_SESSION['first_bytes'] = $_SESSION[$this->sess_key_progress]["bytes_processed"];
	}
		
	// Get some php.ini parameters
	$file_size_limit = ini_get("upload_max_filesize");
	$this->ajax_response['fs_limit'] = $file_size_limit; 
	$this->ajax_response['max_inp_time'] = ini_get("max_input_time"); 

	// investigate whether file size is too big and return error 
	$file_size = $total / 1024 / 1024; 
	if ( $file_size > $file_size_limit ) {
		$this->err++; 
		$this->ajax_response['err'] = 3;
		$this->ajax_response['err_msg'] .= "<br>Error: The file has a size of " . number_format($file_size, 2, '.', '') . " MByte and is bigger than the allowed limit on the server (" . $file_size_limit . " MByte)"; 
		return; 	
	}
	
	// Retrieve progress information 
			
	// Bytes
	$current = $_SESSION[$this->sess_key_progress]["bytes_processed"];
	$total 	 = $_SESSION[$this->sess_key_progress]["content_length"];
	
	$this->ajax_response['percentage'] = ($current < $total) ? ($current / $total * 100) : 100;
	$this->ajax_response['bytes'] = $current;
	$this->ajax_response['total'] = $total;
		
	$this->ajax_response['time'] = date('%d.%m.%Y-%H:%M:%S');
	$this->ajax_response['secs'] = microtime(true);
	$this->ajax_response['first_bytes'] = $_SESSION['first_bytes'];
	$this->ajax_response['first_secs'] = $_SESSION['first_secs'];
	$this->ajax_response['diff_secs'] = $this->ajax_response['secs']  - $_SESSION['first_secs'];
	$this->ajax_response['diff_bytes'] = $this->ajax_response['bytes'] - $_SESSION['first_bytes'];
	
	// Rate in bytes / msec
	if ($this->ajax_response['diff_secs'] > 1.0 ) {
		$this->ajax_response['rate'] = floor($this->ajax_response['diff_bytes'] / ( $this->ajax_response['diff_secs'] * 1000.0));
	}
		
	// upload finalized ? if yes => cleanup of $_SESSION 
	$done_upl 	= $_SESSION[$this->sess_key_progress]["done"];
	$done_file 	= $_SESSION[$this->sess_key_progress]["files"][0]["done"];
		
	if ($done_upl && $done_file) {
		$this->ajax_response['end_time'] = $this->ajax_response['time'];
		$this->ajax_response['end_secs'] = $this->ajax_response['secs'];
	
		// cleanup of progress variables
		// the real session will be closed by the upload job
		unset($_SESSION[$this->sess_key_progress]);
		unset($_SESSION['first_secs']);
		unset($_SESSION['first_bytes']);
	}
		
}

 
As we already know, we first have to compose the key to access progress information in the $_SESSION array. We must use

  • both information provided by the client to uniquely identify the file transfer process to which our polling job refers
  • and some specific information of the "php.ini" file.

See the third article of this series for more information about this point. Remember that we explicitly took care about the fact that key relevant information reaches the server first - i.e. before the file data.

In the block of program statements we obviously test the existence of progress data - and stop our activities with setting an error flag and an error message in our response array. Such an error situation must be recognized and handled on the client side; see the last article of this series.

Then we add some initial time information and byte information to new elements of the $_SESSION array. Obviously, this happens only at the first polling job. This stored information will later on be used for rate estimations.

Important note:

Our simplified approach to rate estimation via additional $_SESSION variables will only work if you trigger exactly one upload process at a time. If you triggered several upload jobs in parallel (i.e. before previously started jobs have finalized and within one and the same session) you would need to make all progress information which you add to $_SESSION dependent on the identifier of the transfer process.

We leave this extension to the reader and assume that different upload jobs are started from the client only sequentially.

We now fetch 2 parameter values from the "php.ini" file: for the maximum allowed size of upload files and the maximum allowed input parsing time. The latter value determines how much time can be used on the server to deal with the transferred (POST) data. This is a critical limit about which the client should be informed.

In addition: If we find that the size of the transferred file is too big, we return an error to the client.

Next, we retrieve progress information, calculate the reached percentage of transferred bytes and estimate a transfer rate. To avoid any problems with divisions by zero we deliver a rate value only after at least a second (i.e. the default the update time interval on the server for progress information) has passed. Remember that these rate values are used on the client side to adapt the polling period to reasonable values.

Finally, we check by some criteria whether the transfer job has already finished and all file data are received. If this is the case, we erase progress related information from the $_SESSION array. This is absolutely necessary if you want to start further upload jobs during the same PHP session.

Important note:

We are only able to retrieve the information about the end of the file transfer if the progress information is not automatically erased from the $_SESSION array by the tracking engine of the server itself. Otherwise our last polling job would almost always run into problems. So, for our Ajax controlled polling to work flawlessly, we must set:
session.upload_progress.cleanup = Off
in our "php.ini"-file - and do some cleanup ourselves.

At this point I also want to remind the reader that our main job for dealing with the uploaded file data may already have started before the last polling job is triggered. Due to the length of polling time interval such a situation is very probable. We had to take care of this situation on the Javascript client side to avoid a confusing mixture or overwriting of returning messages from both PHP jobs; see the last article of this series for more remarks on this point.

Encoding the JSON object

The final step is trivial:

function encodeAndSendJson() {
	$this->ajax_response['sys_msg'] .= ob_get_contents(); 
	ob_end_clean();
	$response = json_encode($this->ajax_response);
	echo $response; 
}

Some example output of the Ajax controlled client/server interaction for the file upload

After all this theory let us now have a brief look of output of the Ajax interaction between the client and the server. Initially we give the user a chance to select a file

upl_form_1
 
The PHP job that created the web page which contains our upload form also started the required PHP session. You may ignore the upper parts of the displayed excerpt of our web page. The interesting things happen in the lower form which allows for file selection.

The attached information elements (progress bar, small text areas) below actually belong to a separate and different web page area (DIV container) which contains an invisible form for the control of the progress polling jobs.

Note that in the displayed test case we have chosen a ZIP file container (which actually contains 5 files with 5 million records each). Then we start the Ajax controlled transfer with a click on the button "Start Upload". This job starts the file transfer and the first Ajax transaction. This will trigger the main PHP job "handle_uploaded_init_files.php5" for file processing when the data transfer has finalized.

upl_form_2

In parallel the sequence of polling jobs is automatically started in the background. Each Ajax transaction in the time loop triggers a job "check_progress.php5" on the server, which retrieves progress information from $_SESSION as discussed above. The information of each PHP polling job returned to the client via a JSON object is used to enlarge the progress bar and to display additional information text about the progress.

upl_form_3
upl_form_4

Note the display of the bytes transferred, the time elapsed and the remaining time estimated from the measured rate.

After all file data have been received at the server we display some final information in green on the left side. After that the main PHP job (triggered by our original form submit) takes over and the status bar runs again - this time indicating the processing of the individual files we moved to the server in our Zip file container.

upl_form_6

We turn to the handling of the ZIP container and its contents in one of the next articles of this series.

Adaption of the polling interval

In our previous example the polling period stayed at the lowest boundary of 1200 msec. The file (around 80 MByte) was not big enough for an adjustment at the given rate. However, a different example with a bigger file around 150 MByte shows the adaption of the polling period quite clearly. Excerpts from respective messages in the console.log:

time = 1433754422037, 
polling_period = 1200

Present upload percentage = 3.0057897183539
rate is 1485, poll_soll = 1501,
polling_period = 1440

Present upload percentage = 5.0072492005327
rate is 1341, poll_soll = 1652  
polling_period = 1652

Present upload percentage = 7.0087017625639
rate is 1235, poll_soll = 1785
polling_period = 1652

Present upload percentage = 8.0094300619559
rate is 1209, poll_soll = 1821
polling_period = 1821

Present upload percentage = 11.011615536811
rate is 1250, poll_soll = 1765
polling_period = 1821


Present upload percentage = 12.012343836203
rate is 1219, poll_soll = 1807
polling_period = 1821

Present upload percentage = 13.013072712274
rate is 1193, poll_soll = 1844
polling_period = 1821

Present upload percentage = 14.013802741702
rate is 1172, poll_soll = 1875
polling_period = 1821

Present upload percentage = 16.015263377239
rate is 1231, poll_soll = 1790 
polling_period = 1821

Present upload percentage = 17.01599225331
rate is 1211, poll_soll = 1818
polling_period = 1821

Present upload percentage = 18.016722859418
rate is 1193, poll_soll = 1844
polling_period = 1821

Present upload percentage = 19.017454042205
rate is 1177, poll_soll = 1868
polling_period = 1821

Present upload percentage = 21.018911217668
rate is 1206, poll_soll = 1825
polling_period = 1821

 
The rate changes from 1200 msec to 1821 msec in 4 steps. That is exactly what we wanted to achieve.

However, there is a glitch of one additional percent every 4th step. This can be explained by the fact that our polling interval allows for around 1.2 % effective change but that we pick up only a 1% change due to the servers settings between 2 polling events. As the update period on the server is a bit smaller and thus a bit asynchronous to our polling events a glitch is bound to happen around every 4th event on the server. The reader may sketch the polling events and boundaries of the update period on the server in a drawing to get a clear understanding. We can ignore the glitch for all practical purposes.

Note that for larger files at the same rate the adaption would take more steps - but the behavior would more or less be the same.

A first conclusion

So far, so good. Obviously, it is possible to use the progress tracking of PHP versions ≥ 5.4 in combination with a series of Ajax controlled polling jobs. The Javascript side was a bit tricky - but we got it working - and we now have full control about the upload process and its messages. At least in principle ...

However, there are still some severe issues. Especially, if the upload file is big and the rate is small. Then our mechanism may run into trouble due to parameter settings of the PHP engine. In the next article of this series

CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – VI

we will therefore discuss how we can get some control over situations in which violations of server limits become probable.

CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – IV

In the last article of this series

CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – III
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – II
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – I

we saw that PHP 5.4 may write progress information about file uploads into special elements of the $_SESSION-array on the server. We discussed that the PHP session must already be established before the upload process is started by the web client via an Ajax process.

Furthermore, we have understood the following: The PHP target program which is called by the original Ajax request - i.e. the request that starts the file upload - will not be of any use for sending progress information about the file transfer to the client: The code execution of this PHP program only starts after all POST data, including all file data, have completely been transferred to the server.

So, how do we get the progress information which the server continuously updates in the PHP $_SESSION array from the server to our web client during the upload process? In this article we look at a solution based upon a general polling scheme and respective prerequisites on the client, i.e. on the Javascript side. As we want to transfer the status information in the background we again talk about Ajax controlled jobs.

A sequence of Ajax polling jobs

The situation is very much the same as for long lasting PHP jobs [server RUNs] whose status shall be followed by an Ajax mechanism. This can be solved by starting a sequence of periodic Ajax jobs from the same web page from which the original PHP RUN was started. See e.g. the article
Fallen beim Statuscheck lang laufender PHP-Jobs mit Ajax – IV
in this blog and the following drawing:

polling

These periodic jobs "poll" the progress information from some storage on the server - in our case from the $_SESSION array. Therefore, we call the periodic jobs "progress polling jobs".

A status monitoring with polling jobs has advantages and disadvantages. One advantage is that it does not depend on special HTML 5 properties or a special jQuery plugin. Another advantage is that we get complete control over what data are exchanged between server and client. One disadvantage is - as we shall see - that we may need to dynamically adapt the polling time interval to the measured rate of the file transfer. A further potential disadvantage is that it may become difficult to react to problems occurring during the ongoing transfer of the file data. We shall have to come back to this point in a later article.

However, in the present article we ignore potential problems and sketch the basic outline of the polling control.

A form for sending information together with each Ajax polling request

On the web page we associate a small form with the polling jobs. This form is added in a special separate "progress" DIV contaimer of our Template [TPL] for the web page. See: CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – II

	<!-- A div to display the upload progress -->
	<div id="progress">
		<form id="form_upl_progr" style="height:0;" action="check_progress.php5" method="POST">
			<input type="hidden" name="progr_key_name" id="hinp_upl_progress_key_name" value="upl">
		</form> 
		<div id="progress_bar_div">
			<div class="outer_bar_div">
				<div id="bar"></div>
			</div>
		</div>
		<div id="progr_msg_cont">
			<div id="progr_msg_bg"></div>
			<div id="progr_msg_div"><p id="progr_msg"></p></div>
		</div>
		<div id="trf_msg_cont">
			<div id="trf_msg_bg"></div>
			<div id="trf_msg_div"><p id="trf_msg"></p></div>
		</div>
		<div id="imp_msg_cont">
			<div id="imp_msg_bg"></div>
			<div id="imp_msg_div"><p id="imp_msg"></p></div>
		</div>
		.....
		.....
	</div>

 
Obviously, we have named the PHP target program collecting status data "check_progress.php5". In our very basic example the form's only contents is a hidden input field whose value is the identifier for the upload process.

As we have seen in the last article this identifier information is required to compose the key for accessing progress information in the $_SESSION array. Note that the identifier value is identical to the one of the corresponding hidden input field in the original upload form we discussed in our last article. (In a productive example both these values should be set by the TCO (template controller object) that uses the TPL to create the web page.)

Note: In a real world example it may be necessary to send more information to the server - especially for error or problem handling. Our simple form can easily be extended by more variables to be sent to the server.

In the HTML code of our DIV we have already included some elements whose purpose later on will be to display specific information about the file transfer progress and also the following import of files into the database. The DIV with the id="bar" will simulate a growing progress bar. For those who prefer a picture - we intend to display something like this:

upl_form

Our "progress" DIV encapsulates the elements of the lower part. There is no need to discuss CSS properties here.

A Javascript CtrlO for the "Progress Information Area" on the web page

We follow our overall Javascript policy to create a "Control object" - a CtrlO - for the "progress" DIV which encapsulates all event handling for the HTML elements plus all Ajax communication handling. We call the correspondent constructor function "Ctrl_Upl_Progr()".

This CtrlO shall be created as a typical singleton and as part of a GOC object (= Global Object Controller) - i.e. its handle or reference will be assigned to some variable

window.GOC.Obj_Upl_Progr

when the web page is loaded. The GOC may also dispatch information about the existence and the address of the object "GOC.Obj_Upl_Progr" to other CtrlOs. Without going into details we indicate "dispatching" by a method "GOC.push_object_references()" :

Excerpts from Javascript code of a JS file loaded in the <header>-tag of the upload web page


// Function called by the web page at the onLoad event
function init() { 
	...
	// The CtrlO object for the DIV displaying a form to upload files    
	GOC.Obj_File_Upl = new Ctrl_File_Upl('File_Upl'); 
	
	// The CtrlO object for the Control of the DIV with progress information 
	GOC.Obj_Upl_Progr = new Ctrl_Upl_Progr('Upl_Progr'); 
	...
	...
	// Dispatch references of all other CtrlOs to each of the CtrlOs 
	GOC.push_object_references(); 
}
....
.....
// Constructor function 
function Ctrl_Upl_Progr(my_name) {
       	
	// Required only for possible references to other CtrlOs 
	this.GOC = GOC;
	// The singleton object in the GOC  
	this.obj_name = "Obj_" + my_name; 
        
	// Selectors
	this.id_progr_form	= "#form_upl_progr"; 
	this.id_progr_div 	= "#progr_bar_div"; 
	this.id_bar 		= "#bar"; 
	this.progr_msg_cont 	= "#progr_msg_cont"; 
	this.progr_msg_p 	= "#progr_msg"; 
	this.trf_msg_cont	= '#trf_msg_cont";
	this.trf_msg		= '#trf_msg";
          
	// Register some events  
	this.register_events(); 

	// timer and initial interval for retrieving progress information 
	this.upl_min_polling_interval = 1200; 
 	this.upl_polling_interval = 1200; 
	this.upl_max_polling_interval = 2000; 
	this.upl_progr_timer = null; 
	this.upl_progr_count = 0; 
	this.upl_progr_count_limit = 100; 
           
	// did the last poll job return ?   	
	this.poll_return = 1; 

	// some progress information 
	this.file_size 	= 0;
	this.last_upl_percentage = 0; 
	this.present_upl_percentage = 0; 
       
	// rate of bytes per msec
	this.present_rate = -1.0; 
	this.diff_bytes	= 0.0; 
	this.diff_secs = 0.0; 
	this.first_bytes = 0.0; 
	this.first_secs = 0.0; 
	this.bytes = 0; 
      
	// start time 
	this.start_time = Date.now(); 
 
	// deal with race condition between messages from the last polling job 
	// and response messages from the executing main PHP job   
	this.race_finalized = 0;

	// Parameters for the Ajax connections 
	this.ajax_url = $(this.id_progr_form).attr('action'); 
	this.ajax_return_data_type = 'json';
 
	// Ajax return messages
	this.err = 0; 
	this.msg = ''; 	
	this.err_msg = ''; 	
	this.sys_msg = ''; 	
}   
....
....
/* Container for global objects - the "this"-operator refers here to the Global object - becoming "window" in browsers */ 
this.GOC = new Global_Objects();
  

 
For the meaning and purpose of the GOC see also a comment to the second article of our series.

The CtrlO "Obj_File_Upl" for the upload form should already be familiar from a previous article. Although one may dispute the approach of assuming and using "singleton" objects in the context of other Javascript tasks, I find the CtrlO approach very clear and convenient for dealing with well defined web page areas providing a certain service: The reason is that such UI areas are relatively individual; so they should be controlled by equally individual CtrlOs. Nevertheless we still try to obey two rules to avoid any dependency on the "singleton" property :

  • The CtrlO methods should not require any special knowledge about the internal structure of the GOC.
  • The CtrlO methods should still work even if several CtrlO objects of the same type are created (full encapsulation).

The latter may become relevant later; e.g. if you want to upload several distinct files for different purposes on the same web page.

Note that we call a method "register_events()" to register methods for handling events occurring for elements of our DIV container. This is a central element of a CtrlO.

Polling frequency and progress update period on the server

Note that we set the initial polling time interval on the client to be 1200 msec. This means that (initially) every 1200 msec an Ajax request will be sent to the server. OK - but this raises the question:

How often is the progress information in the $_SESSION array updated on the server? What is the update frequency on the server compared with our polling frequency?

Not surprisingly, the progress update period on the server is defined by some parameters in the file "/etc/php5/apache2/php.ini":

; How frequently the upload progress should be updated.
; Given either in percentages (per-file), or in bytes
; Default Value: "1%"
session.upload_progress.freq =  "1%"

; The minimum delay between updates, in seconds
; Default Value: 1
session.upload_progress.min_freq = "1"

 
The latter value min_freq has to be an integer. Please, keep in mind that some of the logic we later on implement in our CtrlO only makes sense only if the polling interval on the client is always chosen to be somewhat longer than min_freq on the server.

Now we consider an important question about the whole approach: Can a constant polling interval lead to trouble?

Yes, this is possible. Think about the following situation:

If our connection and the data transfer are very slow we may not see any transfer progress for some polling intervals due to the consequences of the php.ini parameters named above. The progress values may not change although file data arrive continuously - but slowly - at the server.

This may give us a false impression of what is going on and it may impact program decisions whether to stop the polling due to a (falsely) detected potential error situation. In case of a small data transfer rate we obviously should use a relatively long polling time interval to see progress between two consecutive polls. Already this consideration indicates that we need an adaptive polling time interval. Furthermore, we also need to deal with situations where the server responds slowly - i.e. with a period longer than our polling interval. A reasonable approach in such a case is that we should only send a new polling job to the server if we already have received a response to our last polling job. If this is not possible with the chosen polling interval we have to change it. We shall come back to both points below.

Methods of our new CtrlO

What methods does our CtrlO need to control the sequence of Ajax jobs? According to our drawing we need to trigger a time loop. A proper Javascript function for this purpose would be "setInterval()". However, as the context of the function "setInterval()" is the global object (i.e. the browser window) we have to be careful about how we call the function/method

get_status_by_ajax()

that we want to execute periodically :

// method to initiate the time loop for progress control 
Ctrl_Upl_Progr.prototype.get_status_by_ajax = function(setStartTime) {
	
    	if (typeof setStartTime === "undefined" ) {
    		setStartTime = 0; 
    	}
	if ( setStartTime == 1) {
		this.start_time = Date.now(); 
	}
	this.upl_progr_timer = setInterval(this.progr_submit.bind(this), this.upl_polling_interval); 
	if ( this.upl_status_timer != null ) {
		console.log ("upl_progr_timer is set !"); 
	}
    	
	// cleaning the message area of our web page
    	if ( setStartTime == 1  ) { 
    		this.SO_Msg.show_msg(0, '');
    	}
}; 

// Method to trigger submit events for progress polling jobs   
Ctrl_Upl_Progr.prototype.progr_submit = function() {
	$(this.id_progr_form).submit();  
};

// Register events and delegate responsibility to local methods   
Ctrl_Upl_Progr.prototype.register_events = function() {
	$(this.id_progr_form).submit( 
		jQuery.proxy(this, 'poll_progress') 
	);
};

 
The method triggered periodically is obviously one of our CtrlO object - "progr_submit". This method triggers the submit event for our new form which in turn is registered with a CtrlO callback method "poll_progress". To delegate the responsibility for the submit event to a local method of the CtrlO we used jQuery's proxy mechanism. As we used $.proxy() in a previous article of this series we are already familiar with this approach to encapsulate all control mechanisms inside the local CtrlO object.

In addition we introduced a parameter "setStartTime" that distinguishes between the start of a file upload and later calls of the method "get_status_by_ajax(setStartTime)".

Invocation of a local CtrlO method in setInterval()

A closer look shows that we called the "progr_submit()" method in a special way: Why do we need to attach the ".bind(this)" method to the callback function?

As so often with Javascript and jQuery the question behind this "trick" is what the context of the "this" operator in an objects method will be, when this method is indirectly called as a callback. Naturally, we want the "this" operator to point to our CtrlO, because we want to encapsulate everything there. But as a matter of fact the "this" operator of the methods/functions called by setInterval() will point to the global context! But even this depends a bit on how exactly you call the method:

A call as

this.upl_progr_timer = setInterval(this.progr_submit, this.upl_polling_interval);

would not work for us because the "this" context would point to the global object when the callback is invoked.

A call as

this.upl_progr_timer = setInterval(this.progr_submit(), this.upl_polling_interval);

would work - but only once. Here the context really refers to that of the outside calling function "get_status_by_ajax()". But this context of the calling function is destroyed directly after the first call. Working around this specific problem would require a closure - see:
http://stackoverflow.com/questions/10944004/how-to-pass-this-to-window-setinterval
http://stackoverflow.com/questions/2749244/javascript-setinterval-and-this-solution
Both closure approaches discussed in the named articles are nice - but actually not necessary for present browsers.

Actually, there is one special way of enforcing the context of the "Obj_Upl_Progr" correctly via using the object's address in the global context explicitly:

this.upl_progr_timer = setInterval("GOC.Obj_Upl_Progr.progr_submit()", this.upl_polling_interval);

Note that the brackets "()" after the method name are required in this type of approach (at least in FF)!

However, you may set a big question mark behind such a program design and its implied consequences because explicit knowledge about the usage of the "Upl_Progr" class in the GOC is required and the whole approach will only work with singletons. Nevertheless: Our overall design of CtrlOs naturally deals with singletons and a GOC dispatcher - so this solution is somewhat noteworthy. It violates, however, our 2 rules set above.

So, if you want to stay clean use "bind(this)" as in our suggested solution:

this.upl_progr_timer = setInterval(this.progr_submit.bind(this), this.upl_polling_interval);

"bind(context)" sets the context explicitly to the local object from where setInterval is called and will even work in IE > 9. Note that in this approach we do not need to invoke any specific global knowledge about the GOC and that it is not restricted to singletons!

Where from do we start the time loop for polling?

OK, we now have a method to start the time loop for polling. But, we have not yet answered the question, from where and when we start this method. This must of course be done directly after the main job for the file upload has been started. We remember that in
CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – II
we started the main job for file uploading and processing by a special method of the responsible CtrlO "Ctrl_File_Upl". We extend the code now a bit:

Ctrl_File_Upl.prototype.upl_file = function(e) { 
	....
	....
	// Ajax submit  
		
	// URL 
	console.log('upl_file :: url = ' + this.url);
	url = this.url + "?file";
	console.log('upl_file :: submitted url = ' + url);
			
	// Time 
	this.date_start = new Date(); 
	this.ajax_transfer_start = this.date_start.getTime(); 
			
	// Setup and submit Ajax 
	$.ajax({
		// contentType: "application/x-www-form-urlencoded; charset=ISO-8859-1",
		url: url, 
		context:  GOC[this.obj_name],
		timeout: this.timeout,
		data: form_data, 
		type: 'POST', 
		cache: false, 
		dataType: 'json', 
		contentType: false,
		processData: false, 
	
		error: this.error_ajax_file_upl,
		success: this.success_ajax_file_upl
	});
			
	// Start the progress polling 
	// --------------------------	
        this.SO_Upl_Progr.race_finalized = 0; 
        this.time_start = Date.now(); 
        this.SO_Upl_Progr.get_status_by_ajax(1); 
			
};	

 
We just addes some statements that refer to our new CtrlO
"Ctrl_Upl_Progr". Our GOC dispatcher has made this CtrlO available locally in the CtrlO "Ctrl_File_Upl" via the variable
"this.SO_Upl_Progr". Hence:

this.SO_Upl_Progr.get_status_by_ajax(1);

The other statements set values to other variables used in the CtrlO "Ctrl_File_Upl" later on.

Ajax Polling Requests

As you already may have expected we now set up and trigger an Ajax request with the method poll_progress(). As our form is fairly simple, we can just serialize the form data and e.g. use the $.post variant of jQuery's Ajax interface:

Ctrl_Upl_Progr.prototype.poll_progress = function(e) {
         
	//always count polling steps  	
	this.upl_progr_count++; 
        
	// prevent default action of the submit event 
 	e.preventDefault();
    	
	// check against a maximum of periodic calls
 	if ( this.upl_progr_count > this.upl_progr_count_limit ) {
 		clearInterval(this.upl_progr_timer);
 		console.log("progress timer eliminated"); 
 		this.err_msg += "<br><br>Progress polling was stopped due to max request number reached!"; 
 		this.display_msgs(); 
 		return 1;
 	}
        
	// Increase the polling interval if poll_return is not 1 
 	// No new polling job is started if the last did not yet return 
	if (this.poll_return == 0 ) {
		// Adjust interval 
		if (this.upl_polling_interval < this.upl_max_polling_interval ) {
			clearInterval(this.upl_progr_timer);
			this.upl_polling_interval += 100;
			// delay a bit
			setTimeout(this.get_status_by_ajax.bind(this), 100, 0); 
		}
		// jump over one execution 
		else {
			return 2; 
		}
	}
    		
	// start next poll job
	else {
		console.log("Upl_Progr object - poll_progress() :: ajax url = " + this.ajax_url);
		var form_data = $(this.id_progr_form).serialize(); 
		$.ajaxSetup({
			context:  this
		});
		$.post(this.ajax_url, form_data, this.progress_response, this.ajax_return_data_type);  
		this.poll_return = 0; 
		console.log("Upl_Progr object :: submitted Ajax progress polling query to server" );
	}	
}; 

 
Note that we set the context of the Ajax interface explicitly! Thus, we guarantee that the method

this.progress_response

which deals with the JSON answer to our request gets our CtrlO as the context - meaning that the "this" operator will point to our CtrlO and not to some HTML element. We like to emphasize:

Not setting the context for the "this" operator is a common source of errors and mistakes when using callback methods to handle status events or responses in course of Ajax transactions.

Of course, we could have included all parametrization and the call of the Ajax target program in one statement as in our last article. The usage of $.post() in our example has no other reason than showing and discussing an alternative. The parameter for the type of the return data had already been set to "json" in the constructor function.

Remark 28.07.2105:

Due to a mail of a reader I like to point out that using a combination of $.ajaxSetup() with $.post() may have disadvantages because $.ajaxSetup() sets standards for all coming Ajax transactions. Certainly, you do not want the context of all future Ajax transactions point to "Ctrl_Upl_Progr". So, you would have to take care to reset this value as required later on. If you absolutely want to use $.post(), a much more intelligent solution would therefore be to use it in the form "jQuery.post([settings])" with "settings" representing an Ajax key/value parametrization object. See http://api.jquery.com/jquery.post/#jQuery-post-settings. Or just keep using $.ajax() here, too.

Counting the number of executing "progress_poll()" is going on unconditionally until a maximum of allowed calls is reached. This helps to avoid an unlimited time loop. Note in addition that we do not submit a new job if the last one did not yet return some answer. If we experience such a situation we adapt by extending our polling interval slowly but systematically until a maximum value is reached. Thereby, we react adaptively to slow servers or slow connections.

Now you may ask: What happens if the upload progress is going on slowly and the maximum allowed numbers of polling calls is too small? Good point! We will react to this by changing the maximum allowed number of poll calls when dealing with the answers of the server - but only if some upload progress is still measurable. See below.

Dealing with the JSON response of the polling jobs from the server

Now, let us do something about the Ajax response. We expect some element of the JSON object to deliver information about the total size of the file whose upload is ongoing in the background and some information about the percentage of data already transferred to the server. As a simple variant we suggest a method similar to the following code:

Ctrl_Upl_Progr.prototype.progress_response = function(json_progr_result, success_code, jqxhr) {
        
	var msg, err_msg, sys_msg, end_time, count; 
	var poll_soll, poll_diff, poll_rel, time_remain, time_remain_str, time_spent, time_spent_str, time_msg; 
	var div, div_long, p_float_stop, span, span_w; 
	var fs, fs_str, by, upl_bytes, upl_bytes_str, upl_by; 

	// Response  status 
	console.log("Progress response :: received Ajax JSON object from server" );                
	var status = jqxhr.status; 
	var status_txt = jqxhr.statusText; 

	// polling can be continued         
	this.poll_return = 1;     
        
	// error detected by the server ?
	this.err = json_progr_result.err;
	if ( this.err > 0 ) {
		.....
		// general error treatment 
		.....
	}

	// different message types contained in the JSON response  
	this.msg = json_progr_result.msg; 
	this.err_msg = json_progr_result.err_msg; 
	this.sys_msg = json_progr_result.sys_msg; 

	// progress information delivered by the server  
	this.present_upl_percentage = json_progr_result.percentage;
	this.present_rate = json_progr_result.rate; 
	this.file_size = json_progr_result.total;
            
	// Current number of uploaded bytes 
	this.bytes = json_progr_result.bytes; 
	var upl_bytes 	= this.bytes / 1024.0; 
	var upl_by 	= " KB"; 
	if ( upl_bytes > 1024 ) {
		upl_bytes = this.bytes/(1024 * 1024);
		upl_by = " MB"; 
	}
	upl_bytes = upl_bytes.toFixed(2); 
	upl_bytes_str = upl_bytes + upl_by;
		        
	// file_size 
	fs = this.file_size/1024.0;
	by = " KB"; 
	if ( fs > 1024 ) {
		fs = this.file_size/(1024 * 1024);
		by = " MB"; 
	}
	fs = fs.toFixed(2); 
	fs_str = fs + by; 

	// Checking for upload finalization
	end_time  = json_progr_result.end_time; 

	// Shall the associated time loop be stopped ? 
	if ( end_time.length > 0 || this.present_upl_percentage == 100 ) {
		clearInterval(this.upl_progr_timer); 
		console.log("progress timer stopped regularly do to finished upload process on the server");
		// this.present_upl_percentage = 100; 
		this.msg += "<br>File transfer to the server is complete !<br>"; 
	}
        	
	// Set the limit up if the max number is reached but upload is still processing regularly 
	else {
		if (this.present_upl_percentage > 0 && this.present_upl_percentage > this.last_upl_percentage 
		&& ( this.upl_progr_count + 2 > this.upl_progr_count_limit	) ) {
			this.upl_progr_count_limit += 100; 
			console.log("limit for polling counts raised by 100!" ); 
		}
	}
            
	// Display information about percentage - e.g. in form of a progress bar 
	if (this.present_upl_percentage > 0 ) {
		this.last_upl_percentage = this.present_upl_percentage; 
		this.display_upl_percentage(); 
		if ( this.last_upl_percentage < 100 ) {
			this.msg += "<br>File upload is progressing!<br>" 
		}
		this.msg += this.last_upl_percentage.toFixed(2) + " percent of the file have been transferred"; 

		// Display info in special field 
		var msg_trf = "Transfer: " + upl_bytes_str + " of " + fs_str + " :: " + this.last_upl_percentage.toFixed(2) + " %"; 
		$(this.id_progr_msg_p).html(msg_trf);
	}

	// concatenate upload messages and display them 	
	if ( this.err_msg != '' ) {
	       	this.msg += "<br><br>" + "<span style=\"color:#A90000;\">" + this.err_msg + "</span>"; 
	}
	if ( this.sys_msg != '' ) {
		this.msg += "<br><br>" + this.sys_msg; 
	}
	// Only display messages in a special message area if you do not overwrite
	// messages coming already from the main PHP job or if an error occurred   
	if (this.race_finalized == 0 || this.err > 0  ) { 
		this.display_msgs();
	}
 
        // switch of setInterval's timer in case of error signals from the server 
       	if ( this.err > 0 ) {
       		// For all of the following error types 
       		if ( 1 <= this.err <= 3 )
        		clearInterval(this.upl_progr_timer);
        	}
	}
           
	// Adaption of the polling interval and time estimates 
	if ( this.err == 0 && this.present_upl_percentage > 3 && this.present_rate > 0 ) {
		poll_soll = 1.2 * this.file_size / 100.0 / this.present_rate; 
		poll_soll = Math.round(poll_soll) + 100; 
		poll_diff = poll_soll - this.upl_polling_interval; 
		poll_rel = ( Math.abs(poll_soll - this.upl_polling_interval) ) / this.upl_polling_interval  
     		
		// Only do something if the deviation is bigger than a limit 
		if ( poll_rel > 0.10 ) {
			// Limit the relative change 
			if ( poll_rel > 0.2 ) {
				if (poll_diff < 0 ) {
					poll_soll = 0.8 * this.upl_polling_interval;  
				}
				else {
					poll_soll = 1.2 * this.upl_polling_interval;  
				}
			}
			else {
				if (poll_diff < 0 ) {
					poll_soll = (1.0 - poll_rel) * this.upl_polling_interval;  
				}
				else {
					poll_soll = (1.0 + poll_rel) * this.upl_polling_interval;  
				}
			}
	        			
			if ( poll_soll > this.upl_min_polling_interval) {
				this.upl_polling_interval = poll_soll; 
				if (poll_soll > this.upl_max_polling_interval ) {
					this.upl_max_polling_interval = poll_soll + 100; 
				}
				clearInterval(this.upl_progr_timer);
				// delay a bit
				setTimeout(this.get_status_by_ajax.bind(this), poll_soll, 0); 
			}
		}
	        		
		// time estimate
		time_remain 	= ( (this.file_size - this.bytes) / this.present_rate) / 1000.0;
		time_remain_str = time_remain.toFixed(1) + "s"; 
	        		
		// time spent 
		time_spent 	= (Date.now() - this.start_time); 
		time_spent_str 	= (time_spent / 1000.0).toFixed(1) + "s"; 
		time_msg = "time: " + time_spent_str + " :: " + time_remain_str; 
	        		
		$(this.trf_msg_cont).css('display', 'block');
		$(this.trf_msg).css('color', "#666");  	
		$(this.trf_msg).html(time_msg); 	
	}

	// Reset cursor 
	document.body.style.cursor = 'default';
};

// Adjust a progress bar 
Ctrl_Upl_Progr.prototype.display_upl_percentage = function() {
	width = this.present_upl_percentage + '%';
	$(this.id_bar).css('width', width); 
	console.log("\r\nPresent upload percentage = " + this.present_upl_percentage + "\r\n"); 
}; 

// use another specialized CtrlO for handling a special message display area on the web page 
Ctrl_Upl_Progr.prototype.display_msgs = function() {
	this.SO_Msg.show_msg(0, this.msg);
}; 

 
Explanations:
We just split the JSON response object into its components. The next article will show how we get these values on the server and send them back via Ajax. Components of the JSON response object are:

  • an indicator for potential errors detected by the PHP polling program
  • messages of different types (created during execution of the PHP polling program on the server)
  • progress information in form of a percentage value
  • a value for the transfer rate measured on the server
  • the total file size in bytes
  • the number of bytes received on the server so far
  • an end time value (date down to seconds) on the server when the file transfer was finished

We first transform both the uploaded bytes and the file size to KBytes or MBytes. The end time information is also used as a signal to stop the time loop for polling jobs on the client. This means that it will only be sent as a non blank string if our PHP polling program finds that the upload has finalized.

Please, note that we raise the number of allowed polling calls to the server when we are approaching the limit of allowed calls - if we still see any progress of the upload. Oops - what if the rate is so small that we fall below the discussed server's limit of a 1% change during the polling time interval and progress information is not updated ? Then our monitoring would be stopped! Yes, this would be true if we did not adapt the polling period ....

Adaption of the polling time period

We just saw that it may become essential for our polling based progress monitoring to determine whether there is any progress at all. However, due to the parameter settings for the update interval of the progress information a too small polling period may lead to the false impression of zero progress over one or several polling intervals in case of slow connections.

This is a major reason for adapting the polling time interval to the transfer rate. We do this in our example after 3% of the file is loaded (assuming that our initial interval allows for such a progress during the first hundred polls. If it does not, than our polling interval really is much too small and we need to give it a higher initial value or increase the maximum initial number of allowed polls). In our simple adaption algorithm we set an ideal progress rate to 1.2% of the file size per polling interval. (To choose this a bit bigger than the limit of 1% for updates on the server is done on purpose!)

Furthermore, we only do something with our period if the polling time interval deviates more than 10% from the ideal time interval - and we never go below an interval of 1200 msec. In addition we limit changes to a maximum of 20% of the present value to avoid a jumpy behavior during the first steps of the transfer when the rate may change grossly. Thus, we try to change the polling time interval rather smoothly.

We leave it up to the kind reader to improve our simple adaption algorithm. I may say, however, that it works quite well for my aDSL and vDSL connections where reasonable rates are possible. I do not regard the lower limit of 1200 msec as a problem: If the whole file is loaded in one polling interval - hey, I am happy. Monitoring is needed for slower connections.

Note that we we deliver a parameter "0" to the callback of

setTimeout(this.get_status_by_ajax.bind(this), poll_soll, 0);

This kind of passing a parameter to a callback works in FF and Chrome. Unfortunately, it does not work in MS IE, Version <= 9. Fortunately, our method "get_status_by_ajax()" already takes care of an undefined function parameter.

Some Output

As indicated some received progress information is displayed in special DIV containers; the percentage information may be used to simulate a progress bar by a dynamical change of the width of some colored DIV.

Some other messages from the server are, however, handled by a special CtrlO for a message display and formatting area on our web page. The reader may design such an area by himself and write a related CtrlO. In our example we indicated the use of a message handling CtrlO by the statement "this.SO_Msg.show_msg(0, this.msg);"

Note that we did not discuss any handling of error messages from the server yet. We leave this to the reader. You may use a boolean element "json_progr_result.err" of the JSON response object to indicate an error and its type - and react properly to it. We do not elaborate this here.

In this article we have shown some basic ingredients on the Javascript side for polling progress information about a file transfer from a PHP server. In the next article of this series

CSV file upload with ZIP containers, jQuery, Ajax and PHP 5.4 progress tracking – V

we shall have a look a the PHP side.