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',
		),
	),
),