From 46c95474c9c2a310351934594a34f2f827e1cc9a Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Sun, 21 Jul 2013 11:03:33 -0700 Subject: Update File helper docs --- user_guide_src/source/helpers/file_helper.rst | 193 ++++++++++++-------------- 1 file changed, 91 insertions(+), 102 deletions(-) (limited to 'user_guide_src/source') diff --git a/user_guide_src/source/helpers/file_helper.rst b/user_guide_src/source/helpers/file_helper.rst index be451db4d..4d225d278 100644 --- a/user_guide_src/source/helpers/file_helper.rst +++ b/user_guide_src/source/helpers/file_helper.rst @@ -4,7 +4,12 @@ File Helper The File Helper file contains functions that assist in working with files. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + +
Loading this Helper =================== @@ -13,121 +18,114 @@ This helper is loaded using the following code:: $this->load->helper('file'); +Available Functions +=================== + The following functions are available: -read_file() -=========== .. function:: read_file($file) :param string $file: File path :returns: string or FALSE on failure -Returns the data contained in the file specified in the path. + Returns the data contained in the file specified in the path. -Example:: + Example:: - $string = read_file('./path/to/file.php'); + $string = read_file('./path/to/file.php'); -The path can be a relative or full server path. Returns FALSE (boolean) on failure. + The path can be a relative or full server path. Returns FALSE (boolean) on failure. -.. note:: The path is relative to your main site index.php file, NOT your - controller or view files. CodeIgniter uses a front controller so paths - are always relative to the main site index. + .. note:: The path is relative to your main site index.php file, NOT your + controller or view files. CodeIgniter uses a front controller so paths + are always relative to the main site index. -.. note:: This function is DEPRECATED. Use the native ``file_get_contents()`` - instead. + .. note:: This function is DEPRECATED. Use the native ``file_get_contents()`` + instead. -.. important:: If your server is running an **open_basedir** restriction this - function might not work if you are trying to access a file above the - calling script. + .. important:: If your server is running an **open_basedir** restriction this + function might not work if you are trying to access a file above the + calling script. -write_file() -============ -.. function:: write_file($path, $data, $mode = 'wb') +.. function:: write_file($path, $data[, $mode = 'wb']) :param string $path: File path :param string $data: Data to write to file :param string $mode: ``fopen()`` mode :returns: bool -Writes data to the file specified in the path. If the file does not exist then the -function will create it. + Writes data to the file specified in the path. If the file does not exist then the + function will create it. -Example:: + Example:: - $data = 'Some file data'; - if ( ! write_file('./path/to/file.php', $data)) - {      - echo 'Unable to write the file'; - } - else - {      - echo 'File written!'; - } + $data = 'Some file data'; + if ( ! write_file('./path/to/file.php', $data)) + {      + echo 'Unable to write the file'; + } + else + {      + echo 'File written!'; + } -You can optionally set the write mode via the third parameter:: + You can optionally set the write mode via the third parameter:: - write_file('./path/to/file.php', $data, 'r+'); + write_file('./path/to/file.php', $data, 'r+'); -The default mode is 'wb'. Please see the `PHP user guide `_ -for mode options. + The default mode is 'wb'. Please see the `PHP user guide `_ + for mode options. -.. note: In order for this function to write data to a file, its permissions must - be set such that it is writable (666, 777, etc.). If the file does not - already exist, the directory containing it must be writable. + .. note: In order for this function to write data to a file, its permissions must + be set such that it is writable (666, 777, etc.). If the file does not + already exist, the directory containing it must be writable. -.. note:: The path is relative to your main site index.php file, NOT your - controller or view files. CodeIgniter uses a front controller so paths - are always relative to the main site index. + .. note:: The path is relative to your main site index.php file, NOT your + controller or view files. CodeIgniter uses a front controller so paths + are always relative to the main site index. -.. note:: This function acquires an exclusive lock on the file while writing to it. + .. note:: This function acquires an exclusive lock on the file while writing to it. -delete_files() -============== -.. function:: delete_files($path, $del_dir = FALSE, $htdocs = FALSE) +.. function:: delete_files($path[, $del_dir = FALSE[, $htdocs = FALSE]]) :param string $path: Directory path :param bool $del_dir: Whether to also delete directories :param bool $htdocs: Whether to skip deleting .htaccess and index page files :returns: bool -Deletes ALL files contained in the supplied path. + Deletes ALL files contained in the supplied path. -Example:: + Example:: - delete_files('./path/to/directory/'); + delete_files('./path/to/directory/'); -If the second parameter is set to TRUE, any directories contained within the supplied -root path will be deleted as well. + If the second parameter is set to TRUE, any directories contained within the supplied + root path will be deleted as well. -Example:: + Example:: - delete_files('./path/to/directory/', TRUE); + delete_files('./path/to/directory/', TRUE); -.. note:: The files must be writable or owned by the system in order to be deleted. + .. note:: The files must be writable or owned by the system in order to be deleted. -get_filenames() -=============== -.. function:: get_filenames($source_dir, $include_path = FALSE) +.. function:: get_filenames($source_dir[, $include_path = FALSE]) :param string $source_dir: Directory path :param bool $include_path: Whether to include the path as part of the filenames :returns: array -Takes a server path as input and returns an array containing the names of all files -contained within it. The file path can optionally be added to the file names by setting -the second parameter to TRUE. + Takes a server path as input and returns an array containing the names of all files + contained within it. The file path can optionally be added to the file names by setting + the second parameter to TRUE. -Example:: + Example:: - $controllers = get_filenames(APPPATH.'controllers/'); + $controllers = get_filenames(APPPATH.'controllers/'); -get_dir_file_info() -=================== .. function:: get_dir_file_info($source_dir, $top_level_only) @@ -136,81 +134,72 @@ get_dir_file_info() (excluding sub-directories) :returns: array -Reads the specified directory and builds an array containing the filenames, filesize, -dates, and permissions. Sub-folders contained within the specified path are only read -if forced by sending the second parameter to FALSE, as this can be an intensive -operation. + Reads the specified directory and builds an array containing the filenames, filesize, + dates, and permissions. Sub-folders contained within the specified path are only read + if forced by sending the second parameter to FALSE, as this can be an intensive + operation. -Example:: + Example:: - $models_info = get_dir_file_info(APPPATH.'models/'); + $models_info = get_dir_file_info(APPPATH.'models/'); -get_file_info() -=============== -.. function: get_file_info($file, $returned_values = array('name', 'server_path', 'size', 'date')) +.. function:: get_file_info($file[, $returned_values = array('name', 'server_path', 'size', 'date')]) :param string $file: File path :param array $returned_values: What type of info to return :returns: array or FALSE on failure -Given a file and path, returns (optionally) the *name*, *path*, *size* and *date modified* -information attributes for a file. Second parameter allows you to explicitly declare what -information you want returned. - -Valid ``$returned_values`` options are: `name`, `size`, `date`, `readable`, `writeable`, -`executable` and `fileperms`. + Given a file and path, returns (optionally) the *name*, *path*, *size* and *date modified* + information attributes for a file. Second parameter allows you to explicitly declare what + information you want returned. -.. note:: The *writable* attribute is checked via PHP's ``is_writeable()`` function, which - known to have issues on the IIS webserver. Consider using *fileperms* instead, - which returns information from PHP's ``fileperms()`` function. + Valid ``$returned_values`` options are: `name`, `size`, `date`, `readable`, `writeable`, + `executable` and `fileperms`. -get_mime_by_extension() -======================= + .. note:: The *writable* attribute is checked via PHP's ``is_writeable()`` function, which + known to have issues on the IIS webserver. Consider using *fileperms* instead, + which returns information from PHP's ``fileperms()`` function. .. function:: get_mime_by_extension($filename) :param string $filename: File name :returns: string or FALSE on failure -Translates a filename extension into a MIME type based on *config/mimes.php*. -Returns FALSE if it can't determine the type, or read the MIME config file. + Translates a filename extension into a MIME type based on *config/mimes.php*. + Returns FALSE if it can't determine the type, or read the MIME config file. -:: + :: - $file = 'somefile.png'; - echo $file.' is has a mime type of '.get_mime_by_extension($file); + $file = 'somefile.png'; + echo $file.' is has a mime type of '.get_mime_by_extension($file); -.. note:: This is not an accurate way of determining file MIME types, and - is here strictly for convenience. It should not be used for security - purposes. + .. note:: This is not an accurate way of determining file MIME types, and + is here strictly for convenience. It should not be used for security + purposes. -symbolic_permissions() -====================== .. function:: symbolic_permissions($perms) :param int $perms: Permissions :returns: string -Takes numeric permissions (such as is returned by ``fileperms()``) and returns -standard symbolic notation of file permissions. + Takes numeric permissions (such as is returned by ``fileperms()``) and returns + standard symbolic notation of file permissions. -:: + :: - echo symbolic_permissions(fileperms('./index.php')); // -rw-r--r-- + echo symbolic_permissions(fileperms('./index.php')); // -rw-r--r-- -octal_permissions() -=================== .. function:: octal_permissions($perms) :param int $perms: Permissions :returns: string -Takes numeric permissions (such as is returned by ``fileperms()``) and returns -a three character octal notation of file permissions. + Takes numeric permissions (such as is returned by ``fileperms()``) and returns + a three character octal notation of file permissions. -:: + :: - echo octal_permissions(fileperms('./index.php')); // 644 \ No newline at end of file + echo octal_permissions(fileperms('./index.php')); // 644 \ No newline at end of file -- cgit v1.2.3-24-g4f1b