Seeking

• Determine if Seekable
• Position
• Seek
  • Via seek()
  • Via positionAt()
• Rewind
  • Via rewind()
  • Via positionToStart()
  • Rewind after operation
• End
  • Determine if EOF
• Restore Position

Determine if Seekable

The isSeekable() method can be used to determine if a stream is seekable or not.

$a = FileStream::open('cities.txt', 'r+b');
$b = FileStream::make(fopen('php://output', 'r'));

echo $a->isSeekable(); // true
echo $b->isSeekable(); // false

Position

The current read/write pointer position can be obtained via two methods:

$position = $stream->tell();

// ...or via alias method

$position = $stream->position();

Both methods fail if unable to determine the pointer position (StreamException is thrown, if such is the case).

Seek

Via seek()

Use seek() to set the stream's read/write position. The method accepts two arguments:

• int $offset: streams offset
• int $whence: how the cursor position will be calculated based on the seek offset

$stream->seek(50, SEEK_SET);

For additional information, see PHP's documentation.

Via positionAt()

The positionAt() method is a "fluent" version of the seek() method. After read/write pointer position has been set, a reference to the stream instance is returned.

$position = $stream
    ->positionAt(50, SEEK_SET)
    ->position();

echo $position; // 50

Rewind

Via rewind()

The rewind() method sets the read/write pointer position to 0 (beginning of the file stream).

$stream->rewind();

Via positionToStart()

The positionToStart() methods is a "fluent" version of rewind().

$position = $stream
    ->positionToStart()
    ->position();

echo $position; // 0

Rewind after operation

When you need to perform some kind of operation on a stream and rewind it afterwards, then you can use the rewindAfter() method. It accepts a callback, which is executed and the position is thereafter rewound.

The callback is given the stream reference as argument.

$output = $stream
    ->rewindAfter(function($stream) {
        // ...do something with stream and return evt. output.
        
        return 'abc';
    });

echo $output; // abc
echo $stream->position(); // 0

End

Use positionToEnd() to move pointer position to the end of the stream (method is also "fluent").

$stream->positionToEnd();

Determine if EOF

To determine if position is at end-of-file (EOF), use the eof() method.

$atEnd = $stream
    ->positionToEnd()
    ->eof();

echo $atEnd; // true

Restore Position

When you need to restore the current read/write pointer position, after you have performed some kind of operation, then you use the restorePositionAfter() method.

$output = $stream
    ->positionAt(50)
    ->restorePositionAfter(function($stream) {
        return (string) $stream;
    });

echo $output; // (stream's content)
echo $stream->position(); // 50