View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
Zend_Io
{zone-data}

{zone-data:proposer-list}
[Sven Vollbehr|mailto:svollbehr@gmail.com]
[Matthew Ratzloff|mailto:matthew@ratzloff.name]
[Jon Whitcraft|mailto:jon.zf@mac.com]
{zone-data}

{zone-data:liaison}
TBD
{zone-data}

{zone-data:revision}
1.1 - 8 August 2009
{zone-data}

{zone-data:overview}
Zend_Io is a package providing means to read/write primitive PHP types (string, integers, ...) to a character stream.
{zone-data}

{zone-data:references}
* [PHP Reader Project|http://php-reader.googlecode.com/]
{zone-data}

{zone-data:requirements}
* This component *will* read primitive PHP types from character streams.
* This component *will* write primitive PHP types into character streams.

{info:title=Please note}
It's possible to use regular PHP file functions to carry out operations on the same resource while it is used by Zend_Io_Reader.
{info}
{zone-data}

{zone-data:dependencies}
* Zend_Exception
{zone-data}

{zone-data:operation}

{zone-data}

{zone-data:milestones}
* DONE: Milestone 1: Working prototype transformed from existing code (necessary tasks: conform to Zend naming conventions, and refactor to support the new API described here).
* Milestone 2: Unit tests exist and work.
* Milestone 3: Initial documentation exists.
* Milestone 4: Moved to core.
{zone-data}

{zone-data:class-list}
* Zend_Io_Reader
* Zend_Io_FileReader
* Zend_Io_StringReader

* Zend_Io_Writer
* Zend_Io_FileWriter
* Zend_Io_StringWriter

* Zend_Io_Exception
{zone-data}

{zone-data:use-cases}
||UC-1||
{code}
// Initialize reader using an open file descriptor
$reader = new Zend_Io_Reader($fd);
{code}

||UC-2||
{code}
// Initialize reader using a path to the file
$reader = new Zend_Io_FileReader("../../path/to/file");
{code}

||UC-3||
{code}
// Initialize reader using string data
$reader = new Zend_Io_StringReader("arbitrary data");
{code}

||UC-4||
{code}
// Carry out basic read operations
$reader->seek(150);
$val = $reader->read(1); // reads 1 byte starting from offset 150
$val = $reader->getOffset(); // the current offset, 151
{code}

||UC-5||
{code}
// Carry out read operations with byte transformation
$val = $reader->readInt64LE(); // reads a 64 bit little-endian encoded integer
$val = $reader->readUInt32BE(); // reads an unsigned 32 bit big-endian encoded integer
$val = $reader->readGUID(); // reads a GUID
{code}
{zone-data}

{zone-data:skeletons}
||Zend_Io_Reader||
{code}
class Zend_Io_Reader
{
/** @var resource */
protected $_fd;

/**
* Constructs the Zend_Io_Reader class with given open file descriptor.
*
* @param resource $fd The file descriptor.
*/
public function __construct($fd) {}

/**
* Default destructor.
*/
public function __destruct() {}

/**
* Checks whether there is more to be read from the stream. Returns
* <var>true</var> if the end has not yet been reached; <var>false</var>
* otherwise.
*
* @return boolean
* @throws Zend_Io_Exception if an I/O error occurs
*/
public function available() {}

/**
* Returns the current point of operation.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public function getOffset() {}

/**
* Sets the point of operation, ie the cursor offset value. The offset may
* also be set to a negative value when it is interpreted as an offset from
* the end of the stream instead of the beginning.
*
* @param integer $offset The new point of operation.
* @return void
* @throws Zend_Io_Exception if an I/O error occurs
*/
public function setOffset($offset) {}

/**
* Returns the stream size in bytes.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public function getSize() {}

/**
* Returns the underlying stream file descriptor.
*
* @return resource
*/
public function getFileDescriptor() {}

/**
* Jumps <var>size</var> amount of bytes in the stream.
*
* @param integer $size The amount of bytes.
* @return void
* @throws Zend_Io_Exception if <var>size</var> attribute is negative or if
* an I/O error occurs
*/
public function skip($size) {}

/**
* Reads <var>length</var> amount of bytes from the stream.
*
* @param integer $length The amount of bytes.
* @return string
* @throws Zend_Io_Exception if <var>size</var> attribute is negative or if
* an I/O error occurs
*/
public function read($length) {}

/**
* Reads 1 byte from the stream and returns binary data as an 8-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readInt8() {}

/**
* Reads 1 byte from the stream and returns binary data as an unsigned 8-bit
* integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readUInt8() {}

/**
* Reads 2 bytes from the stream and returns little-endian ordered binary
* data as signed 16-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readInt16LE() {}

/**
* Reads 2 bytes from the stream and returns big-endian ordered binary data
* as signed 16-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readInt16BE() {}

/**
* Reads 2 bytes from the stream and returns little-endian ordered binary
* data as unsigned 16-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readUInt16LE() {}

/**
* Reads 2 bytes from the stream and returns big-endian ordered binary data
* as unsigned 16-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readUInt16BE() {}

/**
* Reads 3 bytes from the stream and returns little-endian ordered binary
* data as signed 24-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readInt24LE() {}

/**
* Reads 3 bytes from the stream and returns big-endian ordered binary data
* as signed 24-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readInt24BE() {}

/**
* Reads 3 bytes from the stream and returns little-endian ordered binary
* data as unsigned 24-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readUInt24LE() {}

/**
* Reads 3 bytes from the stream and returns big-endian ordered binary data
* as unsigned 24-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readUInt24BE() {}

/**
* Reads 4 bytes from the stream and returns little-endian ordered binary
* data as signed 32-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readInt32LE() {}

/**
* Reads 4 bytes from the stream and returns big-endian ordered binary data
* as signed 32-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readInt32BE() {}

/**
* Reads 4 bytes from the stream and returns little-endian ordered binary
* data as unsigned 32-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readUInt32LE() {}

/**
* Reads 4 bytes from the stream and returns big-endian ordered binary data
* as unsigned 32-bit integer.
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readUInt32BE() {}

/**
* Reads 8 bytes from the stream and returns little-endian ordered binary
* data as 64-bit float.
*
* {@internal PHP does not support 64-bit integers as the long
* integer is of 32-bits but using aritmetic operations it is implicitly
* converted into floating point which is of 64-bits long.}
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readInt64LE() {}

/**
* Reads 8 bytes from the stream and returns big-endian ordered binary data
* as 64-bit float.
*
* {@internal PHP does not support 64-bit integers as the long integer is of
* 32-bits but using aritmetic operations it is implicitly converted into
* floating point which is of 64-bits long.}
*
* @return integer
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readInt64BE() {}

/**
* Reads fixme bytes from the stream and returns the binary data as a
* floating point number.
*
* @return float
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readFloat() {}

/**
* Reads <var>length</var> amount of bytes from the stream and returns
* binary data as string. Removes terminating zero.
*
* @param integer $length The amount of bytes.
* @return string
* @throws Zend_Io_Exception if <var>length</var> attribute is negative or
* if an I/O error occurs
*/
public final function readString8($length) {}

/**
* Reads <var>length</var> amount of bytes from the stream and returns
* binary data as multibyte Unicode string. Removes terminating zero.
*
* The byte order is possibly determined from the byte order mark included
* in the binary data string. The order parameter is updated if the BOM is
* found.
*
* @param integer $length The amount of bytes.
* @param integer $order The endianess of the string.
* @param integer $trimOrder Whether to remove the byte order mark read the
* string.
* @return string
* @throws Zend_Io_Exception if <var>length</var> attribute is negative or
* if an I/O error occurs
*/
public final function readString16($length, &$order = null, $trimOrder = false) {}

/**
* Reads <var>length</var> amount of bytes from the stream and returns
* binary data as hexadecimal string having high nibble first.
*
* @param integer $length The amount of bytes.
* @return string
* @throws Zend_Io_Exception if <var>length</var> attribute is negative or
* if an I/O error occurs
*/
public final function readHHex($length) {}

/**
* Reads <var>length</var> amount of bytes from the stream and returns
* binary data as hexadecimal string having low nibble first.
*
* @param integer $length The amount of bytes.
* @return string
* @throws Zend_Io_Exception if <var>length</var> attribute is negative or
* if an I/O error occurs
*/
public final function readLHex($length) {}

/**
* Reads 16 bytes from the stream and returns the little-endian ordered
* binary data as mixed-ordered hexadecimal GUID string.
*
* @return string
* @throws Zend_Io_Exception if an I/O error occurs
*/
public final function readGUID() {}

/**
* Resets the stream. Attempts to reset it in some way appropriate to the
* particular stream, for example by repositioning it to its starting point.
*
* @return void
* @throws Zend_Io_Exception if an I/O error occurs
*/
public function reset() {}

/**
* Closes the stream. Once a stream has been closed, further calls to read
* methods will throw an exception. Closing a previously-closed stream,
* however, has no effect.
*
* @return void
* @throws Zend_Io_Exception if an I/O error occurs
*/
public function close() {}
}
{code}

||Zend_Io_FileReader||
{code}
class Zend_Io_FileReader
{
/**
* Constructs the Zend_Io_FileReader class with given file.
*
* @param string|Zend_Uri $filename The path to the file.
* @throws Zend_Io_Exception if the file cannot be read
*/
public function __construct($filename) {}

/**
* Closes the file descriptor.
*/
public function __destruct() {}
}
{code}

||Zend_Io_StringReader||
{code}
class Zend_Io_StringReader
{
/**
* Constructs the Zend_Io_StringReader class with given data.
*
* @param string $data The string to use as the data source.
* @throws Zend_Io_Exception if an I/O error occurs
*/
public function __construct($data) {}

/**
* Closes the file descriptor.
*/
public function __destruct() {}
}
{code}

{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>