Blame - user_guide_src/source/libraries/file_uploading.rst - code-igniter-v3-giggi

blob: c2de598658063468c16d36d6927520b64930cb4c [file] [log] [blame]

Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	1	####################
				2	File Uploading Class
				3	####################
				4
				5	CodeIgniter's File Uploading Class permits files to be uploaded. You can
				6	set various preferences, restricting the type and size of the files.
				7
				8	***********
				9	The Process
				10	***********
				11
				12	Uploading a file involves the following general process:
				13
				14	- An upload form is displayed, allowing a user to select a file and
				15	upload it.
				16	- When the form is submitted, the file is uploaded to the destination
				17	you specify.
				18	- Along the way, the file is validated to make sure it is allowed to be
				19	uploaded based on the preferences you set.
				20	- Once uploaded, the user will be shown a success message.
				21
				22	To demonstrate this process here is brief tutorial. Afterward you'll
				23	find reference information.
				24
				25	Creating the Upload Form
				26	========================
				27
				28	Using a text editor, create a form called upload_form.php. In it, place
				29	this code and save it to your applications/views/ folder:
				30
				31	<html> <head> <title>Upload Form</title> </head> <body> <?php echo
				32	$error;?> <?php echo form_open_multipart('upload/do_upload');?>
				33	<input type="file" name="userfile" size="20" /> <br /><br /> <input
				34	type="submit" value="upload" /> </form> </body> </html>
				35	You'll notice we are using a form helper to create the opening form tag.
				36	File uploads require a multipart form, so the helper creates the proper
				37	syntax for you. You'll also notice we have an $error variable. This is
				38	so we can show error messages in the event the user does something
				39	wrong.
				40
				41	The Success Page
				42	================
				43
				44	Using a text editor, create a form called upload_success.php. In it,
				45	place this code and save it to your applications/views/ folder:
				46
				47	<html> <head> <title>Upload Form</title> </head> <body> <h3>Your file
				48	was successfully uploaded!</h3> <ul> <?php foreach ($upload_data as
				49	$item => $value):?> <li><?php echo $item;?>: <?php echo $value;?></li>
				50	<?php endforeach; ?> </ul> <p><?php echo anchor('upload', 'Upload
				51	Another File!'); ?></p> </body> </html>
				52	The Controller
				53	==============
				54
				55	Using a text editor, create a controller called upload.php. In it, place
				56	this code and save it to your applications/controllers/ folder:
				57
				58	<?php class Upload extends CI_Controller { function \__construct() {
				59	parent::\__construct(); $this->load->helper(array('form', 'url')); }
				60	function index() { $this->load->view('upload_form', array('error' => '
				61	' )); } function do_upload() { $config['upload_path'] = './uploads/';
				62	$config['allowed_types'] = 'gif\\|jpg\\|png'; $config['max_size'] =
				63	'100'; $config['max_width'] = '1024'; $config['max_height'] = '768';
				64	$this->load->library('upload', $config); if ( !
				65	$this->upload->do_upload()) { $error = array('error' =>
				66	$this->upload->display_errors()); $this->load->view('upload_form',
				67	$error); } else { $data = array('upload_data' =>
				68	$this->upload->data()); $this->load->view('upload_success', $data); } }
				69	} ?>
				70
				71	The Upload Folder
				72	=================
				73
				74	You'll need a destination folder for your uploaded images. Create a
				75	folder at the root of your CodeIgniter installation called uploads and
				76	set its file permissions to 777.
				77
				78	Try it!
				79	=======
				80
				81	To try your form, visit your site using a URL similar to this one::
				82
				83	example.com/index.php/upload/
				84
				85	You should see an upload form. Try uploading an image file (either a
				86	jpg, gif, or png). If the path in your controller is correct it should
				87	work.
				88
				89	***************
				90	Reference Guide
				91	***************
				92
				93	Initializing the Upload Class
				94	=============================
				95
				96	Like most other classes in CodeIgniter, the Upload class is initialized
				97	in your controller using the $this->load->library function::
				98
				99	$this->load->library('upload');
				100
				101	Once the Upload class is loaded, the object will be available using:
				102	$this->upload
				103
				104	Setting Preferences
				105	===================
				106
				107	Similar to other libraries, you'll control what is allowed to be upload
				108	based on your preferences. In the controller you built above you set the
				109	following preferences::
				110
				111	$config['upload_path'] = './uploads/'; $config['allowed_types'] = 'gif\|jpg\|png'; $config['max_size'] = '100'; $config['max_width'] = '1024'; $config['max_height'] = '768'; $this->load->library('upload', $config); // Alternately you can set preferences by calling the initialize function. Useful if you auto-load the class: $this->upload->initialize($config);
				112
				113	The above preferences should be fairly self-explanatory. Below is a
				114	table describing all available preferences.
				115
				116	Preferences
				117	===========
				118
				119	The following preferences are available. The default value indicates
				120	what will be used if you do not specify that preference.
				121
				122	Preference
				123	Default Value
				124	Options
				125	Description
				126	upload_path
				127	None
				128	None
				129	The path to the folder where the upload should be placed. The folder
				130	must be writable and the path can be absolute or relative.
				131	allowed_types
				132	None
				133	None
				134	The mime types corresponding to the types of files you allow to be
				135	uploaded. Usually the file extension can be used as the mime type.
				136	Separate multiple types with a pipe.
				137	file_name
				138	None
				139	Desired file name
				140	If set CodeIgniter will rename the uploaded file to this name. The
				141	extension provided in the file name must also be an allowed file type.
				142
				143	overwrite
				144	FALSE
				145	TRUE/FALSE (boolean)
				146	If set to true, if a file with the same name as the one you are
				147	uploading exists, it will be overwritten. If set to false, a number will
				148	be appended to the filename if another with the same name exists.
				149	max_size
				150	0
				151	None
				152	The maximum size (in kilobytes) that the file can be. Set to zero for no
				153	limit. Note: Most PHP installations have their own limit, as specified
				154	in the php.ini file. Usually 2 MB (or 2048 KB) by default.
				155	max_width
				156	0
				157	None
				158	The maximum width (in pixels) that the file can be. Set to zero for no
				159	limit.
				160	max_height
				161	0
				162	None
				163	The maximum height (in pixels) that the file can be. Set to zero for no
				164	limit.
				165	max_filename
				166	0
				167	None
				168	The maximum length that a file name can be. Set to zero for no limit.
				169	max_filename_increment
				170	100
				171	None
				172	When overwrite is set to FALSE, use this to set the maximum filename
				173	increment for CodeIgniter to append to the filename.
				174	encrypt_name
				175	FALSE
				176	TRUE/FALSE (boolean)
				177	If set to TRUE the file name will be converted to a random encrypted
				178	string. This can be useful if you would like the file saved with a name
				179	that can not be discerned by the person uploading it.
				180	remove_spaces
				181	TRUE
				182	TRUE/FALSE (boolean)
				183	If set to TRUE, any spaces in the file name will be converted to
				184	underscores. This is recommended.
				185
				186	Setting preferences in a config file
				187	====================================
				188
				189	If you prefer not to set preferences using the above method, you can
				190	instead put them into a config file. Simply create a new file called the
				191	upload.php, add the $config array in that file. Then save the file in:
				192	config/upload.php and it will be used automatically. You will NOT need
				193	to use the $this->upload->initialize function if you save your
				194	preferences in a config file.
				195
				196	******************
				197	Function Reference
				198	******************
				199
				200	The following functions are available
				201
				202	$this->upload->do_upload()
				203	===========================
				204
				205	Performs the upload based on the preferences you've set. Note: By
				206	default the upload routine expects the file to come from a form field
				207	called userfile, and the form must be a "multipart type::
				208
				209	<form method="post" action="some_action" enctype="multipart/form-data" />
				210
				211	If you would like to set your own field name simply pass its value to
				212	the do_upload function::
				213
				214	$field_name = "some_field_name"; $this->upload->do_upload($field_name)
				215
				216	$this->upload->display_errors()
				217	================================
				218
				219	Retrieves any error messages if the do_upload() function returned
				220	false. The function does not echo automatically, it returns the data so
				221	you can assign it however you need.
				222
				223	Formatting Errors
				224	*****************
				225
				226	By default the above function wraps any errors within <p> tags. You can
				227	set your own delimiters like this::
				228
				229	$this->upload->display_errors('<p>', '</p>');
				230
				231	$this->upload->data()
				232	=====================
				233
				234	This is a helper function that returns an array containing all of the
				235	data related to the file you uploaded. Here is the array prototype::
				236
				237	Array ( [file_name] => mypic.jpg [file_type] => image/jpeg [file_path] => /path/to/your/upload/ [full_path] => /path/to/your/upload/jpg.jpg [raw_name] => mypic [orig_name] => mypic.jpg [client_name] => mypic.jpg [file_ext] => .jpg [file_size] => 22.2 [is_image] => 1 [image_width] => 800 [image_height] => 600 [image_type] => jpeg [image_size_str] => width="800" height="200" )
				238
				239	Explanation
				240	***********
				241
				242	Here is an explanation of the above array items.
				243
				244	Item
				245	Description
				246	file_name
				247	The name of the file that was uploaded including the file extension.
				248	file_type
				249	The file's Mime type
				250	file_path
				251	The absolute server path to the file
				252	full_path
				253	The absolute server path including the file name
				254	raw_name
				255	The file name without the extension
				256	orig_name
				257	The original file name. This is only useful if you use the encrypted
				258	name option.
				259	client_name
				260	The file name as supplied by the client user agent, prior to any file
				261	name preparation or incrementing.
				262	file_ext
				263	The file extension with period
				264	file_size
				265	The file size in kilobytes
				266	is_image
				267	Whether the file is an image or not. 1 = image. 0 = not.
				268	image_width
				269	Image width.
				270	image_height
				271	Image height
				272	image_type
				273	Image type. Typically the file extension without the period.
				274	image_size_str
				275	A string containing the width and height. Useful to put into an image
				276	tag.