Stream
Extends CMSObjectJoomla! 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.
note |
This class adheres to the stream wrapper operations: |
---|---|
link |
PHP Stream Manual Stream Wrappers Stream Filters Socket Transports (used by some options, particularly HTTP proxy) |
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream instead. |
package |
Joomla CMS |
Methods
__construct
Constructor
__construct( writeprefix = '', readprefix = '', mixed||string|int context = []) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::__construct() instead. |
Arguments
- writeprefix
string
Prefix of the stream (optional). Unlike the JPATH_*, this has a final path separator!- readprefix
string
The read prefix (optional).- context
array<string|int, mixed>
The context options (optional).
Response
mixed
__destruct
Destructor
__destruct() :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::__destruct() instead. |
Response
mixed
__toString
Magic method to convert the object to a string gracefully.
__toString() :
since |
1.7.0 |
---|---|
deprecated |
4.3 will be removed in 6.0 Classes should provide their own __toString() implementation. |
Response
string
The classname.
_buildContext
Stream contexts Builds the context from the array
_buildContext() :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::_buildContext() instead. |
Response
void
_getFilename
Determine the appropriate 'filename' of a file
_getFilename( filename, mode, usePrefix, relative) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::_getFilename() instead. |
Arguments
- filename
string
Original filename of the file- mode
string
Mode string to retrieve the filename- usePrefix
bool
Controls the use of a prefix- relative
bool
Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
Response
string
addContextEntry
Adds a particular options to the context
addContextEntry( wrapper, name, value) :
link |
Stream Context Creation Context Options for various streams |
---|---|
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::addContextEntry() instead. |
Arguments
- wrapper
string
The wrapper to use- name
string
The option to set- value
string
The value of the option
Response
void
appendFilter
Stream filters Append a filter to the chain
appendFilter( filterName, readWrite = STREAM_FILTER_READ, mixed||string|int params = []) :
link | |
---|---|
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::appendFilter() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- filterName
string
The key name of the filter.- readWrite
int
Optional. Defaults to STREAM_FILTER_READ.- params
array<string|int, mixed>
An array of params for the stream_filter_append call.
Response
mixed
applyContextToStream
Applies the current context to the stream
applyContextToStream() :
Use this to change the values of the context after you've opened a stream
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::applyContextToStream() instead. The framework class throws Exceptions in case of error which you have to catch. |
Response
mixed
chmod
Chmod wrapper
chmod( filename = '', mode) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::chmod() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- filename
string
File name.- mode
mixed
Mode to use.
Response
bool
close
Attempt to close a file handle
close() :
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
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::close() instead. The framework class throws Exceptions in case of error which you have to catch. |
Response
bool
copy
Copy a file from src to dest
copy( src, dest, context = null, usePrefix = true, relative = false) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::copy() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- src
string
The file path to copy from.- dest
string
The file path to copy to.- context
resource
A valid context resource (optional) created with stream_context_create.- usePrefix
bool
Controls the use of a prefix (optional).- relative
bool
Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
Response
mixed
def
Sets a default value if not already assigned
def( property, default = null) :
since |
1.7.0 |
---|---|
deprecated |
4.3.0 will be removed in 6.0 Defining dynamic properties should not be used anymore |
Arguments
- property
string
The name of the property.- default
mixed
The default value.
Response
mixed
delete
Delete a file
delete( filename, context = null, usePrefix = true, relative = false) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::delete() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- filename
string
The file path to delete.- context
resource
A valid context resource (optional) created with stream_context_create.- usePrefix
bool
Controls the use of a prefix (optional).- relative
bool
Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
Response
mixed
deleteContextEntry
Deletes a particular setting from a context
deleteContextEntry( wrapper, name) :
link | |
---|---|
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::deleteContextEntry() instead. |
Arguments
- wrapper
string
The wrapper to use- name
string
The option to unset
Response
void
eof
Work out if we're at the end of the file for a stream
eof() :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::eof() instead. The framework class throws Exceptions in case of error which you have to catch. |
Response
bool
filesize
Retrieve the file size of the path
filesize() :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::filesize() instead. The framework class throws Exceptions in case of error which you have to catch. |
Response
mixed
get
Returns a property of the object or the default value if the property is not set.
get( property, default = null) :
since |
1.7.0 |
---|---|
see | CMSObject::getProperties() |
deprecated |
4.3.0 will be removed in 6.0 Create a proper getter function for the property |
Arguments
- property
string
The name of the property.- default
mixed
The default value.
Response
mixed
The value of the property.
get_meta_data
Get the stream metadata
get_meta_data() : array|bool
link | |
---|---|
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::get_meta_data() instead. The framework class throws Exceptions in case of error which you have to catch. |
Response
array<string|int, mixed>|bool
header/metadata
getError
Get the most recent error message.
getError( i = null, toString = true) :
since |
1.7.0 |
---|---|
deprecated |
3.1.4 will be removed in 6.0 Will be removed without replacement Catch thrown Exceptions instead of getError |
Arguments
- i
int
Option error index.- toString
bool
Indicates if Exception objects should return their error message.
Response
string
Error message
getErrors
Return all errors, if any.
getErrors() : mixed||string|int
since |
1.7.0 |
---|---|
deprecated |
3.1.4 will be removed in 6.0 Will be removed without replacement Catch thrown Exceptions instead of getErrors |
Response
array<string|int, mixed>
Array of error messages.
getFileHandle
Return the internal file handle
getFileHandle() :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::getFileHandle() instead. |
Response
resource
File handler
getProperties
Returns an associative array of object properties.
getProperties( public = true) : mixed||string|int
since |
1.7.0 |
---|---|
see | CMSObject::get() |
deprecated |
4.3.0 will be removed in 6.0 Create a proper getter function for the property |
Arguments
- public
bool
If true, returns only the public properties.
Response
array<string|int, mixed>
gets
Get a line from the stream source.
gets( length) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::gets() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- length
int
The number of bytes (optional) to read.
Response
mixed
move
Moves a file
move( src, dest, context = null, usePrefix = true, relative = false) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::move() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- src
string
The file path to move from.- dest
string
The file path to move to.- context
resource
A valid context resource (optional) created with stream_context_create.- usePrefix
bool
Controls the use of a prefix (optional).- relative
bool
Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
Response
mixed
open
Generic File Operations
open( filename, mode = 'r', useIncludePath = false, context = null, usePrefix = false, relative = false, detectProcessingMode = false) :
Open a stream with some lazy loading smarts
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::open() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- filename
string
Filename- mode
string
Mode string to use- useIncludePath
bool
Use the PHP include path- context
resource
Context to use when opening- usePrefix
bool
Use a prefix to open the file- relative
bool
Filename is a relative path (if false, strips JPATH_ROOT to make it relative)- detectProcessingMode
bool
Detect the processing method for the file and use the appropriate function to handle output automatically
Response
bool
prependFilter
Prepend a filter to the chain
prependFilter( filterName, readWrite = STREAM_FILTER_READ, mixed||string|int params = []) :
link | |
---|---|
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::prependFilter() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- filterName
string
The key name of the filter.- readWrite
int
Optional. Defaults to STREAM_FILTER_READ.- params
array<string|int, mixed>
An array of params for the stream_filter_prepend call.
Response
mixed
read
Read a file
read( length) :
Handles user space streams appropriately otherwise any read will return 8192
link | |
---|---|
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::read() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- length
int
Length of data to read
Response
mixed
removeFilter
Remove a filter, either by resource (handed out from the append or prepend function) or via getting the filter list)
removeFilter( &resource, byindex = false) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::removeFilter() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- resource
resource
The resource.- byindex
bool
The index of the filter.
Response
bool
Result of operation
seek
Seek the file
seek( offset, whence = SEEK_SET) :
Note: the return value is different to that of fseek
link | |
---|---|
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::seek() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- offset
int
Offset to use when seeking.- whence
int
Seek mode to use.
Response
bool
True on success, false on failure
set
Modifies a property of the object, creating it if it does not already exist.
set( property, value = null) :
since |
1.7.0 |
---|---|
deprecated |
4.3.0 will be removed in 6.0 Create a proper setter function for the property |
Arguments
- property
string
The name of the property.- value
mixed
The value of the property to set.
Response
mixed
Previous value of the property.
setContextOptions
Updates the context to the array
setContextOptions(mixed||string|int context) :
Format is the same as the options for stream_context_create
link | |
---|---|
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::setContextOptions() instead. |
Arguments
- context
array<string|int, mixed>
Options to create the context with
Response
void
setError
Add an error message.
setError( error) :
since |
1.7.0 |
---|---|
deprecated |
3.1.4 will be removed in 6.0 Will be removed without replacement Throw an Exception instead of using setError |
Arguments
- error
string
Error message.
Response
void
setProperties
Set the object properties based on a named array/hash.
setProperties( properties) :
since |
1.7.0 |
---|---|
see | CMSObject::set() |
deprecated |
4.3.0 will be removed in 6.0 Create a proper setter function for the property |
Arguments
- properties
mixed
Either an associative array or another object.
Response
bool
tell
Returns the current position of the file read/write pointer.
tell() :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::tell() instead. The framework class throws Exceptions in case of error which you have to catch. |
Response
mixed
upload
Upload a file
upload( src, dest, context = null, usePrefix = true, relative = false) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::upload() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- src
string
The file path to copy from (usually a temp folder).- dest
string
The file path to copy to.- context
resource
A valid context resource (optional) created with stream_context_create.- usePrefix
bool
Controls the use of a prefix (optional).- relative
bool
Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
Response
mixed
write
File write
write( &string, length, chunk) :
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
link | |
---|---|
since |
1.7.0 |
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::write() instead. The framework class throws Exceptions in case of error which you have to catch. |
Arguments
- string
string
Reference to the string to write.- length
int
Length of the string to write.- chunk
int
Size of chunks to write in.
Response
bool
writeFile
Writes a chunk of data to a file.
writeFile( filename, &buffer) :
since |
1.7.0 |
---|---|
deprecated |
4.4 will be removed in 6.0 Use Joomla\Filesystem\Stream::writeFile() instead. |
Arguments
- filename
string
The file name.- buffer
string
The data to write to the file.
Response
bool
Properties
_errors
An array of error messages or Exception objects.
since |
1.7.0 |
---|---|
deprecated |
3.1.4 JError has been deprecated |
Type(s)
array<string|int, mixed>
filemode
File Mode
since |
1.7.0 |
---|
Type(s)
int
dirmode
Directory Mode
since |
1.7.0 |
---|
Type(s)
int
chunksize
Default Chunk Size
since |
1.7.0 |
---|
Type(s)
int
filename
Filename
since |
1.7.0 |
---|
Type(s)
string
writeprefix
Prefix of the connection for writing
since |
1.7.0 |
---|
Type(s)
string
readprefix
Prefix of the connection for reading
since |
1.7.0 |
---|
Type(s)
string
processingmethod
Read Processing method
since |
1.7.0 |
---|
Type(s)
string
filters
Filters applied to the current stream
since |
1.7.0 |
---|
Type(s)
array<string|int, mixed>
fh
File Handle
since |
3.0.0 |
---|
Type(s)
resource
filesize
File size
since |
3.0.0 |
---|
Type(s)
int
context
Context to use when opening the connection
since |
3.0.0 |
---|
Type(s)
resource
contextOptions
Context options; used to rebuild the context
since |
3.0.0 |
---|
Type(s)
array<string|int, mixed>
openmode
The mode under which the file was opened
since |
3.0.0 |
---|
Type(s)
string