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

PHP Stream Manual

Stream Wrappers

Stream Filters

Socket Transports (used by some options, particularly HTTP proxy)

since

1.0

package

Joomla Framework

Methods

__construct

Constructor

__construct(string writeprefix = '', string readprefix = '', array context = []) : mixed
since

1.0

Arguments

writeprefix

stringPrefix of the stream (optional). Unlike the JPATH_*, this has a final path separator!

readprefix

stringThe read prefix (optional).

context

arrayThe context options (optional).

Response

mixed

__destruct

Destructor

__destruct() : mixed
since

1.0

Response

mixed

_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, bool usePrefix, bool relative) : string
since

1.0

Arguments

filename

stringOriginal filename of the file

mode

stringMode string to retrieve the filename

usePrefix

boolControls the use of a prefix

relative

boolDetermines 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

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, int readWrite = STREAM_FILTER_READ, array params = []) : resource|bool
link
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Arguments

filtername

stringThe key name of the filter.

readWrite

intOptional. Defaults to STREAM_FILTER_READ.

params

arrayAn array of params for the stream_filter_append call.

Response

resource|bool

applyContextToStream

Applies the current context to the stream

applyContextToStream() : bool

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

since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Response

bool

chmod

Chmod wrapper

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

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Arguments

filename

stringFile name.

mode

mixedMode to use.

Response

bool

close

Attempt to close a file handle

close() : bool

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

\Joomla\Filesystem\Exception\FilesystemException

Response

bool

copy

Copy a file from src to dest

copy(string src, string dest, resource context = null, bool usePrefix = true, bool relative = false) : bool
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

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.

usePrefix

boolControls the use of a prefix (optional).

relative

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

Response

bool

delete

Delete a file

delete(string filename, resource context = null, bool usePrefix = true, bool relative = false) : bool
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Arguments

filename

stringThe file path to delete.

context

resourceA valid context resource (optional) created with stream_context_create.

usePrefix

boolControls the use of a prefix (optional).

relative

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

Response

bool

deleteContextEntry

Deletes a particular setting from a context

deleteContextEntry(string wrapper, string name) : void
link
since

1.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() : bool
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Response

bool

filesize

Retrieve the file size of the path

filesize() : int|bool
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Response

int|bool

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

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
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Response

arrayheader/metadata

getFileHandle

Return the internal file handle

getFileHandle() : \Joomla\Filesystem\File
since

1.0

Response

\Joomla\Filesystem\Filehandler

gets

Get a line from the stream source.

gets(int length) : string
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Arguments

length

intThe number of bytes (optional) to read.

Response

string

getStream

Creates a new stream object with appropriate prefix

getStream(bool usePrefix = true, string ua = null, bool uamask = false) : \Joomla\Filesystem\Stream
static
see Stream
since

1.0

Arguments

usePrefix

boolPrefix the connections for writing

ua

stringUA User agent to use

uamask

boolUser agent masking (prefix Mozilla)

Response

\Joomla\Filesystem\Stream

move

Moves a file

move(string src, string dest, resource context = null, bool usePrefix = true, bool relative = false) : bool
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

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.

usePrefix

boolControls the use of a prefix (optional).

relative

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

Response

bool

open

Generic File Operations

open(string filename, string mode = 'r', bool useIncludePath = false, resource context = null, bool usePrefix = false, bool relative = false, bool detectprocessingmode = false) : bool

Open a stream with some lazy loading smarts

since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Arguments

filename

stringFilename

mode

stringMode string to use

useIncludePath

boolUse the PHP include path

context

resourceContext to use when opening

usePrefix

boolUse a prefix to open the file

relative

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

detectprocessingmode

boolDetect 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(string filtername, int readWrite = STREAM_FILTER_READ, array params = []) : resource|bool
link
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Arguments

filtername

stringThe key name of the filter.

readWrite

intOptional. Defaults to STREAM_FILTER_READ.

params

arrayAn array of params for the stream_filter_prepend call.

Response

resource|bool

read

Read a file

read(int length) : string

Handles user space streams appropriately otherwise any read will return 8192

link
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Arguments

length

intLength 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, bool byindex = false) : bool
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Arguments

resource

resourceThe resource.

byindex

boolThe index of the filter.

Response

boolResult of operation

seek

Seek the file

seek(int offset, int whence = SEEK_SET) : bool

Note: the return value is different to that of fseek

link
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Arguments

offset

intOffset to use when seeking.

whence

intSeek mode to use.

Response

boolTrue 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

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
since

1.0

Arguments

context

arrayOptions to create the context with

tell

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

tell() : int
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

Response

int

upload

Upload a file

upload(string src, string dest, resource context = null, bool usePrefix = true, bool relative = false) : bool
since

1.0

throws

\Joomla\Filesystem\Exception\FilesystemException

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.

usePrefix

boolControls the use of a prefix (optional).

relative

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

Response

bool

write

File write

write(string &string, int length, int chunk) : bool

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

\Joomla\Filesystem\Exception\FilesystemException

Arguments

string

stringReference to the string to write.

length

intLength of the string to write.

chunk

intSize of chunks to write in.

Response

bool

writeFile

Writes a chunk of data to a file.

writeFile(string filename, string &buffer, bool appendToFile = false) : bool
since

1.0

Arguments

filename

stringThe file name.

buffer

stringThe data to write to the file.

appendToFile

boolAppend to the file and not overwrite it.

Response

bool

Properties

filemode

File Mode

since

1.0

Type(s)

int

dirmode

Directory Mode

since

1.0

Type(s)

int

chunksize

Default Chunk Size

since

1.0

Type(s)

int

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)

int

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