Stream
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 atomic manner.
This class adheres to the stream wrapper operations:
link |
https://www.php.net/manual/en/function.stream-get-wrappers.php PHP Stream Manual Stream Wrappers Stream Filters Socket Transports (used by some options, particularly HTTP proxy) |
---|---|
since |
1.0 |
Methods
__construct
Constructor
__construct(string $writeprefix = '', string $readprefix = '', array $context = array())
since |
1.0 |
---|
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
The context options (optional).
__destruct
Destructor
__destruct()
since |
1.0 |
---|
_buildContext
Stream contexts Builds the context from the array
_buildContext() : void
since |
1.0 |
---|
_getFilename
Determine the appropriate 'filename' of a file
_getFilename(string $filename, string $mode, boolean $usePrefix, boolean $relative) : string
since |
1.0 |
---|
Arguments
- $filename
string
Original filename of the file- $mode
string
Mode string to retrieve the filename- $usePrefix
boolean
Controls the use of a prefix- $relative
boolean
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(string $wrapper, string $name, string $value) : void
link |
Stream Context Creation Context Options for various streams |
---|---|
since |
1.0 |
Arguments
- $wrapper
string
The wrapper to use- $name
string
The option to set- $value
string
The value of the option
appendFilter
Stream filters Append a filter to the chain
appendFilter(string $filtername, integer $readWrite = \STREAM_FILTER_READ, array $params = array()) : resource|boolean
link |
https://www.php.net/manual/en/function.stream-filter-append.php |
---|---|
since |
1.0 |
throws |
|
Arguments
- $filtername
string
The key name of the filter.- $readWrite
integer
Optional. Defaults to STREAM_FILTER_READ.- $params
array
An array of params for the stream_filter_append call.
Response
resource|boolean
applyContextToStream
Applies the current context to the stream
applyContextToStream() : boolean
Use this to change the values of the context after you've opened a stream
since |
1.0 |
---|---|
throws |
|
Response
boolean
chmod
Chmod wrapper
chmod(string $filename = '', mixed $mode) : boolean
since |
1.0 |
---|---|
throws |
|
Arguments
- $filename
string
File name.- $mode
mixed
Mode to use.
Response
boolean
close
Attempt to close a file handle
close() : boolean
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.0 |
---|---|
throws |
|
Response
boolean
copy
Copy a file from src to dest
copy(string $src, string $dest, resource $context = null, boolean $usePrefix = true, boolean $relative = false) : boolean
since |
1.0 |
---|---|
throws |
|
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
boolean
Controls the use of a prefix (optional).- $relative
boolean
Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
Response
boolean
delete
Delete a file
delete(string $filename, resource $context = null, boolean $usePrefix = true, boolean $relative = false) : boolean
since |
1.0 |
---|---|
throws |
|
Arguments
- $filename
string
The file path to delete.- $context
resource
A valid context resource (optional) created with stream_context_create.- $usePrefix
boolean
Controls the use of a prefix (optional).- $relative
boolean
Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
Response
boolean
deleteContextEntry
Deletes a particular setting from a context
deleteContextEntry(string $wrapper, string $name) : void
link | |
---|---|
since |
1.0 |
Arguments
- $wrapper
string
The wrapper to use- $name
string
The option to unset
eof
Work out if we're at the end of the file for a stream
eof() : boolean
since |
1.0 |
---|---|
throws |
|
Response
boolean
filesize
Retrieve the file size of the path
filesize() : integer|boolean
since |
1.0 |
---|---|
throws |
|
Response
integer|boolean
get
Returns a property of the object or the default value if the property is not set.
get(string $property, mixed $default = null) : mixed
since |
1.0 |
---|
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
link |
https://www.php.net/manual/en/function.stream-get-meta-data.php |
---|---|
since |
1.0 |
throws |
|
Response
array
header/metadata
getFileHandle
Return the internal file handle
getFileHandle() : \Joomla\Filesystem\File
gets
Get a line from the stream source.
gets(integer $length) : string
since |
1.0 |
---|---|
throws |
|
Arguments
- $length
integer
The number of bytes (optional) to read.
Response
string
getStream
Creates a new stream object with appropriate prefix
getStream(boolean $usePrefix = true, string $ua = null, boolean $uamask = false) : \Joomla\Filesystem\Stream
see | \Joomla\Filesystem\Stream |
---|---|
since |
1.0 |
Arguments
- $usePrefix
boolean
Prefix the connections for writing- $ua
string
UA User agent to use- $uamask
boolean
User agent masking (prefix Mozilla)
Response
move
Moves a file
move(string $src, string $dest, resource $context = null, boolean $usePrefix = true, boolean $relative = false) : boolean
since |
1.0 |
---|---|
throws |
|
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
boolean
Controls the use of a prefix (optional).- $relative
boolean
Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
Response
boolean
open
Generic File Operations
open(string $filename, string $mode = 'r', boolean $useIncludePath = false, resource $context = null, boolean $usePrefix = false, boolean $relative = false, boolean $detectprocessingmode = false) : boolean
Open a stream with some lazy loading smarts
since |
1.0 |
---|---|
throws |
|
Arguments
- $filename
string
Filename- $mode
string
Mode string to use- $useIncludePath
boolean
Use the PHP include path- $context
resource
Context to use when opening- $usePrefix
boolean
Use a prefix to open the file- $relative
boolean
Filename is a relative path (if false, strips JPATH_ROOT to make it relative)- $detectprocessingmode
boolean
Detect the processing method for the file and use the appropriate function to handle output automatically
Response
boolean
prependFilter
Prepend a filter to the chain
prependFilter(string $filtername, integer $readWrite = \STREAM_FILTER_READ, array $params = array()) : resource|boolean
link |
https://www.php.net/manual/en/function.stream-filter-prepend.php |
---|---|
since |
1.0 |
throws |
|
Arguments
- $filtername
string
The key name of the filter.- $readWrite
integer
Optional. Defaults to STREAM_FILTER_READ.- $params
array
An array of params for the stream_filter_prepend call.
Response
resource|boolean
read
Read a file
read(integer $length) : string
Handles user space streams appropriately otherwise any read will return 8192
link | |
---|---|
since |
1.0 |
throws |
|
Arguments
- $length
integer
Length of data to read
Response
string
removeFilter
Remove a filter, either by resource (handed out from the append or prepend function) or via getting the filter list)
removeFilter(resource &$resource, boolean $byindex = false) : boolean
since |
1.0 |
---|---|
throws |
|
Arguments
- $resource
resource
The resource.- $byindex
boolean
The index of the filter.
Response
boolean
Result of operation
seek
Seek the file
seek(integer $offset, integer $whence = \SEEK_SET) : boolean
Note: the return value is different to that of fseek
link | |
---|---|
since |
1.0 |
throws |
|
Arguments
- $offset
integer
Offset to use when seeking.- $whence
integer
Seek mode to use.
Response
boolean
True on success, false on failure
set
Modifies a property of the object, creating it if it does not already exist.
set(string $property, mixed $value = null) : mixed
since |
1.0 |
---|
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(array $context) : void
Format is the same as the options for stream_context_create
link | |
---|---|
since |
1.0 |
Arguments
- $context
array
Options to create the context with
tell
Returns the current position of the file read/write pointer.
tell() : integer
since |
1.0 |
---|---|
throws |
|
Response
integer
upload
Upload a file
upload(string $src, string $dest, resource $context = null, boolean $usePrefix = true, boolean $relative = false) : boolean
since |
1.0 |
---|---|
throws |
|
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
boolean
Controls the use of a prefix (optional).- $relative
boolean
Determines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.
Response
boolean
write
File write
write(string &$string, integer $length, integer $chunk) : boolean
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 Stream::set('chunksize', newsize);) Note: This doesn't support gzip/bzip2 writing like reading does
link | |
---|---|
since |
1.0 |
throws |
|
Arguments
- $string
string
Reference to the string to write.- $length
integer
Length of the string to write.- $chunk
integer
Size of chunks to write in.
Response
boolean
writeFile
Writes a chunk of data to a file.
writeFile(string $filename, string &$buffer, boolean $appendToFile = false) : boolean
since |
1.0 |
---|
Arguments
- $filename
string
The file name.- $buffer
string
The data to write to the file.- $appendToFile
boolean
Append to the file and not overwrite it.
Response
boolean
Properties
filemode
File Mode
since |
1.0 |
---|
Type(s)
integer
dirmode
Directory Mode
since |
1.0 |
---|
Type(s)
integer
chunksize
Default Chunk Size
since |
1.0 |
---|
Type(s)
integer
filename
Filename
since |
1.0 |
---|
Type(s)
string
writeprefix
Prefix of the connection for writing
since |
1.0 |
---|
Type(s)
string
readprefix
Prefix of the connection for reading
since |
1.0 |
---|
Type(s)
string
processingmethod
Read Processing method
since |
1.0 |
---|
Type(s)
string
filters
Filters applied to the current stream
since |
1.0 |
---|
Type(s)
array
fh
File Handle
since |
1.0 |
---|
Type(s)
resource
filesize
File size
since |
1.0 |
---|
Type(s)
integer
context
Context to use when opening the connection
since |
1.0 |
---|
Type(s)
string
contextOptions
Context options; used to rebuild the context
since |
1.0 |
---|
Type(s)
array
openmode
The mode under which the file was opened
since |
1.0 |
---|
Type(s)
string