File API - Revision history

Devdocsbot: Update migration status and path

2022-05-24T01:41:44Z

Update migration status and path

← Older revision		Revision as of 01:41, 24 May 2022
Line 1:		Line 1:
	{{Template:Migrated\|newDocId=/docs/subsystems~~/apis~~/files}}		{{Template:Migrated\|newDocId=/docs/apis/subsystems/files}}
	{{Moodle 2.0}}		{{Moodle 2.0}}
	==Overview==		==Overview==

Devdocsbot: Protected "File API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-05-06T07:27:02Z

Protected "File API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 07:27, 6 May 2022
(No difference)

Devdocsbot: Update migration status and path

2022-04-28T07:01:06Z

Update migration status and path

← Older revision		Revision as of 07:01, 28 April 2022
Line 1:		Line 1:
	{{Template:Migrated\|newDocId=/docs/apis/files}}		{{Template:Migrated\|newDocId=/docs/subsystems/apis/files}}
	{{Moodle 2.0}}		{{Moodle 2.0}}
	==Overview==		==Overview==

Andrewnicols: Update migration status and path

2022-04-20T16:12:00Z

Update migration status and path

← Older revision		Revision as of 16:12, 20 April 2022
Line 1:		Line 1:
	{{Template:Migrated\|newDocId=docs/apis/files}}		{{Template:Migrated\|newDocId=/docs/apis/files}}
	{{Moodle 2.0}}		{{Moodle 2.0}}
	==Overview==		==Overview==

Andrewnicols at 15:54, 20 April 2022

2022-04-20T15:54:30Z

← Older revision		Revision as of 15:54, 20 April 2022
Line 1:		Line 1:
	{{Template:Migrated\|newDocId=/docs/apis/files}}		{{Template:Migrated\|newDocId=docs/apis/files}}
	{{Moodle 2.0}}		{{Moodle 2.0}}
	==Overview==		==Overview==

Sarjona: Update migration status and path

2022-04-20T14:11:36Z

Update migration status and path

← Older revision		Revision as of 14:11, 20 April 2022
Line 1:		Line 1:
			{{Template:Migrated\|newDocId=/docs/apis/files}}
	{{Moodle 2.0}}		{{Moodle 2.0}}
	==Overview==		==Overview==

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:38:37Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:38, 14 July 2021
				
Line 25:
Line 25:



The general form of the URL is something like The general form of the URL is something like
<code php> <syntaxhighlight lang="php">
$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext $url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext
</syntaxhighlight> </syntaxhighlight>



A specific example might be A specific example might be
<code php> <syntaxhighlight lang="php">
$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg $url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg
</syntaxhighlight> </syntaxhighlight>



Usually, you do not need to construct this URL directly - the function moodle_url::make_pluginfile_url() should be used instead: Usually, you do not need to construct this URL directly - the function moodle_url::make_pluginfile_url() should be used instead:
<code php> <syntaxhighlight lang="php">
$url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename(), false); $url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename(), false);
</syntaxhighlight> </syntaxhighlight>
Line 45:
Line 45:



<strong>Note: </strong>In most cases, when developing third party plugins, pluginfile.php looks for a '''callback function''' in the appropriate plugin. These functions are stored in '''lib.php''' files and are named '''component_name_pluginfile()'''. The arbitrary/extra/infomation.ext is passed to the callback. For example, files in the mod_forum+post file area end up being served by the mod_forum_pluginfile function in mod/forum/lib.php. This function in MYPLUGIN/lib.php will usually follow a pattern like the example below, but the details will vary depending on the restrictions your plugin places on accessing different files (e.g. assignment files can only be accessed by teachers and the student who submitted the file, forum attachments require access to the discussion they are posted on): <strong>Note: </strong>In most cases, when developing third party plugins, pluginfile.php looks for a '''callback function''' in the appropriate plugin. These functions are stored in '''lib.php''' files and are named '''component_name_pluginfile()'''. The arbitrary/extra/infomation.ext is passed to the callback. For example, files in the mod_forum+post file area end up being served by the mod_forum_pluginfile function in mod/forum/lib.php. This function in MYPLUGIN/lib.php will usually follow a pattern like the example below, but the details will vary depending on the restrictions your plugin places on accessing different files (e.g. assignment files can only be accessed by teachers and the student who submitted the file, forum attachments require access to the discussion they are posted on):
<code php> <syntaxhighlight lang="php">
/** /**
  * Serve the files from the MYPLUGIN file areas   * Serve the files from the MYPLUGIN file areas
Line 113:
Line 113:



===Browsing files=== ===Browsing files===
<code php> <syntaxhighlight lang="php">
$browser = get_file_browser(); $browser = get_file_browser();
$context = get_system_context(); $context = get_system_context();
Line 143:
Line 143:



For example, if you have just built a file at the path For example, if you have just built a file at the path
<code php> <syntaxhighlight lang="php">
  $from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .   $from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
          '/' . $preferences->backup_name;           '/' . $preferences->backup_name;
</syntaxhighlight> </syntaxhighlight>
And you want to move it into the course_backup file area, do And you want to move it into the course_backup file area, do
<code php> <syntaxhighlight lang="php">
  $context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);   $context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);
  $fs = get_file_storage();   $fs = get_file_storage();
Line 158:
Line 158:



=== List area files === === List area files ===
<code php> <syntaxhighlight lang="php">
$fs = get_file_storage(); $fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id); $files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);
Line 169:
Line 169:
Or as links... Or as links...



<code php> <syntaxhighlight lang="php">
$out = array(); $out = array();
                     
Line 190:
Line 190:
Here's how to create a file whose contents will be a text string. This is the equivalent of the PHP function <tt>file_put_contents</tt>. Here's how to create a file whose contents will be a text string. This is the equivalent of the PHP function <tt>file_put_contents</tt>.



<code php> <syntaxhighlight lang="php">
$fs = get_file_storage(); $fs = get_file_storage();



Line 214:
Line 214:
This is a way to read a file, equivalent to <tt>file_get_contents</tt>. '''Please note your are allowed to do this ONLY from mod/mymodule/* code, it is not acceptable to do this anywhere else.''' Other code has to use file_browser interface instead. This is a way to read a file, equivalent to <tt>file_get_contents</tt>. '''Please note your are allowed to do this ONLY from mod/mymodule/* code, it is not acceptable to do this anywhere else.''' Other code has to use file_browser interface instead.



<code php> <syntaxhighlight lang="php">
$fs = get_file_storage(); $fs = get_file_storage();



Line 242:
Line 242:
=== Delete file === === Delete file ===



<code php> <syntaxhighlight lang="php">
$fs = get_file_storage(); $fs = get_file_storage();



Line 269:
Line 269:
This functionality requires "unoconv" to be installed and configured on the site - so it is not available on all installations. This functionality requires "unoconv" to be installed and configured on the site - so it is not available on all installations.



<code php> <syntaxhighlight lang="php">
$fs = get_file_storage(); $fs = get_file_storage();

`Mudrd8mz: Text replacement - "`" to ""

2021-07-14T13:05:37Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 13:05, 14 July 2021
Line 27:		Line 27:
	<code php>		<code php>
	$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext		$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext
	</~~code~~>		</syntaxhighlight>

	A specific example might be		A specific example might be
	<code php>		<code php>
	$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg		$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg
	</~~code~~>		</syntaxhighlight>

	Usually, you do not need to construct this URL directly - the function moodle_url::make_pluginfile_url() should be used instead:		Usually, you do not need to construct this URL directly - the function moodle_url::make_pluginfile_url() should be used instead:
	<code php>		<code php>
	$url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename(), false);		$url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename(), false);
	</~~code~~>		</syntaxhighlight>
	Note: If you do not need the 'itemid', then pass null in as this parameter and it will be entirely missed out from the URL - you need to take this into account when serving the file in the callback function, below.		Note: If you do not need the 'itemid', then pass null in as this parameter and it will be entirely missed out from the URL - you need to take this into account when serving the file in the callback function, below.

Line 101:		Line 101:
	send_stored_file($file, 86400, 0, $forcedownload, $options);		send_stored_file($file, 86400, 0, $forcedownload, $options);
	}		}
	</~~code~~>		</syntaxhighlight>

	You normally use an API function to generate these URL automatically, most often the <tt>file_rewrite_pluginfile_urls</tt> function.		You normally use an API function to generate these URL automatically, most often the <tt>file_rewrite_pluginfile_urls</tt> function.
Line 138:		Line 138:
	}		}

	</~~code~~>		</syntaxhighlight>

	===Moving files around===		===Moving files around===
Line 146:		Line 146:
	$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .		$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
	'/' . $preferences->backup_name;		'/' . $preferences->backup_name;
	</~~code~~>		</syntaxhighlight>
	And you want to move it into the course_backup file area, do		And you want to move it into the course_backup file area, do
	<code php>		<code php>
Line 155:		Line 155:
	'timecreated'=>time(), 'timemodified'=>time());		'timecreated'=>time(), 'timemodified'=>time());
	$fs->create_file_from_pathname($file_record, $from_zip_file);		$fs->create_file_from_pathname($file_record, $from_zip_file);
	</~~code~~>		</syntaxhighlight>

	=== List area files ===		=== List area files ===
Line 165:		Line 165:
	echo $f->get_filename();		echo $f->get_filename();
	}		}
	</~~code~~>		</syntaxhighlight>

	Or as links...		Or as links...
Line 184:		Line 184:

	return implode($br, $out);		return implode($br, $out);
	</~~code~~>		</syntaxhighlight>

	=== Create file ===		=== Create file ===
Line 204:		Line 204:
	// Create file containing text 'hello world'		// Create file containing text 'hello world'
	$fs->create_file_from_string($fileinfo, 'hello world');		$fs->create_file_from_string($fileinfo, 'hello world');
	</~~code~~>		</syntaxhighlight>

	If you want to create a file in the Moodle file area based on a 'real' file e.g. in a temporary folder, you can use <tt>create_file_from_pathname</tt> instead. Similarly, you can create a file based on some other file already in Moodle's local files by using <tt>create_file_from_storedfile</tt>. Browse through <tt>lib/filestorage/file_storage.php</tt> for details.		If you want to create a file in the Moodle file area based on a 'real' file e.g. in a temporary folder, you can use <tt>create_file_from_pathname</tt> instead. Similarly, you can create a file based on some other file already in Moodle's local files by using <tt>create_file_from_storedfile</tt>. Browse through <tt>lib/filestorage/file_storage.php</tt> for details.
Line 236:		Line 236:
	// file doesn't exist - do something		// file doesn't exist - do something
	}		}
	</~~code~~>		</syntaxhighlight>

	If you want to access the file directly on disk, this is not permitted. Instead, you need to make a copy of the file in a temporary area and use that. You can do this with <tt>$file->copy_content_to($pathname)</tt>.		If you want to access the file directly on disk, this is not permitted. Instead, you need to make a copy of the file in a temporary area and use that. You can do this with <tt>$file->copy_content_to($pathname)</tt>.
Line 262:		Line 262:
	$file->delete();		$file->delete();
	}		}
	</~~code~~>		</syntaxhighlight>

	=== Convert between file formats (office documents) ===		=== Convert between file formats (office documents) ===
Line 289:		Line 289:
	$convertedfile = $fs->get_converted_document($file, 'pdf');		$convertedfile = $fs->get_converted_document($file, 'pdf');
	}		}
	</~~code~~>		</syntaxhighlight>

	==See also==		==See also==

Howardsmiller: /* Serving files to users */

2019-01-30T09:55:22Z

Serving files to users

← Older revision		Revision as of 09:55, 30 January 2019
Line 36:		Line 36:
	Usually, you do not need to construct this URL directly - the function moodle_url::make_pluginfile_url() should be used instead:		Usually, you do not need to construct this URL directly - the function moodle_url::make_pluginfile_url() should be used instead:
	<code php>		<code php>
	$url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename());		$url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename(), false);
	</code>		</code>
	Note: If you do not need the 'itemid', then pass null in as this parameter and it will be entirely missed out from the URL - you need to take this into account when serving the file in the callback function, below.		Note: If you do not need the 'itemid', then pass null in as this parameter and it will be entirely missed out from the URL - you need to take this into account when serving the file in the callback function, below.

			The final parameter ('false' here) is 'forcedownload'.

	The file serving script then looks at the context id, and component name, and the file area name, and based on that arranges for the file to be served, following appropriate security checks.		The file serving script then looks at the context id, and component name, and the file area name, and based on that arranges for the file to be served, following appropriate security checks.

TimHunt at 22:50, 29 January 2019

2019-01-29T22:50:47Z

← Older revision		Revision as of 22:50, 29 January 2019
Line 97:		Line 97:

	// We can now send the file back to the browser - in this case with a cache lifetime of 1 day and no filtering.		// We can now send the file back to the browser - in this case with a cache lifetime of 1 day and no filtering.
	~~send__stored_file~~($file, 86400, 0, $forcedownload, $options);		send_stored_file($file, 86400, 0, $forcedownload, $options);
	}		}
	</code>		</code>

← Older revision		Revision as of 13:38, 14 July 2021
Line 25:		Line 25:

	The general form of the URL is something like		The general form of the URL is something like
	<~~code~~ php>		<syntaxhighlight lang="php">
	$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext		$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext
	</syntaxhighlight>		</syntaxhighlight>

	A specific example might be		A specific example might be
	<~~code~~ php>		<syntaxhighlight lang="php">
	$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg		$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg
	</syntaxhighlight>		</syntaxhighlight>

	Usually, you do not need to construct this URL directly - the function moodle_url::make_pluginfile_url() should be used instead:		Usually, you do not need to construct this URL directly - the function moodle_url::make_pluginfile_url() should be used instead:
	<~~code~~ php>		<syntaxhighlight lang="php">
	$url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename(), false);		$url = moodle_url::make_pluginfile_url($file->get_contextid(), $file->get_component(), $file->get_filearea(), $file->get_itemid(), $file->get_filepath(), $file->get_filename(), false);
	</syntaxhighlight>		</syntaxhighlight>
Line 45:		Line 45:

	<strong>Note: </strong>In most cases, when developing third party plugins, pluginfile.php looks for a '''callback function''' in the appropriate plugin. These functions are stored in '''lib.php''' files and are named '''component_name_pluginfile()'''. The arbitrary/extra/infomation.ext is passed to the callback. For example, files in the mod_forum+post file area end up being served by the mod_forum_pluginfile function in mod/forum/lib.php. This function in MYPLUGIN/lib.php will usually follow a pattern like the example below, but the details will vary depending on the restrictions your plugin places on accessing different files (e.g. assignment files can only be accessed by teachers and the student who submitted the file, forum attachments require access to the discussion they are posted on):		<strong>Note: </strong>In most cases, when developing third party plugins, pluginfile.php looks for a '''callback function''' in the appropriate plugin. These functions are stored in '''lib.php''' files and are named '''component_name_pluginfile()'''. The arbitrary/extra/infomation.ext is passed to the callback. For example, files in the mod_forum+post file area end up being served by the mod_forum_pluginfile function in mod/forum/lib.php. This function in MYPLUGIN/lib.php will usually follow a pattern like the example below, but the details will vary depending on the restrictions your plugin places on accessing different files (e.g. assignment files can only be accessed by teachers and the student who submitted the file, forum attachments require access to the discussion they are posted on):
	<~~code~~ php>		<syntaxhighlight lang="php">
	/**		/**
	* Serve the files from the MYPLUGIN file areas		* Serve the files from the MYPLUGIN file areas
Line 113:		Line 113:

	===Browsing files===		===Browsing files===
	<~~code~~ php>		<syntaxhighlight lang="php">
	$browser = get_file_browser();		$browser = get_file_browser();
	$context = get_system_context();		$context = get_system_context();
Line 143:		Line 143:

	For example, if you have just built a file at the path		For example, if you have just built a file at the path
	<~~code~~ php>		<syntaxhighlight lang="php">
	$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .		$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
	'/' . $preferences->backup_name;		'/' . $preferences->backup_name;
	</syntaxhighlight>		</syntaxhighlight>
	And you want to move it into the course_backup file area, do		And you want to move it into the course_backup file area, do
	<~~code~~ php>		<syntaxhighlight lang="php">
	$context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);		$context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);
	$fs = get_file_storage();		$fs = get_file_storage();
Line 158:		Line 158:

	=== List area files ===		=== List area files ===
	<~~code~~ php>		<syntaxhighlight lang="php">
	$fs = get_file_storage();		$fs = get_file_storage();
	$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);		$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);
Line 169:		Line 169:
	Or as links...		Or as links...

	<~~code~~ php>		<syntaxhighlight lang="php">
	$out = array();		$out = array();

Line 190:		Line 190:
	Here's how to create a file whose contents will be a text string. This is the equivalent of the PHP function <tt>file_put_contents</tt>.		Here's how to create a file whose contents will be a text string. This is the equivalent of the PHP function <tt>file_put_contents</tt>.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fs = get_file_storage();		$fs = get_file_storage();

Line 214:		Line 214:
	This is a way to read a file, equivalent to <tt>file_get_contents</tt>. '''Please note your are allowed to do this ONLY from mod/mymodule/* code, it is not acceptable to do this anywhere else.''' Other code has to use file_browser interface instead.		This is a way to read a file, equivalent to <tt>file_get_contents</tt>. '''Please note your are allowed to do this ONLY from mod/mymodule/* code, it is not acceptable to do this anywhere else.''' Other code has to use file_browser interface instead.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fs = get_file_storage();		$fs = get_file_storage();

Line 242:		Line 242:
	=== Delete file ===		=== Delete file ===

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fs = get_file_storage();		$fs = get_file_storage();

Line 269:		Line 269:
	This functionality requires "unoconv" to be installed and configured on the site - so it is not available on all installations.		This functionality requires "unoconv" to be installed and configured on the site - so it is not available on all installations.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$fs = get_file_storage();		$fs = get_file_storage();

File API - Revision history

Devdocsbot: Update migration status and path

Devdocsbot: Protected "File API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

Devdocsbot: Update migration status and path

Andrewnicols: Update migration status and path

Andrewnicols at 15:54, 20 April 2022

Sarjona: Update migration status and path

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Howardsmiller: /* Serving files to users */

TimHunt at 22:50, 29 January 2019

Mudrd8mz: Text replacement - "`" to ""`

`Mudrd8mz: Text replacement - "`" to ""