C# Class Pchp.Library.Streams.PhpStream

Abstraction of streaming behavior for PHP. PhpStreams are opened by StreamWrappers on a call to fopen().

PhpStream is a descendant of PhpResource, it contains a StreamContext (may be empty) and two ordered lists of StreamFilters (input and output filters). PhpStream may be cast to a .NET stream (using its RawStream property).

Various stream types are defined by overriding the Raw* methods that provide direct access to the underlying physical stream. Corresponding public methods encapsulate these accessors with buffering and filtering. Raw stream access is performed at the byte[] level. ClassLibrary functions may use either the Read/WriteBytes or Read/WriteString depending on the nature of the PHP function. Data are converted using the ApplicationConfiguration.GlobalizationSection.PageEncoding as necessary.

When reading from a stream, the stream data is read in binary format in chunks of predefined size (8kB). Stream filters (if any) are then applied in a cascade to the whole block. Filtered blocks are stored in a Queue of either strings or PhpBytes depending on the last filter output (note that after filtering not all blocks have necessarily the original chunk size; when appending a filter to the filter-chain all the buffered data is passed through this one too). The input queue is being filled until the required data length is available. The readPosition property holds the index into the first chunk of data. When this chunk is entirely consumed it is dequeued.

Writing to a stream is buffered too (unless it is disabled using stream_set_write_buffer). When the data passes through the filter-chain it is appended to the write buffer (using the writePosition property). When the write buffer is full it is flushed to the underlying stream.

Inheritance: Pchp.Core.PhpResource

Afficher le fichier Open project: iolevel/peachpie Class Usage Examples

Méthodes publiques

Свойство	Type	Description
OpenedPath	string
Options	StreamAccessOptions
Wrapper	StreamWrapper

Protected Properties

Свойство	Type	Description
_context	StreamContext
currentAccess	FileAccess
fgetssState	int
isPersistent	bool
isReadBuffered	bool
readBuffers	Queue
readChunkSize	int
readFilteredCount	int
readFilters	List
readOffset	int
readPosition	int
readTimeout	double
textReadFilter	IFilter
textWriteFilter	IFilter
writeBuffer	byte[]
writeBufferSize	int
writeFilteredCount	int
writeOffset	int
writePosition	int

Méthodes publiques

Méthode	Description
AddFilter ( IFilter filter, FilterChainOptions where ) : void	Adds a filter to one of the read or write filter chains.
CheckAccess ( string filename, CheckAccessMode mode, CheckAccessOptions options ) : bool	Performs all checks on a path passed to a PHP function. This method performs a check similar to `safe_mode.c: php_checkuid_ex()` together with `open_basedir` check. The filename may be one of the following: A relative path. The path is resolved regarding the `include_path` too if required and checking continues as in the next case. An absolute path. The file or directory is checked for existence and for access permissions¹ according to the given mode. ¹ Regarding the `open_basedir` configuration option. File access permissions are checked at the time of file manipulation (opening, copying etc.).
Flush ( ) : bool	Write all the output buffer to the underlying stream and flush it.
GetNextDataLength ( ) : int	Gets the number of bytes or characters in the first read-buffer or next chunk size.
GetValid ( PhpResource handle ) : PhpStream	Check that the resource handle contains a valid PhpStream resource and cast the handle to PhpStream.
GetValid ( PhpResource handle, FileAccess desiredAccess ) : PhpStream
Open ( Context ctx, string path, string mode ) : PhpStream
Open ( Context ctx, string path, string mode, StreamOpenOptions options ) : PhpStream
Open ( Context ctx, string path, string mode, StreamOpenOptions options, StreamContext context ) : PhpStream	Openes a PhpStream using the appropriate StreamWrapper.
PhpStream ( Context ctx, StreamWrapper openingWrapper, StreamAccessOptions accessOptions, string openedPath, StreamContext context ) : Pchp.Core	PhpStream is created by a StreamWrapper together with the encapsulated RawStream (the actual file opening is handled by the wrapper). This class newly implements the auto-remove behavior too (see StreamAccessOptions.Temporary).
ReadBinaryContents ( int maxLength ) : byte[]
ReadBytes ( int length ) : byte[]	Reads binary data from the stream. First looks for data into the readBuffers. When length is not satisfied, new data from the underlying stream are processed.
ReadContents ( ) : TextElement
ReadContents ( int maxLength ) : TextElement
ReadContents ( int maxLength, int offset ) : TextElement
ReadData ( int length, bool ending ) : TextElement	Reads a block of data from the stream up to length characters or up to EOLN if length is negative. ReadData first looks for data into the readBuffers. While length is not satisfied, new data from the underlying stream are processed. The data is buffered as either string or PhpBytes but consistently. The type of the first buffer thus specifies the return type.
ReadLine ( int length, string ending ) : string	Reads one line (text ending with the ending delimiter) from the stream up to length characters long.
ReadMaximumBytes ( ) : byte[]	Effecient access to the buffered and filtered stream consuming one whole buffer at a time.
ReadMaximumData ( ) : TextElement	Most effecient access to the buffered stream consuming one whole buffer at a time. Performs no unnecessary conversions (although attached stream filters may do so). Use the readChunkSize member to affect the amount of data returned at a time.
ReadMaximumString ( ) : string	Effecient access to the buffered and filtered stream consuming one whole buffer at a time.
ReadString ( int length ) : string	Reads text data from the stream. First looks for data into the readBuffers. When length is not satisfied, new data from the underlying stream are processed.
ReadStringContents ( int maxLength ) : string
ResolvePath ( Context ctx, string &path, StreamWrapper &wrapper, CheckAccessMode mode, CheckAccessOptions options ) : bool	Merges the path with the current working directory to get a canonicalized absolute pathname representing the same file. This method is an analogy of `main/safe_mode.c: php_checkuid`. Looks for the file in the `include_path` and checks for `open_basedir` restrictions.
Seek ( int offset, SeekOrigin whence ) : bool	Sets the read/write pointer in the stream to a new position.
SetParameter ( StreamParameterOptions option, PhpValue value ) : bool
Stat ( ) : StatStruct
Tell ( ) : int	Gets the current position in the stream. The problem with tell() in PHP is that although the write offset is calculated in the raw byte stream (just before buffering) the read one is calculated in the filtered string buffers. In other words the value returned by tell() for output streams is the real position in the raw stream but may differ from the number of characters written. On the other hand the value returned for input streams corresponds with the number of characters retreived but not with the position in the raw stream. It is important to remember that seeking on a filtered stream (such as a file opened with a "rt" mode) has undefined behavior.
WriteBytes ( byte data ) : int	Apppends the binary data to the output buffer passing through the output filter-chain. When the buffer is full or buffering is disabled, pass the data to the low-level stream.
WriteString ( string data ) : int	Apppends the text data to the output buffer passing through the output filter-chain. When the buffer is full or buffering is disabled, pass the data to the low-level stream.

Méthodes protégées

Méthode	Description
DropReadBuffer ( ) : bool	Remove the (entirely consumed) read buffer from the head of the read buffer queue.
FlushWriteBuffer ( ) : bool	Writes all the output buffer to the underlying stream.
FreeManaged ( ) : void	PhpResource.FreeManaged overridden to get rid of the contained context on Dispose.
FreeUnmanaged ( ) : void	PhpResource.FreeUnmanaged overridden to remove a temporary file on Dispose.
RawFlush ( ) : bool
RawLength ( ) : int	Gets the length of the stream.
RawRead ( byte buffer, int offset, int count ) : int
RawSeek ( int offset, SeekOrigin whence ) : bool
RawTell ( ) : int
RawWrite ( byte buffer, int offset, int count ) : int
ReadBinaryBuffer ( int length ) : byte[]	Joins the read buffers to get at least length bytes in a PhpBytes.
ReadFiltered ( int chunkSize ) : TextElement	Fills the readBuffers with more data from the underlying stream passed through all the stream filters.
ReadTextBuffer ( int length ) : string	Joins the read buffers to get at least length characters in a string. It is assumed that there already is length bytes in the buffers. Otherwise an InvalidOperationException is raised.
WriteData ( TextElement data, bool closing = false ) : int	Passes the data through output filter-chain to the output buffer. When the buffer is full or buffering is disabled, passes the data to the low-level stream.

Private Methods

Méthode	Description
CheckIncludePath ( Context ctx, string relativePath, string &absolutePath ) : bool	Check if the path lays inside of the directory tree specified by the `open_basedir` configuration option and return the resulting absolutePath.
EnqueueReadBuffer ( TextElement data ) : void	Put a buffer at the end of the readBuffers.
FindEoln ( TextElement data, int from ) : int	Finds the '\n' in a string or PhpBytes and returns its offset or `-1` if not found.
GetSchemeInternal ( string path, string &filename ) : string	Checks if the given path is a filesystem path or an URL and returns the corresponding scheme.
Open ( Context ctx, string path, StreamOpenMode mode ) : PhpStream	Simple version of the stream opening function
ReadBufferScan ( int &nlpos ) : int
SeekInternal ( int offset, int current, SeekOrigin whence ) : bool	Perform the actual seek on the stream. Report errors.
SplitData ( TextElement data, int upto, TextElement &left, TextElement &right ) : void	Split a String or PhpBytes to "upto" bytes at left and the rest or `null` at right.
SplitData ( string s, int upto, string &left, string &right ) : void	Split a string to "upto" bytes at left and the rest or `null` at right.
TryUnlink ( ) : void

Method Details

AddFilter() public méthode

Adds a filter to one of the read or write filter chains.

public AddFilter ( IFilter filter, FilterChainOptions where ) : void
filter	IFilter	The filter.
where	FilterChainOptions	The position in the chain.
Résultat	void

CheckAccess() public static méthode

Performs all checks on a path passed to a PHP function.

This method performs a check similar to safe_mode.c: php_checkuid_ex() together with open_basedir check.

The filename may be one of the following: A relative path. The path is resolved regarding the include_path too if required and checking continues as in the next case. An absolute path. The file or directory is checked for existence and for access permissions¹ according to the given mode. ¹ Regarding the open_basedir configuration option. File access permissions are checked at the time of file manipulation (opening, copying etc.).

If the file can not be accessed /// and the is not set.

public static CheckAccess ( string filename, CheckAccessMode mode, CheckAccessOptions options ) : bool
filename	string	A resolved path. Must be an absolute path to a local file.
mode	CheckAccessMode	One of the .
options	CheckAccessOptions	true to suppress error messages.
Résultat	bool

DropReadBuffer() protected méthode

Remove the (entirely consumed) read buffer from the head of the read buffer queue.

protected DropReadBuffer ( ) : bool
Résultat	bool

Flush() public méthode

Write all the output buffer to the underlying stream and flush it.

public Flush ( ) : bool
Résultat	bool

FlushWriteBuffer() protected méthode

Writes all the output buffer to the underlying stream.

protected FlushWriteBuffer ( ) : bool
Résultat	bool

FreeManaged() protected méthode

PhpResource.FreeManaged overridden to get rid of the contained context on Dispose.

protected FreeManaged ( ) : void
Résultat	void

FreeUnmanaged() protected méthode

PhpResource.FreeUnmanaged overridden to remove a temporary file on Dispose.

protected FreeUnmanaged ( ) : void
Résultat	void

GetNextDataLength() public méthode

Gets the number of bytes or characters in the first read-buffer or next chunk size.

public GetNextDataLength ( ) : int
Résultat	int

GetValid() public static méthode

Check that the resource handle contains a valid PhpStream resource and cast the handle to PhpStream.

public static GetValid ( PhpResource handle ) : PhpStream
handle	Pchp.Core.PhpResource	A PhpResource passed to the PHP function.
Résultat	PhpStream

GetValid() public static méthode

public static GetValid ( PhpResource handle, FileAccess desiredAccess ) : PhpStream
handle	Pchp.Core.PhpResource
desiredAccess	FileAccess
Résultat	PhpStream

Open() public static méthode

public static Open ( Context ctx, string path, string mode ) : PhpStream
ctx	Pchp.Core.Context
path	string
mode	string
Résultat	PhpStream

Open() public static méthode

public static Open ( Context ctx, string path, string mode, StreamOpenOptions options ) : PhpStream
ctx	Pchp.Core.Context
path	string
mode	string
options	StreamOpenOptions
Résultat	PhpStream

Open() public static méthode

Openes a PhpStream using the appropriate StreamWrapper.

public static Open ( Context ctx, string path, string mode, StreamOpenOptions options, StreamContext context ) : PhpStream
ctx	Pchp.Core.Context	Current runtime context.
path	string	URI or filename of the resource to be opened.
mode	string	A file-access mode as passed to the PHP function.
options	StreamOpenOptions	A combination of .
context	StreamContext	A valid StreamContext. Must not be null.
Résultat	PhpStream

PhpStream() public méthode

PhpStream is created by a StreamWrapper together with the encapsulated RawStream (the actual file opening is handled by the wrapper).

This class newly implements the auto-remove behavior too (see StreamAccessOptions.Temporary).

public PhpStream ( Context ctx, StreamWrapper openingWrapper, StreamAccessOptions accessOptions, string openedPath, StreamContext context ) : Pchp.Core
ctx	Pchp.Core.Context	Runtime context.
openingWrapper	StreamWrapper	The parent instance.
accessOptions	StreamAccessOptions	The additional options parsed from the fopen() mode.
openedPath	string	The absolute path to the opened resource.
context	StreamContext	The stream context passed to fopen().
Résultat	Pchp.Core

RawFlush() protected abstract méthode

protected abstract RawFlush ( ) : bool
Résultat	bool

RawLength() protected méthode

Gets the length of the stream.

protected RawLength ( ) : int
Résultat	int

RawRead() protected abstract méthode

protected abstract RawRead ( byte buffer, int offset, int count ) : int
buffer	byte
offset	int
count	int
Résultat	int

RawSeek() protected méthode

protected RawSeek ( int offset, SeekOrigin whence ) : bool
offset	int
whence	SeekOrigin
Résultat	bool

RawTell() protected méthode

protected RawTell ( ) : int
Résultat	int

RawWrite() protected abstract méthode

protected abstract RawWrite ( byte buffer, int offset, int count ) : int
buffer	byte
offset	int
count	int
Résultat	int

ReadBinaryBuffer() protected méthode

Joins the read buffers to get at least length bytes in a PhpBytes.

protected ReadBinaryBuffer ( int length ) : byte[]
length	int	The desired maximum result length.
Résultat	byte[]

ReadBinaryContents() public méthode

public ReadBinaryContents ( int maxLength ) : byte[]
maxLength	int
Résultat	byte[]

ReadBytes() public méthode

Reads binary data from the stream. First looks for data into the readBuffers. When length is not satisfied, new data from the underlying stream are processed.

public ReadBytes ( int length ) : byte[]
length	int	The number of bytes to return.
Résultat	byte[]

ReadContents() public méthode

public ReadContents ( ) : TextElement
Résultat	TextElement

ReadContents() public méthode

public ReadContents ( int maxLength ) : TextElement
maxLength	int
Résultat	TextElement

ReadContents() public méthode

public ReadContents ( int maxLength, int offset ) : TextElement
maxLength	int
offset	int
Résultat	TextElement

ReadData() public méthode

Reads a block of data from the stream up to length characters or up to EOLN if length is negative.

ReadData first looks for data into the readBuffers. While length is not satisfied, new data from the underlying stream are processed. The data is buffered as either string or PhpBytes but consistently. The type of the first buffer thus specifies the return type.

public ReadData ( int length, bool ending ) : TextElement
length	int	The number of bytes to return, when set to -1 /// reading carries on up to EOLN or EOF.
ending	bool	If true, the buffers are first searched for \n.
Résultat	TextElement

ReadFiltered() protected méthode

Fills the readBuffers with more data from the underlying stream passed through all the stream filters.

protected ReadFiltered ( int chunkSize ) : TextElement
chunkSize	int	Maximum number of bytes to be read from the stream.
Résultat	TextElement

ReadLine() public méthode

Reads one line (text ending with the ending delimiter) from the stream up to length characters long.

public ReadLine ( int length, string ending ) : string
length	int	Maximum length of the returned or -1 for unlimited reslut.
ending	string	Delimiter of the returned line or null to use the system default.
Résultat	string

ReadMaximumBytes() public méthode

Effecient access to the buffered and filtered stream consuming one whole buffer at a time.

public ReadMaximumBytes ( ) : byte[]
Résultat	byte[]

ReadMaximumData() public méthode

Most effecient access to the buffered stream consuming one whole buffer at a time. Performs no unnecessary conversions (although attached stream filters may do so).

Use the readChunkSize member to affect the amount of data returned at a time.

public ReadMaximumData ( ) : TextElement
Résultat	TextElement

ReadMaximumString() public méthode

Effecient access to the buffered and filtered stream consuming one whole buffer at a time.

public ReadMaximumString ( ) : string
Résultat	string

ReadString() public méthode

Reads text data from the stream. First looks for data into the readBuffers. When length is not satisfied, new data from the underlying stream are processed.

public ReadString ( int length ) : string
length	int	The number of characters to return.
Résultat	string

ReadStringContents() public méthode

public ReadStringContents ( int maxLength ) : string
maxLength	int
Résultat	string

ReadTextBuffer() protected méthode

Joins the read buffers to get at least length characters in a string.

It is assumed that there already is length bytes in the buffers. Otherwise an InvalidOperationException is raised.

If the buffers don't contain enough data.

protected ReadTextBuffer ( int length ) : string
length	int	The desired maximum result length.
Résultat	string

ResolvePath() public static méthode

Merges the path with the current working directory to get a canonicalized absolute pathname representing the same file.

This method is an analogy of main/safe_mode.c: php_checkuid. Looks for the file in the include_path and checks for open_basedir restrictions.

Security violation - when the target file /// lays outside the tree defined by open_basedir configuration option.

public static ResolvePath ( Context ctx, string &path, StreamWrapper &wrapper, CheckAccessMode mode, CheckAccessOptions options ) : bool
ctx	Pchp.Core.Context	Current runtime context.
path	string	An absolute or relative path to a file.
wrapper	StreamWrapper	The wrapper found for the specified file or null if the path resolution fails.
mode	CheckAccessMode	The checking mode of the method (file, directory etc.).
options	CheckAccessOptions	Additional options for the method.
Résultat	bool

Seek() public méthode

Sets the read/write pointer in the stream to a new position.

public Seek ( int offset, SeekOrigin whence ) : bool
offset	int	The offset from the position denoted by .
whence	SeekOrigin	One of the flags.
Résultat	bool

SetParameter() public méthode

public SetParameter ( StreamParameterOptions option, PhpValue value ) : bool
option	StreamParameterOptions
value	Pchp.Core.PhpValue
Résultat	bool

Stat() public méthode

public Stat ( ) : StatStruct
Résultat	StatStruct

Tell() public méthode

Gets the current position in the stream.

The problem with tell() in PHP is that although the write offset is calculated in the raw byte stream (just before buffering) the read one is calculated in the filtered string buffers. In other words the value returned by tell() for output streams is the real position in the raw stream but may differ from the number of characters written. On the other hand the value returned for input streams corresponds with the number of characters retreived but not with the position in the raw stream. It is important to remember that seeking on a filtered stream (such as a file opened with a "rt" mode) has undefined behavior.

public Tell ( ) : int
Résultat	int

WriteBytes() public méthode

Apppends the binary data to the output buffer passing through the output filter-chain. When the buffer is full or buffering is disabled, pass the data to the low-level stream.

public WriteBytes ( byte data ) : int
data	byte	The to store.
Résultat	int

WriteData() protected méthode

Passes the data through output filter-chain to the output buffer. When the buffer is full or buffering is disabled, passes the data to the low-level stream.

protected WriteData ( TextElement data, bool closing = false ) : int
data	TextElement	The data to store (filters will handle the type themselves).
closing	bool	true when this method is called from close() /// to prune all the pending filters with closing set to true.
Résultat	int

WriteString() public méthode

Apppends the text data to the output buffer passing through the output filter-chain. When the buffer is full or buffering is disabled, pass the data to the low-level stream.

public WriteString ( string data ) : int
data	string	The to store.
Résultat	int

Property Details

OpenedPath public_oe property

The absolute path to the resource.

public string OpenedPath
Résultat	string

Options public_oe property

Additional stream options defined at open-time.

public StreamAccessOptions Options
Résultat	StreamAccessOptions

Wrapper public_oe property

The StreamWrapper responsible for opening this stream.

Used for example to access the correct section of context and for wrapper-notifications too.

public StreamWrapper,Pchp.Library.Streams Wrapper
Résultat	StreamWrapper

_context protected_oe property

The stream context options resource.

protected StreamContext,Pchp.Library.Streams _context
Résultat	StreamContext

currentAccess protected_oe property

Gets the type of last stream access (initialized to FileAccess.ReadWrite if not accessed yet).

protected FileAccess currentAccess
Résultat	FileAccess

fgetssState protected_oe property

For fgetss() to handle multiline tags.

protected int fgetssState
Résultat	int

isPersistent protected_oe property

For future use. Persistent streams are not implemented so far.

protected bool isPersistent
Résultat	bool

isReadBuffered protected_oe property

Whether the read operations are interated for a single fread call.

protected bool isReadBuffered
Résultat	bool

readBuffers protected_oe property

Store the filtered input data queued as either strings or byte[].

protected Queue readBuffers
Résultat	Queue

readChunkSize protected_oe property

The default size of a single read chunk in the readBuffers.

protected int readChunkSize
Résultat	int

readFilteredCount protected_oe property

Total bytes passed through the ReadData function (after input filtering)

protected int readFilteredCount
Résultat	int

readFilters protected_oe property

The lists of StreamFilters associated with this stream.

protected List readFilters
Résultat	List

readOffset protected_oe property

The offset from the beginning of the raw stream to the first byte stored in the readBuffers.

This offset is incremented when a consumed buffer is dropped.

protected int readOffset
Résultat	int

readPosition protected_oe property

The position in the first buffer in the readBuffers.

protected int readPosition
Résultat	int

readTimeout protected_oe property

Timeout for network-based streams in seconds.

protected double readTimeout
Résultat	double

textReadFilter protected_oe property

The text-mode conversion filter of this stream used for reading.

protected IFilter textReadFilter
Résultat	IFilter

textWriteFilter protected_oe property

The text-mode conversion filter of this stream used for writing.

protected IFilter textWriteFilter
Résultat	IFilter

writeBuffer protected_oe property

Store the filtered output data in a byte[] up to writeBufferSize bytes.

protected byte[] writeBuffer
Résultat	byte[]

writeBufferSize protected_oe property

The maximum count of buffered output bytes. 0 to disable buffering.

protected int writeBufferSize
Résultat	int

writeFilteredCount protected_oe property

Total bytes passed through the WriteData function (before output filtering)

protected int writeFilteredCount
Résultat	int

writeOffset protected_oe property

The offset from the beginning of the raw stream to the first byte of the writeBuffer.

This offset is incremented when the buffer is being flushed or the data is written to a non-buffered stream.

protected int writeOffset
Résultat	int

writePosition protected_oe property

The actual write position in the writeBuffer.

protected int writePosition
Résultat	int