1. class
  2. Joomla
  3. CMS
  4. Filesystem
  5. Stream

Stream

class Stream extends CMSObject

Joomla! Stream Interface

The Joomla! stream interface is designed to handle files as streams where as the legacy File static class treated files in a rather atomic manner.

Methods

__construct( string $writeprefix = '', string $readprefix = '', array $context = array())

Constructor

string
__toString()

Magic method to convert the object to a string gracefully.

from CMSObject
mixed
def( string $property, mixed $default = null)

Sets a default value if not already assigned

from CMSObject
mixed
get( string $property, mixed $default = null)

Returns a property of the object or the default value if the property is not set.

from CMSObject
array
getProperties( boolean $public = true)

Returns an associative array of object properties.

from CMSObject
string
getError( integer $i = null, boolean $toString = true)

Get the most recent error message.

from CMSObject
array
getErrors()

Return all errors, if any.

from CMSObject
mixed
set( string $property, mixed $value = null)

Modifies a property of the object, creating it if it does not already exist.

from CMSObject
boolean
setProperties( mixed $properties)

Set the object properties based on a named array/hash.

from CMSObject
void
setError( string $error)

Add an error message.

from CMSObject
__destruct()

Destructor

boolean
open( string $filename, string $mode = 'r', boolean $use_include_path = false, resource $context = null, boolean $use_prefix = false, boolean $relative = false, boolean $detectprocessingmode = false)

Generic File Operations

boolean
close()

Attempt to close a file handle

boolean
eof()

Work out if we're at the end of the file for a stream

mixed
filesize()

Retrieve the file size of the path

mixed
gets( integer $length)

Get a line from the stream source.

mixed
read( integer $length)

Read a file

boolean
seek( integer $offset, integer $whence = SEEK_SET)

Seek the file

mixed
tell()

Returns the current position of the file read/write pointer.

boolean
write( string $string, integer $length, integer $chunk)

File write

boolean
chmod( string $filename = '', mixed $mode)

Chmod wrapper

array
get_meta_data()

Get the stream metadata

mixed
_buildContext()

Stream contexts Builds the context from the array

void
setContextOptions( array $context)

Updates the context to the array

void
addContextEntry( string $wrapper, string $name, string $value)

Adds a particular options to the context

void
deleteContextEntry( string $wrapper, string $name)

Deletes a particular setting from a context

mixed
applyContextToStream()

Applies the current context to the stream

mixed
appendFilter( string $filtername, integer $read_write = STREAM_FILTER_READ, array $params = array())

Stream filters Append a filter to the chain

mixed
prependFilter( string $filtername, integer $read_write = STREAM_FILTER_READ, array $params = array())

Prepend a filter to the chain

boolean
removeFilter( resource $resource, boolean $byindex = false)

Remove a filter, either by resource (handed out from the append or prepend function) or via getting the filter list)

mixed
copy( string $src, string $dest, resource $context = null, boolean $use_prefix = true, boolean $relative = false)

Copy a file from src to dest

mixed
move( string $src, string $dest, resource $context = null, boolean $use_prefix = true, boolean $relative = false)

Moves a file

mixed
delete( string $filename, resource $context = null, boolean $use_prefix = true, boolean $relative = false)

Delete a file

mixed
upload( string $src, string $dest, resource $context = null, boolean $use_prefix = true, boolean $relative = false)

Upload a file

boolean
writeFile( string $filename, string $buffer)

Writes a chunk of data to a file.

string
_getFilename( string $filename, string $mode, boolean $use_prefix, boolean $relative)

Determine the appropriate 'filename' of a file

resource
getFileHandle()

Return the internal file handle

Details

__construct( string $writeprefix = '', string $readprefix = '', array $context = array())

Constructor

Parameters

string $writeprefix Prefix of the stream (optional). Unlike the JPATH_*, this has a final path separator!
string $readprefix The read prefix (optional).
array $context The context options (optional).

string __toString()

Magic method to convert the object to a string gracefully.

Return Value

string The classname.

mixed def( string $property, mixed $default = null)

Sets a default value if not already assigned

Parameters

string $property The name of the property.
mixed $default The default value.

Return Value

mixed

mixed get( string $property, mixed $default = null)

Returns a property of the object or the default value if the property is not set.

Parameters

string $property The name of the property.
mixed $default The default value.

Return Value

mixed The value of the property.

See also

CMSObject::getProperties()

array getProperties( boolean $public = true)

Returns an associative array of object properties.

Parameters

boolean $public If true, returns only the public properties.

Return Value

array

See also

CMSObject::get()

string getError( integer $i = null, boolean $toString = true)

Get the most recent error message.

Parameters

integer $i Option error index.
boolean $toString Indicates if JError objects should return their error message.

Return Value

string Error message

See also

JError

array getErrors()

Return all errors, if any.

Return Value

array Array of error messages or JErrors.

See also

JError

mixed set( string $property, mixed $value = null)

Modifies a property of the object, creating it if it does not already exist.

Parameters

string $property The name of the property.
mixed $value The value of the property to set.

Return Value

mixed Previous value of the property.

boolean setProperties( mixed $properties)

Set the object properties based on a named array/hash.

Parameters

mixed $properties Either an associative array or another object.

Return Value

boolean

See also

CMSObject::set()

void setError( string $error)

Add an error message.

Parameters

string $error Error message.

Return Value

void

See also

JError

__destruct()

Destructor

boolean open( string $filename, string $mode = 'r', boolean $use_include_path = false, resource $context = null, boolean $use_prefix = false, boolean $relative = false, boolean $detectprocessingmode = false)

Generic File Operations

Open a stream with some lazy loading smarts

Parameters

string $filename Filename
string $mode Mode string to use
boolean $use_include_path Use the PHP include path
resource $context Context to use when opening
boolean $use_prefix Use a prefix to open the file
boolean $relative Filename is a relative path (if false, strips JPATH_ROOT to make it relative)
boolean $detectprocessingmode Detect the processing method for the file and use the appropriate function to handle output automatically

Return Value

boolean

boolean close()

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

Return Value

boolean

boolean eof()

Work out if we're at the end of the file for a stream

Return Value

boolean

mixed filesize()

Retrieve the file size of the path

Return Value

mixed

mixed gets( integer $length)

Get a line from the stream source.

Parameters

integer $length The number of bytes (optional) to read.

Return Value

mixed

mixed read( integer $length)

Read a file

Handles user space streams appropriately otherwise any read will return 8192

Parameters

integer $length Length of data to read

Return Value

mixed

boolean seek( integer $offset, integer $whence = SEEK_SET)

Seek the file

Note: the return value is different to that of fseek

Parameters

integer $offset Offset to use when seeking.
integer $whence Seek mode to use.

Return Value

boolean True on success, false on failure

mixed tell()

Returns the current position of the file read/write pointer.

Return Value

mixed

boolean write( string $string, integer $length, integer $chunk)

File write

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

Parameters

string $string &$string Reference to the string to write.
integer $length Length of the string to write.
integer $chunk Size of chunks to write in.

Return Value

boolean

boolean chmod( string $filename = '', mixed $mode)

Chmod wrapper

Parameters

string $filename File name.
mixed $mode Mode to use.

Return Value

boolean

array get_meta_data()

Get the stream metadata

Return Value

array header/metadata

mixed _buildContext()

Stream contexts Builds the context from the array

Return Value

mixed

void setContextOptions( array $context)

Updates the context to the array

Format is the same as the options for streamcontextcreate

Parameters

array $context Options to create the context with

Return Value

void

void addContextEntry( string $wrapper, string $name, string $value)

Adds a particular options to the context

Parameters

string $wrapper The wrapper to use
string $name The option to set
string $value The value of the option

Return Value

void

void deleteContextEntry( string $wrapper, string $name)

Deletes a particular setting from a context

Parameters

string $wrapper The wrapper to use
string $name The option to unset

Return Value

void

mixed applyContextToStream()

Applies the current context to the stream

Use this to change the values of the context after you've opened a stream

Return Value

mixed

mixed appendFilter( string $filtername, integer $read_write = STREAM_FILTER_READ, array $params = array())

Stream filters Append a filter to the chain

Parameters

string $filtername The key name of the filter.
integer $read_write Optional. Defaults to STREAMFILTERREAD.
array $params An array of params for the streamfilterappend call.

Return Value

mixed

mixed prependFilter( string $filtername, integer $read_write = STREAM_FILTER_READ, array $params = array())

Prepend a filter to the chain

Parameters

string $filtername The key name of the filter.
integer $read_write Optional. Defaults to STREAMFILTERREAD.
array $params An array of params for the streamfilterprepend call.

Return Value

mixed

boolean removeFilter( resource $resource, boolean $byindex = false)

Remove a filter, either by resource (handed out from the append or prepend function) or via getting the filter list)

Parameters

resource $resource &$resource The resource.
boolean $byindex The index of the filter.

Return Value

boolean Result of operation

mixed copy( string $src, string $dest, resource $context = null, boolean $use_prefix = true, boolean $relative = false)

Copy a file from src to dest

Parameters

string $src The file path to copy from.
string $dest The file path to copy to.
resource $context A valid context resource (optional) created with streamcontextcreate.
boolean $use_prefix Controls the use of a prefix (optional).
boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.

Return Value

mixed

mixed move( string $src, string $dest, resource $context = null, boolean $use_prefix = true, boolean $relative = false)

Moves a file

Parameters

string $src The file path to move from.
string $dest The file path to move to.
resource $context A valid context resource (optional) created with streamcontextcreate.
boolean $use_prefix Controls the use of a prefix (optional).
boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.

Return Value

mixed

mixed delete( string $filename, resource $context = null, boolean $use_prefix = true, boolean $relative = false)

Delete a file

Parameters

string $filename The file path to delete.
resource $context A valid context resource (optional) created with streamcontextcreate.
boolean $use_prefix Controls the use of a prefix (optional).
boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.

Return Value

mixed

mixed upload( string $src, string $dest, resource $context = null, boolean $use_prefix = true, boolean $relative = false)

Upload a file

Parameters

string $src The file path to copy from (usually a temp folder).
string $dest The file path to copy to.
resource $context A valid context resource (optional) created with streamcontextcreate.
boolean $use_prefix Controls the use of a prefix (optional).
boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.

Return Value

mixed

boolean writeFile( string $filename, string $buffer)

Writes a chunk of data to a file.

Parameters

string $filename The file name.
string $buffer &$buffer The data to write to the file.

Return Value

boolean

string _getFilename( string $filename, string $mode, boolean $use_prefix, boolean $relative)

Determine the appropriate 'filename' of a file

Parameters

string $filename Original filename of the file
string $mode Mode string to retrieve the filename
boolean $use_prefix Controls the use of a prefix
boolean $relative Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.

Return Value

string

resource getFileHandle()

Return the internal file handle

Return Value

resource File handler