file_progress Interface Reference

Simple interface for receiving progress during long-running file operations. More...

Inheritance diagram for file_progress:

Public Member Functions
	progress ($progress=self::INDETERMINATE, $max=self::INDETERMINATE)
	Called during a file processing operation that reports progress.

Public Attributes
int const	INDETERMINATE = -1
	Constant used for indeterminate progress.

Detailed Description

Simple interface for receiving progress during long-running file operations.

In some cases progress can be reported precisely. In other cases, progress is indeterminate which means that the progress function is called periodically but without information on completion.

Copyright

2013 The Open University

License

http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

progress()

file_progress::progress	(		$progress = self::INDETERMINATE,
			$max = self::INDETERMINATE )

Called during a file processing operation that reports progress.

This function will be called periodically during the operation, assuming it is successful.

The $max value will be the same for each call to progress() within an operation.

If numbers (rather than INDETERMINATE) are provided, then:

• The $progress value will either be the same as last call, or increased by some value (not necessarily 1)
• The $progress value will be less than or equal to the $max value.

There is no guarantee that this function will be called for every value in the range, or that it will be called with $progress == $max.

The function may be called very frequently (e.g. after each file) or quite rarely (e.g. after each large file).

When creating an implementation of this function, you probably want to do the following:

1. Check the current time and do not do anything if it's less than a second since the last time you reported something.
2. Update the PHP timeout (i.e. set it back to 2 minutes or whatever) so that the system will not time out.
3. If the progress is unchanged since last second, still display some output to the user. (Setting PHP timeout is not sufficient; some front-end servers require that data is output to the browser every minute or so, or they will time out on their own.)

Parameters

int	$progress	Current progress, or INDETERMINATE if unknown
int	$max	Max progress, or INDETERMINATE if unknown

Implemented in restore_ui_stage_confirm.

---

The documentation for this interface was generated from the following file:

• lib/filestorage/file_progress.php