summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDerek Jones <derek.jones@ellislab.com>2013-07-21 20:03:33 +0200
committerDerek Jones <derek.jones@ellislab.com>2013-07-21 20:03:33 +0200
commit46c95474c9c2a310351934594a34f2f827e1cc9a (patch)
tree5550cee7c3b900463b36ded0def33094b74a46be
parentc43dc1e6b34104c4c060f2e0fc07ea61cabbf6c1 (diff)
Update File helper docs
-rw-r--r--user_guide_src/source/helpers/file_helper.rst193
1 files changed, 91 insertions, 102 deletions
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
+
+ <div class="custom-index container"></div>
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 <http://php.net/fopen>`_
-for mode options.
+ The default mode is 'wb'. Please see the `PHP user guide <http://php.net/fopen>`_
+ 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