The upload class¶
The newly introduced files upload
class replaces the previously existing fileupload
class.
Passing settings to upload class¶
In phpBB versions prior to 3.2, the settings like maximum image dimensions could be passed directly
to the fileupload
class via the constructor. Since these are now retrieved via the container
infrastructure, this is no longer possible. Instead, the new upload
class incorporates several
methods for easily setting the necessary upload requirements:
set_allowed_extensions($allowed_extensions)
set_allowed_dimensions($min_width, $min_height, $max_width, $max_height)
set_max_filesize($max_filesize)
set_disallowed_content($disallowed_content)
set_error_prefix($error_prefix)
Each of these methods returns the current instance of the upload
class allowing for chained calls:
$upload->set_allowed_extensions(['png', 'jpg'])
->set_allowed_dimensions(20, 20, 90, 90)
->set_max_filesize(65536)
->set_error_prefix('AVATAR_');
Uploading files¶
The previously existing form_upload()
, remote_upload()
, and local_upload()
methods no longer exist. Instead, the upload
class now contains the handle_upload()
method.
$files_upload->handle_upload('files.type.local', $source_file, $filedata);
The method expects the upload type as the first argument. Types that are available by default are
files.types.form
files.types.local
files.types.remote
Extensions can of course add new upload types and use them provided that they implement phpbb\files\types\type_interface
.
Any arguments after the type will passed on to the upload type class. These have to implement the upload method and retrieve the passed arguments with func_get_args()
.
Converting uses of fileupload
class¶
It is recommended to use the files
factory for retrieving the files
classes. In this example we will
however use the phpBB container.
Empty constructor¶
In phpBB 3.1, the basic use of the fileupload
class looked as follows:
include_once($phpbb_root_path . 'includes/functions_upload.' . $phpEx);
$upload = new fileupload();
$upload->set_disallowed_content([]);
$extensions = $cache->obtain_attach_extensions((($is_message) ? false : (int) $forum_id));
$upload->set_allowed_extensions(array_keys($extensions['_allowed_']));
$file = ($local) ? $upload->local_upload($local_storage, $local_filedata, $mimetype_guesser) : $upload->form_upload($form_name, $mimetype_guesser, $plupload);
As of phpBB 3.2, this is changed to:
$upload = $phpbb_container->get('files.upload');
$upload->set_disallowed_content([]);
$extensions = $cache->obtain_attach_extensions((($is_message) ? false : (int) $forum_id));
$upload->set_allowed_extensions(array_keys($extensions['_allowed_']));
$file = ($local) ? $upload->handle_upload('files.types.local', $local_storage, $local_filedata) : $upload->handle_upload('files.types.form', $form_name);
Note
Services like phpbb\mimetype\guesser
and phpbb\plupload\plupload
are no longer passed to the upload methods.
The calls can of course also be chained:
$extensions = $cache->obtain_attach_extensions((($is_message) ? false : (int) $forum_id));
$file = $phpbb_container->get('files.upload')
->set_disallowed_content([])
->set_allowed_extensions(array_keys($extensions['_allowed_']))
->handle_upload('files.types.local', $local_storage, $local_filedata);
Settings passed to constructor¶
phpBB 3.1 also allowed passing the settings directly to the constructor of the fileupload
class:
$upload = new fileupload(
$error_prefix,
$allowed_extensions,
$max_filesize,
$min_width,
$min_height,
$max_width,
$max_height,
$disallowed_content
);
Since the upload
class is retrieved with the container or the factory, passing these settings to the
constructor is no longer possible. Instead, these should be passed with the accompanying set_
methods:
$upload = $files_factory->get('files.upload')
->set_error_prefix($error_prefix)
->set_allowed_extensions($allowed_extensions)
->set_max_filesize($max_filesize)
->set_allowed_dimensions($min_width, $min_height, $max_width, $max_height)
->set_disallowed_content($disallowed_content);
This can also be chained to directly call the handle_upload()
method:
$upload = $files_factory->get('files.upload')
->set_error_prefix($error_prefix)
->set_allowed_extensions($allowed_extensions)
->set_max_filesize($max_filesize)
->set_allowed_dimensions($min_width, $min_height, $max_width, $max_height)
->set_disallowed_content($disallowed_content)
->handle_upload('files.types.local', $local_storage, $local_filedata);
Reset settings¶
The settings like maximum file size, allowed dimensions, and error prefix can easily be reset using the
reset_vars()
method.
Perform common checks on upload¶
The common_checks()
method can be used to perform common checks on the filespec
object returned
by the handle_upload()
method. These include checks for the file size of the uploaded file, the file’s
name and extension, and disallowed file content.
This can be performed by simply passing the filespec
object:
$upload->common_checks($filespec);
Note
common_checks()
does not have a function return. Instead, please check the $filespec->error
property after running common_checks()
Check form for validity¶
One can check if a form is valid for file uploads by simply passing the form name to the is_valid()
method.
It will return true on valid forms and false if the file was not uploaded for the specified form or the upload file was
not properly set.
$valid_form = $upload->is_valid('acme_form');