Source for file stream.php
Documentation is available at stream.php
* @package Joomla.Platform
* @copyright Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE
* Joomla! Stream Interface
* The Joomla! stream interface is designed to handle files as streams
* where as the legacy JFile static class treated files in a rather
* @package Joomla.Platform
* @note This class adheres to the stream wrapper operations:
* @see http://php.net/manual/en/function.stream-get-wrappers.php
* @see http://php.net/manual/en/intro.stream.php PHP Stream Manual
* @see http://php.net/manual/en/wrappers.php Stream Wrappers
* @see http://php.net/manual/en/filters.php Stream Filters
* @see http://php.net/manual/en/transports.php Socket Transports (used by some options, particularly HTTP proxy)
* Prefix of the connection for writing
* Prefix of the connection for reading
* If a scheme is detected, fopen will be defaulted
* To use compression with a network stream use a filter
* Filters applied to the current stream
* Context to use when opening the connection
* Context options; used to rebuild the context
* The mode under which the file was opened
* @param string $writeprefix Prefix of the stream (optional). Unlike the JPATH_*, this has a final path separator!
* @param string $readprefix The read prefix (optional).
* @param array $context The context options (optional).
public function __construct($writeprefix =
'', $readprefix =
'', $context =
array())
// Attempt to close on destruction if there is a file handle
* Generic File Operations
* Open a stream with some lazy loading smarts
* @param string $filename Filename
* @param string $mode Mode string to use
* @param boolean $use_include_path Use the PHP include path
* @param resource $context Context to use when opening
* @param boolean $use_prefix Use a prefix to open the file
* @param boolean $relative Filename is a relative path (if false, strips JPATH_ROOT to make it relative)
* @param boolean $detectprocessingmode Detect the processing method for the file and use the appropriate function
* to handle output automatically
public function open($filename, $mode =
'r', $use_include_path =
false, $context =
null,
$use_prefix =
false, $relative =
false, $detectprocessingmode =
false)
$filename =
$this->_getFilename($filename, $mode, $use_prefix, $relative);
if (isset
($url['scheme']))
// If we're dealing with a Joomla! stream, load it
require_once __DIR__ .
'/streams/' .
$url['scheme'] .
'.php';
// We have a scheme! force the method to be f
elseif ($detectprocessingmode)
$php_errormsg =
'Error Unknown whilst opening a file';
$track_errors =
ini_get('track_errors');
// Decide which context to use:
// Gzip doesn't support contexts or streams
$this->fh =
gzopen($filename, $mode, $use_include_path);
// Bzip2 is much like gzip except it doesn't use the include path
// Fopen can handle streams
// One supplied at open; overrides everything
$this->fh =
fopen($filename, $mode, $use_include_path, $context);
// One provided at initialisation
$this->fh =
fopen($filename, $mode, $use_include_path, $this->context);
// No context; all defaults
$this->fh =
fopen($filename, $mode, $use_include_path);
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* Attempt to close a file handle
* Will return false if it failed and true on success
* If the file is not open the system will return true, this function destroys the file handle as well
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_FILE_NOT_OPEN'));
$php_errormsg =
'Error Unknown';
$track_errors =
ini_get('track_errors');
// If we wrote, chmod the file after it's closed
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* Work out if we're at the end of the file for a stream
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_FILE_NOT_OPEN'));
$track_errors =
ini_get('track_errors');
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* Retrieve the file size of the path
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_FILE_NOT_OPEN'));
$track_errors =
ini_get('track_errors');
// Store the error in case we need it.
$tmp_error =
$php_errormsg;
// Use the php_errormsg from before
// Error but nothing from php? How strange! Create our own
// Restore error tracking to what it was before.
ini_set('track_errors', $track_errors);
* Get a line from the stream source.
* @param integer $length The number of bytes (optional) to read.
public function gets($length =
0)
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_FILE_NOT_OPEN'));
$php_errormsg =
'Error Unknown';
$track_errors =
ini_get('track_errors');
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* Handles user space streams appropriately otherwise any read will return 8192
* @param integer $length Length of data to read
* @see http://php.net/manual/en/function.fread.php
public function read($length =
0)
// Set it to the biggest and then wait until eof
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_FILE_NOT_OPEN'));
$php_errormsg =
'Error Unknown';
$track_errors =
ini_get('track_errors');
// Do chunked reads where relevant
// If it's the end of the file then we've nothing left to read; reset remaining and len
while ($remaining ||
!$length);
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* Note: the return value is different to that of fseek
* @param integer $offset Offset to use when seeking.
* @param integer $whence Seek mode to use.
* @return boolean True on success, false on failure
* @see http://php.net/manual/en/function.fseek.php
public function seek($offset, $whence =
SEEK_SET)
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_FILE_NOT_OPEN'));
$track_errors =
ini_get('track_errors');
$res =
gzseek($this->fh, $offset, $whence);
$res =
fseek($this->fh, $offset, $whence);
// Seek, interestingly, returns 0 on success or -1 on failure.
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* Returns the current position of the file read/write pointer.
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_FILE_NOT_OPEN'));
$track_errors =
ini_get('track_errors');
// May return 0 so check if it's really false
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* Whilst this function accepts a reference, the underlying fwrite
* will do a copy! This will roughly double the memory allocation for
* any write you do. Specifying chunked will get around this by only
* writing in specific chunk sizes. This defaults to 8192 which is a
* sane number to use most of the time (change the default with
* JStream::set('chunksize', newsize);)
* Note: This doesn't support gzip/bzip2 writing like reading does
* @param string &$string Reference to the string to write.
* @param integer $length Length of the string to write.
* @param integer $chunk Size of chunks to write in.
* @see http://php.net/manual/en/function.fwrite.php
public function write(&$string, $length =
0, $chunk =
0)
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_FILE_NOT_OPEN'));
// If the length isn't set, set it to the length of the string.
// If the chunk isn't set, set it to the default.
$track_errors =
ini_get('track_errors');
// If the amount remaining is greater than the chunk size, then use the chunk
$amount =
($remaining >
$chunk) ?
$chunk :
$remaining;
// Returns false on error or the number of bytes written
// Restore error tracking to what it was before.
ini_set('track_errors', $track_errors);
* @param string $filename File name.
* @param mixed $mode Mode to use.
public function chmod($filename =
'', $mode =
0)
// If no mode is set use the default
$track_errors =
ini_get('track_errors');
// Scheme specific options; ftp's chmod support is fun.
$res =
chmod($filename, $mode);
// Seek, interestingly, returns 0 on success or -1 on failure
// Restore error tracking to what it was before.
ini_set('track_errors', $track_errors);
* Get the stream metadata
* @return array header/metadata
* @see http://php.net/manual/en/function.stream-get-meta-data.php
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_FILE_NOT_OPEN'));
* Builds the context from the array
// According to the manual this always works!
* Updates the context to the array
* Format is the same as the options for stream_context_create
* @param array $context Options to create the context with
* @see http://php.net/stream_context_create
* Adds a particular options to the context
* @param string $wrapper The wrapper to use
* @param string $name The option to set
* @param string $value The value of the option
* @see http://php.net/stream_context_create Stream Context Creation
* @see http://php.net/manual/en/context.php Context Options for various streams
* Deletes a particular setting from a context
* @param string $wrapper The wrapper to use
* @param string $name The option to unset
* @see http://php.net/stream_context_create
// Check whether the wrapper is set
// Check that entry is set for that wrapper
// Check that there are still items there
// Clean up an empty wrapper context option
// Rebuild the context and apply it to the stream
* Applies the current context to the stream
* Use this to change the values of the context after you've opened a stream
$php_errormsg =
'Unknown error setting context option';
$track_errors =
ini_get('track_errors');
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* Append a filter to the chain
* @param string $filtername The key name of the filter.
* @param integer $read_write Optional. Defaults to STREAM_FILTER_READ.
* @param array $params An array of params for the stream_filter_append call.
* @see http://php.net/manual/en/function.stream-filter-append.php
public function appendFilter($filtername, $read_write =
STREAM_FILTER_READ, $params =
array())
$track_errors =
ini_get('track_errors');
if (!$res &&
$php_errormsg)
// Restore error tracking to what it was before.
ini_set('track_errors', $track_errors);
* Prepend a filter to the chain
* @param string $filtername The key name of the filter.
* @param integer $read_write Optional. Defaults to STREAM_FILTER_READ.
* @param array $params An array of params for the stream_filter_prepend call.
* @see http://php.net/manual/en/function.stream-filter-prepend.php
public function prependFilter($filtername, $read_write =
STREAM_FILTER_READ, $params =
array())
$track_errors =
ini_get('track_errors');
if (!$res &&
$php_errormsg)
// Restore error tracking to what it was before.
ini_set('track_errors', $track_errors);
* Remove a filter, either by resource (handed out from the append or prepend function)
* or via getting the filter list)
* @param resource &$resource The resource.
* @param boolean $byindex The index of the filter.
* @return boolean Result of operation
$track_errors =
ini_get('track_errors');
if ($res &&
$php_errormsg)
// Restore error tracking to what it was before.
ini_set('track_errors', $track_errors);
* Copy a file from src to dest
* @param string $src The file path to copy from.
* @param string $dest The file path to copy to.
* @param resource $context A valid context resource (optional) created with stream_context_create.
* @param boolean $use_prefix Controls the use of a prefix (optional).
* @param boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
public function copy($src, $dest, $context =
null, $use_prefix =
true, $relative =
false)
$track_errors =
ini_get('track_errors');
$chmodDest =
$this->_getFilename($dest, 'w', $use_prefix, $relative);
// Since we're going to open the file directly we need to get the filename.
// We need to use the same prefix so force everything to write.
$src =
$this->_getFilename($src, 'w', $use_prefix, $relative);
$dest =
$this->_getFilename($dest, 'w', $use_prefix, $relative);
// Use the provided context
$res =
@copy($src, $dest, $context);
// Use the objects context
$res =
@copy($src, $dest);
if (!$res &&
$php_errormsg)
$this->chmod($chmodDest);
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* @param string $src The file path to move from.
* @param string $dest The file path to move to.
* @param resource $context A valid context resource (optional) created with stream_context_create.
* @param boolean $use_prefix Controls the use of a prefix (optional).
* @param boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
public function move($src, $dest, $context =
null, $use_prefix =
true, $relative =
false)
$track_errors =
ini_get('track_errors');
$src =
$this->_getFilename($src, 'w', $use_prefix, $relative);
$dest =
$this->_getFilename($dest, 'w', $use_prefix, $relative);
// Use the provided context
$res =
@rename($src, $dest, $context);
// Use the object's context
if (!$res &&
$php_errormsg)
// Restore error tracking to what it was before
ini_set('track_errors', $track_errors);
* @param string $filename The file path to delete.
* @param resource $context A valid context resource (optional) created with stream_context_create.
* @param boolean $use_prefix Controls the use of a prefix (optional).
* @param boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
public function delete($filename, $context =
null, $use_prefix =
true, $relative =
false)
$track_errors =
ini_get('track_errors');
$filename =
$this->_getFilename($filename, 'w', $use_prefix, $relative);
// Use the provided context
$res =
@unlink($filename, $context);
// Use the object's context
if (!$res &&
$php_errormsg)
// Restore error tracking to what it was before.
ini_set('track_errors', $track_errors);
* @param string $src The file path to copy from (usually a temp folder).
* @param string $dest The file path to copy to.
* @param resource $context A valid context resource (optional) created with stream_context_create.
* @param boolean $use_prefix Controls the use of a prefix (optional).
* @param boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
public function upload($src, $dest, $context =
null, $use_prefix =
true, $relative =
false)
// Make sure it's an uploaded file
return $this->copy($src, $dest, $context, $use_prefix, $relative);
$this->setError(JText::_('JLIB_FILESYSTEM_ERROR_STREAMS_NOT_UPLOADED_FILE'));
* Writes a chunk of data to a file.
* @param string $filename The file name.
* @param string &$buffer The data to write to the file.
public function writeFile($filename, &$buffer)
if ($this->open($filename, 'w'))
$result =
$this->write($buffer);
* Determine the appropriate 'filename' of a file
* @param string $filename Original filename of the file
* @param string $mode Mode string to retrieve the filename
* @param boolean $use_prefix Controls the use of a prefix
* @param boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
public function _getFilename($filename, $mode, $use_prefix, $relative)
// Get rid of binary or t, should be at the end of the string
$tmode =
trim($mode, 'btf123456789');
// Check if it's a write mode then add the appropriate prefix
// Get rid of JPATH_ROOT (legacy compat) along the way
* Return the internal file handle
Documentation generated on Tue, 19 Nov 2013 15:14:28 +0100 by phpDocumentor 1.4.3