Handlers
Introduction
Fuel allows you to wrap directories and files in objects. By doing this it allows you to access
and modify filesystem items (files and directories) on a OO basis.
The objects received from the File class (or file areas) are File Handlers. Fuel
has two core file handlers: File Handler and Directory Handler.
Like you would expect these classes handle the files and directories.
Topics
Usage
Every helper class comes with a set of methods that allow you to perform operations on the
files or directories wrapped inside the object. Here is are some examples using
File::get:
// First we'll get a file
$file = \File::get(DOCROOT.'/here_is_my/textfile.txt');
Now we've got the file handler, we can use its methods to get something done.
// Let's rename rename it.
$file->rename('new_name');
// Get the file's content
$content = $file->read();
// And rename it back to the original name
$file->rename('textfile');
As you can see in the example above, when renaming the file you don't need to refetch the handler.
You can reuse the same object over and over, untill you delete the file or unset the var.
File handler
The file handlers handles the basic interaction with files. Each example assumes the
$handler var is the fetched handler. Want to know how to get the handler?
Look at the usage section.
forge($path, $config = array(), $area = null, $content = array())
The forge method returns a new File_Handler_File object.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$path |
required |
path to the file |
$config |
array() |
optional config array |
$area |
null |
File_Area instance |
$content |
array |
ignored |
|
Returns |
Returns a new File_Handler_File object. |
Example |
$handler = File_Handler_File::forge('path/to/file.txt', $config_array, $my_file_area);
|
read($as_string = false)
The read method is a shortcut to File::read.
Static |
No |
Parameters |
Param |
Default |
Description |
$as_string |
false |
set to true to use file_get_contents() instead of readfile() |
|
Returns |
Returns IO or string (file contents) |
Example |
$file_content = $handler->read(true);
|
rename($new_name, $new_extension = false)
The rename method is a shortcut to File::rename.
Static |
No |
Parameters |
Param |
Default |
Description |
$new_name |
required |
the new filename |
$new_extension |
false |
the new filename extension |
|
Returns |
boolean, result form rename() |
Example |
$handler->rename('new_name');
|
move($new_path)
The move method is a shortcut to File::move.
Static |
No |
Parameters |
Param |
Default |
Description |
$new_path |
required |
path to new directory, must be valid |
|
Returns |
boolean, result form rename() |
Example |
$handler->move(DOCROOT.'/new/parent/directory/');
|
copy($new_path)
The copy method is a shortcut to File::copy.
Static |
No |
Parameters |
Param |
Default |
Description |
$new_path |
required |
path to directory to copy to, must be valid |
|
Returns |
boolean, result form copy() |
Example |
$handler->copy(DOCROOT.'/directory/');
|
update($new_content)
The update method is a shortcut to File::update.
Static |
No |
Parameters |
Param |
Default |
Description |
$new_content |
required |
the new file content |
|
Returns |
true on success |
Example |
$handler->update('the new content');
|
delete()
The delete method is a shortcut to File::delete.
Static |
No |
Returns |
bool, result from unlink() |
Example |
$handler->delete();
|
get_url()
The get_url method is a shortcut to File::get_url.
Static |
No |
Returns |
The public url |
Example |
$url = $handler->get_url();
|
get_permissions()
The get_permissions method is a shortcut to File::get_permissions.
Static |
No |
Returns |
The octal file permissions |
Example |
$permissions = $handler->get_permissions();
|
get_time($type = 'modified')
The get_time method is a shortcut to File::get_time.
Static |
No |
Parameters |
Param |
Default |
Description |
$type |
'modified' |
What time needs to be returned. Can only be created or modified. |
|
Returns |
The file's created or modified timestamp |
Example |
$created_at = $handler->get_time('created');
$modified_at = $handler->get_time('modified');
// or short
$modified_at = $handler->get_time();
|
get_size()
The get_size method is a shortcut to File::get_size.
Static |
No |
Returns |
The file size in bytes |
Example |
$file_size = $handler->get_size();
|
get_path()
The get_path method returns the file path.
Static |
No |
Returns |
The file path |
Example |
$file_path = $handler->get_path();
// returns "/path/to/file.txt"
|
Directory handler
The directory handler handles the basic interaction with directories. Each example assumes the
$handler var is the fetched handler. Want to know how to get the handler?
Look at the usage section.
forge($path, $config = array(), $area = null, $content = array())
The forge method returns a new File_Handler_Directory object.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$path |
required |
path to the directory |
$config |
array() |
optional config array |
$area |
null |
File_Area instance |
$content |
array |
the content of the directory |
|
Returns |
Returns a new File_Handler_File object. |
Example |
$handler = File_Handler_Directory::forge('path/to/dir');
|
read($depth = 0, $filters = null)
The read method is a shortcut to File::read_dir.
Static |
No |
Parameters |
Param |
Default |
Description |
$depth |
0 |
depth to recurse directory, 1 is only current and 0 or smaller is unlimited |
$filters |
null |
array of partial regexes or non-array for default |
|
Returns |
Returns directory contents in an array |
Example |
$dir_contents = $handler->read();
|
rename($new_name)
The rename method is a shortcut to File::rename_dir.
Static |
No |
Parameters |
Param |
Default |
Description |
$new_name |
required |
the new directory name |
|
Returns |
boolean, result form rename() |
Example |
$handler->rename('new_name');
|
move($new_path)
The move method is a shortcut to File::move.
Static |
No |
Parameters |
Param |
Default |
Description |
$new_path |
required |
path to new directory, must be valid |
|
Returns |
boolean, result form rename() |
Example |
$handler->move(DOCROOT.'/new/parent/directory/');
|
copy($new_path)
The copy method is a shortcut to File::copy_dir.
Static |
No |
Parameters |
Param |
Default |
Description |
$new_path |
required |
path to directory to copy to, must be valid |
|
Returns |
boolean, result form copy() |
Example |
$handler->copy(DOCROOT.'/directory/');
|
delete($recursive = true, $delete_top = true)
The delete method is a shortcut to File::delete_dir.
Static |
No |
Parameters |
Param |
Default |
Description |
$recursive |
true |
whether to also delete contents of subdirectories |
$delete_top |
true |
whether to delete the parent dir itself when empty |
|
Returns |
true on success |
Example |
$handler->delete();
|
get_permissions()
The get_permissions method is a shortcut to File::get_permissions.
Static |
No |
Returns |
The octal directory permissions |
Example |
$permissions = $handler->get_permissions();
|
get_time($type = 'modified')
The get_time method is a shortcut to File::get_time.
Static |
No |
Parameters |
Param |
Default |
Description |
$type |
'modified' |
What time needs to be returned. Can only be created or modified. |
|
Returns |
The directory's created or modified timestamp |
Example |
$created_at = $handler->get_time('created');
$modified_at = $handler->get_time('modified');
// or short
$modified_at = $handler->get_time();
|
Writing handlers
As mentioned before Fuel comes with two predefined handlers. One for directories and one for
files. By writing your own handlers you can alter the behaviour and add functionalities by
filetype. For instance, when dealing with csv files you might want to auto-parse them when
reading, or be able to fetch a image object from image files.
How to write them...
Handlers are classes that extend the File Handler class (\File_Handler_File).
Here is an example:
<?php
class File_Handler_XML extends \File_Handler_File
{
/**
* Read method specific to how this handler will handle the file contents
*/
public function read()
{
return simplexml_load_file($this->path);
}
}
/* End of file xml.php */
Note the $this->path. This will always hold the path to the current file, even when moving or renaming.
Adding them...
File handlers can be assigned by adding them in the file config.
By adding them to the base config all files from a certain extension wil be fetched as the
desired handler. You can also assign handlers on an area basis by adding them to the area config
you'd like to use them in.
// In app/config/file.php
'base_config' => array(
'file_handlers' => array(
'csv' => 'File_Handler_Csv',
),
),
'areas' => array(
'my_area' => array(
'file_handlers' => array(
'xml' => 'File_Handler_XML',
),
),
),