Stream

Extends \Joomla\CMS\Object\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.

note

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.7.0

Methods

__construct

Class constructor, overridden in descendant classes.

__construct(mixed $properties = null) 
inherited
since

1.7.0

Arguments

$properties

mixedEither and associative array or another object to set the initial properties of the object.

__destruct

Destructor

__destruct() 
since

1.7.0

__toString

Magic method to convert the object to a string gracefully.

__toString() : string
inherited deprecated
since

1.7.0

deprecated

12.3 Classes should provide their own __toString() implementation.

Response

stringThe classname.

_buildContext

Stream contexts Builds the context from the array

_buildContext() : mixed
since

1.7.0

Response

mixed

_getFilename

Determine the appropriate 'filename' of a file

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

1.7.0

Arguments

$filename

stringOriginal filename of the file

$mode

stringMode string to retrieve the filename

$use_prefix

booleanControls the use of a prefix

$relative

booleanDetermines 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.7.0

Arguments

$wrapper

stringThe wrapper to use

$name

stringThe option to set

$value

stringThe value of the option

appendFilter

Stream filters Append a filter to the chain

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

https://www.php.net/manual/en/function.stream-filter-append.php

since

1.7.0

Arguments

$filtername

stringThe key name of the filter.

$read_write

integerOptional. Defaults to STREAM_FILTER_READ.

$params

arrayAn array of params for the stream_filter_append call.

Response

mixed

applyContextToStream

Applies the current context to the stream

applyContextToStream() : mixed

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

since

1.7.0

Response

mixed

chmod

Chmod wrapper

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

1.7.0

Arguments

$filename

stringFile name.

$mode

mixedMode 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.7.0

Response

boolean

copy

Copy a file from src to dest

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

1.7.0

Arguments

$src

stringThe file path to copy from.

$dest

stringThe file path to copy to.

$context

resourceA valid context resource (optional) created with stream_context_create.

$use_prefix

booleanControls the use of a prefix (optional).

$relative

booleanDetermines 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(string $property, mixed $default = null) : mixed
inherited
since

1.7.0

Arguments

$property

stringThe name of the property.

$default

mixedThe default value.

Response

mixed

delete

Delete a file

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

1.7.0

Arguments

$filename

stringThe file path to delete.

$context

resourceA valid context resource (optional) created with stream_context_create.

$use_prefix

booleanControls the use of a prefix (optional).

$relative

booleanDetermines 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(string $wrapper, string $name) : void
link

https://www.php.net/stream_context_create

since

1.7.0

Arguments

$wrapper

stringThe wrapper to use

$name

stringThe option to unset

eof

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

eof() : boolean
since

1.7.0

Response

boolean

filesize

Retrieve the file size of the path

filesize() : mixed
since

1.7.0

Response

mixed

get

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

get(string $property, mixed $default = null) : mixed
inherited
since

1.7.0

see \Joomla\CMS\Object\CMSObject::getProperties()

Arguments

$property

stringThe name of the property.

$default

mixedThe default value.

Response

mixedThe 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.7.0

Response

arrayheader/metadata

getError

Get the most recent error message.

getError(integer $i = null, boolean $toString = true) : string
inherited deprecated
since

1.7.0

see \Joomla\CMS\Object\JError
deprecated

12.3 JError has been deprecated

Arguments

$i

integerOption error index.

$toString

booleanIndicates if JError objects should return their error message.

Response

stringError message

getErrors

Return all errors, if any.

getErrors() : array
inherited deprecated
since

1.7.0

see \Joomla\CMS\Object\JError
deprecated

12.3 JError has been deprecated

Response

arrayArray of error messages or JErrors.

getFileHandle

Return the internal file handle

getFileHandle() : resource
since

1.7.0

Response

resourceFile handler

getProperties

Returns an associative array of object properties.

getProperties(boolean $public = true) : array
inherited
since

1.7.0

see \Joomla\CMS\Object\CMSObject::get()

Arguments

$public

booleanIf true, returns only the public properties.

Response

array

gets

Get a line from the stream source.

gets(integer $length) : mixed
since

1.7.0

Arguments

$length

integerThe number of bytes (optional) to read.

Response

mixed

move

Moves a file

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

1.7.0

Arguments

$src

stringThe file path to move from.

$dest

stringThe file path to move to.

$context

resourceA valid context resource (optional) created with stream_context_create.

$use_prefix

booleanControls the use of a prefix (optional).

$relative

booleanDetermines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.

Response

mixed

open

Generic File Operations

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

Open a stream with some lazy loading smarts

since

1.7.0

Arguments

$filename

stringFilename

$mode

stringMode string to use

$use_include_path

booleanUse the PHP include path

$context

resourceContext to use when opening

$use_prefix

booleanUse a prefix to open the file

$relative

booleanFilename is a relative path (if false, strips JPATH_ROOT to make it relative)

$detectprocessingmode

booleanDetect 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 $read_write = STREAM_FILTER_READ, array $params = array()) : mixed
link

https://www.php.net/manual/en/function.stream-filter-prepend.php

since

1.7.0

Arguments

$filtername

stringThe key name of the filter.

$read_write

integerOptional. Defaults to STREAM_FILTER_READ.

$params

arrayAn array of params for the stream_filter_prepend call.

Response

mixed

read

Read a file

read(integer $length) : mixed

Handles user space streams appropriately otherwise any read will return 8192

link

https://www.php.net/manual/en/function.fread.php

since

1.7.0

Arguments

$length

integerLength 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, boolean $byindex = false) : boolean
since

1.7.0

Arguments

$resource

$byindex

booleanThe index of the filter.

Response

booleanResult 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

https://www.php.net/manual/en/function.fseek.php

since

1.7.0

Arguments

$offset

integerOffset to use when seeking.

$whence

integerSeek mode to use.

Response

booleanTrue 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
inherited
since

1.7.0

Arguments

$property

stringThe name of the property.

$value

mixedThe value of the property to set.

Response

mixedPrevious 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

https://www.php.net/stream_context_create

since

1.7.0

Arguments

$context

arrayOptions to create the context with

setError

Add an error message.

setError(string $error) : void
inherited deprecated
since

1.7.0

see \Joomla\CMS\Object\JError
deprecated

12.3 JError has been deprecated

Arguments

$error

stringError message.

setProperties

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

setProperties(mixed $properties) : boolean
inherited
since

1.7.0

see \Joomla\CMS\Object\CMSObject::set()

Arguments

$properties

mixedEither an associative array or another object.

Response

boolean

tell

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

tell() : mixed
since

1.7.0

Response

mixed

upload

Upload a file

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

1.7.0

Arguments

$src

stringThe file path to copy from (usually a temp folder).

$dest

stringThe file path to copy to.

$context

resourceA valid context resource (optional) created with stream_context_create.

$use_prefix

booleanControls the use of a prefix (optional).

$relative

booleanDetermines if the filename given is relative. Relative paths do not have JPATH_ROOT stripped.

Response

mixed

write

File write

write( &$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 JStream::set('chunksize', newsize);) Note: This doesn't support gzip/bzip2 writing like reading does

link

https://www.php.net/manual/en/function.fwrite.php

since

1.7.0

Arguments

$string

$length

integerLength of the string to write.

$chunk

integerSize of chunks to write in.

Response

boolean

writeFile

Writes a chunk of data to a file.

writeFile(string $filename,  &$buffer) : boolean
since

1.7.0

Arguments

$filename

stringThe file name.

$buffer

Response

boolean

Properties

filemode

File Mode

since

1.7.0

Type(s)

integer

dirmode

Directory Mode

since

1.7.0

Type(s)

integer

chunksize

Default Chunk Size

since

1.7.0

Type(s)

integer

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

fh

File Handle

since

3.0.0

Type(s)

resource

filesize

File size

since

3.0.0

Type(s)

integer

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

openmode

The mode under which the file was opened

since

3.0.0

Type(s)

string

_errors

An array of error messages or Exception objects.

inherited deprecated
since

1.7.0

see \Joomla\CMS\Object\JError
deprecated

12.3 JError has been deprecated

Type(s)

array