To allow file uploads in your code, you use the \IPS\Helpers\Form\Upload class within the Form Helper.
The administrator has the ability to control how to store different types of file - due to this, using an Upload field is slightly more complicated than most other form types.
The FileStorage extension
You are required to create a FileStorage extension within your application which is mostly used to provide callbacks to locate files uploaded by your field.
To get started, create a FileStorage extension file through the developer center for your application. A skeleton file will be created in the applications/app/extensions/core/FileStorage folder with example code. You will need to provide code for all of the methods.
For example, if you are storing each file in a row in a database table, the code might look something like this:
<?php namespace IPS\forums\extensions\core\FileStorage; class _Key { /** * Count stored files * * @return int */ public function count() { return \IPS\Settings::i()->setting_key ? 1 : 0; } /** * Move stored files * * @param int $offset This will be sent starting with 0, increasing to get all files stored by this extension * @param int $storageConfiguration New storage configuration ID * @param int|NULL $oldConfiguration Old storage configuration ID * @throws \Underflowexception When file record doesn't exist. Indicating there are no more files to move * @return void */ public function move( $offset, $storageConfiguration, $oldConfiguration=NULL ) { $thing = \IPS\Db::i()->select( '*', 'my_table', 'image IS NOT NULL', 'id', array( $offset, 1 ) )->first(); \IPS\Db::i()->update( 'my_table', array( 'image' => (string) \IPS\File::get( $oldConfiguration ?: 'app_Key', $thing['image'] )->move( $storageConfiguration ) ), array( 'id=?', $thing['id'] ) ); } /** * Check if a file is valid * * @param \IPS\Http\Url $file The file to check * @return bool */ public function isValidFile( $file ) { try { \IPS\Db::i()->select( 'id', 'my_table', array( 'image=?', $file ) )->first(); return TRUE; } catch ( \UnderflowException $e ) { return FALSE; } } /** * Delete all stored files * * @return void */ public function delete() { foreach( \IPS\Db::i()->select( '*', 'my_table', "image IS NOT NULL" ) as $forum ) { try { \IPS\File::get( 'app_Key', $forum['image'] )->delete(); } catch( \Exception $e ){} } } }
However the appropriate code to use will depend on the nature of how the content created by your files are stored.
Creating the form element
When creating the element you must provide an $options parameter specifying the extension you just created. For example, the code to create your element will look something like:
$form->add( new \IPS\Helpers\Form\Upload( 'my_upload_field', NULL, TRUE, array( 'storageExtension' => 'app_Key' ) ) );
Additional options are available to allow multiple file uploads, to restrict the allowed extensions, the maximum file size and more. See the source code for all the available options.
Handling submissions
The value returned will be an object of \IPS\File (or an array of \IPS\File objects if the field allows multiple file uploads). You do not need to do anything with the file itself, as it has already been stored according to the administrators preference. You do however, have to save the URL to it (which you can get by casting the \IPS\File object to a string) as that is what you will need to get and manipulate the file later, and use within the extension you created earlier. For example, your code might look like:
$form = new \IPS\Helpers\Form; $form->add( new \IPS\Helpers\Form\Upload( 'my_upload_field', NULL, TRUE, array( 'storageExtension' => 'app_Key' ) ) ); if ( $values = $form->values() ) { \IPS\Db::i()->insert( 'my_table', array( 'image' => (string) $values['my_upload_field'] ) ); }
Manipulating the file later
To get the \IPS\File object back at a later date, you simply call:
$file = \IPS\File::get( 'app_Key', $url );
The first parameter being your extension, and the second being the URL you obtained when saving the form. You can then use this object to get the contents of the file, delete it, etc. See the phpDocs in \IPS\File for more information on what you can do with files.
If it is an image file, you can also create an \IPS\Image object to resize, add a watermark, etc. To do this you call:
$image = \IPS\Image::create( $file->contents() );
See the phpDocs in \IPS\Image for more information on what you can do with images.
Report Document