Iterators

Table of Contents

AppendIterator — The AppendIterator class
- AppendIterator::append — Appends an iterator
- AppendIterator::__construct — Constructs an AppendIterator
- AppendIterator::current — Gets the current value
- AppendIterator::getArrayIterator — Gets the ArrayIterator
- AppendIterator::getInnerIterator — Gets the inner iterator
- AppendIterator::getIteratorIndex — Gets an index of iterators
- AppendIterator::key — Gets the current key
- AppendIterator::next — Moves to the next element
- AppendIterator::rewind — Rewinds the Iterator
- AppendIterator::valid — Checks validity of the current element
ArrayIterator — The ArrayIterator class
- ArrayIterator::append — Append an element
- ArrayIterator::asort — Sort array by values
- ArrayIterator::__construct — Construct an ArrayIterator
- ArrayIterator::count — Count elements
- ArrayIterator::current — Return current array entry
- ArrayIterator::getArrayCopy — Get array copy
- ArrayIterator::getFlags — Get flags
- ArrayIterator::key — Return current array key
- ArrayIterator::ksort — Sort array by keys
- ArrayIterator::natcasesort — Sort an array naturally, case insensitive
- ArrayIterator::natsort — Sort an array naturally
- ArrayIterator::next — Move to next entry
- ArrayIterator::offsetExists — Check if offset exists
- ArrayIterator::offsetGet — Get value for an offset
- ArrayIterator::offsetSet — Set value for an offset
- ArrayIterator::offsetUnset — Unset value for an offset
- ArrayIterator::rewind — Rewind array back to the start
- ArrayIterator::seek — Seek to position
- ArrayIterator::serialize — Serialize
- ArrayIterator::setFlags — Set behaviour flags
- ArrayIterator::uasort — User defined sort
- ArrayIterator::uksort — User defined sort
- ArrayIterator::unserialize — Unserialize
- ArrayIterator::valid — Check whether array contains more entries
CachingIterator — The CachingIterator class
- CachingIterator::__construct — Construct a new CachingIterator object for the iterator.
- CachingIterator::count — The number of elements in the iterator
- CachingIterator::current — Return the current element
- CachingIterator::getCache — The getCache purpose
- CachingIterator::getFlags — Get flags used
- CachingIterator::getInnerIterator — Returns the inner iterator
- CachingIterator::hasNext — Check whether the inner iterator has a valid next element
- CachingIterator::key — Return the key for the current element
- CachingIterator::next — Move the iterator forward
- CachingIterator::offsetExists — The offsetExists purpose
- CachingIterator::offsetGet — The offsetGet purpose
- CachingIterator::offsetSet — The offsetSet purpose
- CachingIterator::offsetUnset — The offsetUnset purpose
- CachingIterator::rewind — Rewind the iterator
- CachingIterator::setFlags — The setFlags purpose
- CachingIterator::__toString — Return the string representation of the current element
- CachingIterator::valid — Check whether the current element is valid
CallbackFilterIterator — The CallbackFilterIterator class
- CallbackFilterIterator::accept — Calls the callback with the current value, the current key and the inner iterator as arguments
- CallbackFilterIterator::__construct — Create a filtered iterator from another iterator
DirectoryIterator — The DirectoryIterator class
- DirectoryIterator::__construct — Constructs a new directory iterator from a path
- DirectoryIterator::current — Return the current DirectoryIterator item.
- DirectoryIterator::getATime — Get last access time of the current DirectoryIterator item
- DirectoryIterator::getBasename — Get base name of current DirectoryIterator item.
- DirectoryIterator::getCTime — Get inode change time of the current DirectoryIterator item
- DirectoryIterator::getExtension — Gets the file extension
- DirectoryIterator::getFilename — Return file name of current DirectoryIterator item.
- DirectoryIterator::getGroup — Get group for the current DirectoryIterator item
- DirectoryIterator::getInode — Get inode for the current DirectoryIterator item
- DirectoryIterator::getMTime — Get last modification time of current DirectoryIterator item
- DirectoryIterator::getOwner — Get owner of current DirectoryIterator item
- DirectoryIterator::getPath — Get path of current Iterator item without filename
- DirectoryIterator::getPathname — Return path and file name of current DirectoryIterator item
- DirectoryIterator::getPerms — Get the permissions of current DirectoryIterator item
- DirectoryIterator::getSize — Get size of current DirectoryIterator item
- DirectoryIterator::getType — Determine the type of the current DirectoryIterator item
- DirectoryIterator::isDir — Determine if current DirectoryIterator item is a directory
- DirectoryIterator::isDot — Determine if current DirectoryIterator item is '.' or '..'
- DirectoryIterator::isExecutable — Determine if current DirectoryIterator item is executable
- DirectoryIterator::isFile — Determine if current DirectoryIterator item is a regular file
- DirectoryIterator::isLink — Determine if current DirectoryIterator item is a symbolic link
- DirectoryIterator::isReadable — Determine if current DirectoryIterator item can be read
- DirectoryIterator::isWritable — Determine if current DirectoryIterator item can be written to
- DirectoryIterator::key — Return the key for the current DirectoryIterator item
- DirectoryIterator::next — Move forward to next DirectoryIterator item
- DirectoryIterator::rewind — Rewind the DirectoryIterator back to the start
- DirectoryIterator::seek — Seek to a DirectoryIterator item
- DirectoryIterator::__toString — Get file name as a string
- DirectoryIterator::valid — Check whether current DirectoryIterator position is a valid file
EmptyIterator — The EmptyIterator class
- EmptyIterator::current — The current() method
- EmptyIterator::key — The key() method
- EmptyIterator::next — The next() method
- EmptyIterator::rewind — The rewind() method
- EmptyIterator::valid — The valid() method
FilesystemIterator — The FilesystemIterator class
- FilesystemIterator::__construct — Constructs a new filesystem iterator
- FilesystemIterator::current — The current file
- FilesystemIterator::getFlags — Get the handling flags
- FilesystemIterator::key — Retrieve the key for the current file
- FilesystemIterator::next — Move to the next file
- FilesystemIterator::rewind — Rewinds back to the beginning
- FilesystemIterator::setFlags — Sets handling flags
FilterIterator — The FilterIterator class
- FilterIterator::accept — Check whether the current element of the iterator is acceptable
- FilterIterator::__construct — Construct a filterIterator
- FilterIterator::current — Get the current element value
- FilterIterator::getInnerIterator — Get the inner iterator
- FilterIterator::key — Get the current key
- FilterIterator::next — Move the iterator forward
- FilterIterator::rewind — Rewind the iterator
- FilterIterator::valid — Check whether the current element is valid
GlobIterator — The GlobIterator class
- GlobIterator::__construct — Construct a directory using glob
- GlobIterator::count — Get the number of directories and files
InfiniteIterator — The InfiniteIterator class
- InfiniteIterator::__construct — Constructs an InfiniteIterator
- InfiniteIterator::next — Moves the inner Iterator forward or rewinds it
IteratorIterator — The IteratorIterator class
- IteratorIterator::__construct — Create an iterator from anything that is traversable
- IteratorIterator::current — Get the current value
- IteratorIterator::getInnerIterator — Get the inner iterator
- IteratorIterator::key — Get the key of the current element
- IteratorIterator::next — Forward to the next element
- IteratorIterator::rewind — Rewind to the first element
- IteratorIterator::valid — Checks if the iterator is valid
LimitIterator — The LimitIterator class
- LimitIterator::__construct — Construct a LimitIterator
- LimitIterator::current — Get current element
- LimitIterator::getInnerIterator — Get inner iterator
- LimitIterator::getPosition — Return the current position
- LimitIterator::key — Get current key
- LimitIterator::next — Move the iterator forward
- LimitIterator::rewind — Rewind the iterator to the specified starting offset
- LimitIterator::seek — Seek to the given position
- LimitIterator::valid — Check whether the current element is valid
MultipleIterator — The MultipleIterator class
- MultipleIterator::attachIterator — Attaches iterator information
- MultipleIterator::__construct — Constructs a new MultipleIterator
- MultipleIterator::containsIterator — Checks if an iterator is attached
- MultipleIterator::countIterators — Gets the number of attached iterator instances
- MultipleIterator::current — Gets the registered iterator instances
- MultipleIterator::detachIterator — Detaches an iterator
- MultipleIterator::getFlags — Gets the flag information
- MultipleIterator::key — Gets the registered iterator instances
- MultipleIterator::next — Moves all attached iterator instances forward
- MultipleIterator::rewind — Rewinds all attached iterator instances
- MultipleIterator::setFlags — Sets flags
- MultipleIterator::valid — Checks the validity of sub iterators
NoRewindIterator — The NoRewindIterator class
- NoRewindIterator::__construct — Construct a NoRewindIterator
- NoRewindIterator::current — Get the current value
- NoRewindIterator::getInnerIterator — Get the inner iterator
- NoRewindIterator::key — Get the current key
- NoRewindIterator::next — Forward to the next element
- NoRewindIterator::rewind — Prevents the rewind operation on the inner iterator.
- NoRewindIterator::valid — Validates the iterator
ParentIterator — The ParentIterator class
- ParentIterator::accept — Determines acceptability
- ParentIterator::__construct — Constructs a ParentIterator
- ParentIterator::getChildren — Return the inner iterator's children contained in a ParentIterator
- ParentIterator::hasChildren — Check whether the inner iterator's current element has children
- ParentIterator::next — Move the iterator forward
- ParentIterator::rewind — Rewind the iterator
RecursiveArrayIterator — The RecursiveArrayIterator class
- RecursiveArrayIterator::getChildren — Returns an iterator for the current entry if it is an array or an object.
- RecursiveArrayIterator::hasChildren — Returns whether current entry is an array or an object.
RecursiveCachingIterator — The RecursiveCachingIterator class
- RecursiveCachingIterator::__construct — Construct
- RecursiveCachingIterator::getChildren — Return the inner iterator's children as a RecursiveCachingIterator
- RecursiveCachingIterator::hasChildren — Check whether the current element of the inner iterator has children
RecursiveCallbackFilterIterator — The RecursiveCallbackFilterIterator class
- RecursiveCallbackFilterIterator::__construct — Create a RecursiveCallbackFilterIterator from a RecursiveIterator
- RecursiveCallbackFilterIterator::getChildren — Return the inner iterator's children contained in a RecursiveCallbackFilterIterator
- RecursiveCallbackFilterIterator::hasChildren — Check whether the inner iterator's current element has children
RecursiveDirectoryIterator — The RecursiveDirectoryIterator class
- RecursiveDirectoryIterator::__construct — Constructs a RecursiveDirectoryIterator
- RecursiveDirectoryIterator::getChildren — Returns an iterator for the current entry if it is a directory
- RecursiveDirectoryIterator::getSubPath — Get sub path
- RecursiveDirectoryIterator::getSubPathname — Get sub path and name
- RecursiveDirectoryIterator::hasChildren — Returns whether current entry is a directory and not '.' or '..'
- RecursiveDirectoryIterator::key — Return path and filename of current dir entry
- RecursiveDirectoryIterator::next — Move to next entry
- RecursiveDirectoryIterator::rewind — Rewind dir back to the start
RecursiveFilterIterator — The RecursiveFilterIterator class
- RecursiveFilterIterator::__construct — Create a RecursiveFilterIterator from a RecursiveIterator
- RecursiveFilterIterator::getChildren — Return the inner iterator's children contained in a RecursiveFilterIterator
- RecursiveFilterIterator::hasChildren — Check whether the inner iterator's current element has children
RecursiveIteratorIterator — The RecursiveIteratorIterator class
- RecursiveIteratorIterator::beginChildren — Begin children
- RecursiveIteratorIterator::beginIteration — Begin Iteration
- RecursiveIteratorIterator::callGetChildren — Get children
- RecursiveIteratorIterator::callHasChildren — Has children
- RecursiveIteratorIterator::__construct — Construct a RecursiveIteratorIterator
- RecursiveIteratorIterator::current — Access the current element value
- RecursiveIteratorIterator::endChildren — End children
- RecursiveIteratorIterator::endIteration — End Iteration
- RecursiveIteratorIterator::getDepth — Get the current depth of the recursive iteration
- RecursiveIteratorIterator::getInnerIterator — Get inner iterator
- RecursiveIteratorIterator::getMaxDepth — Get max depth
- RecursiveIteratorIterator::getSubIterator — The current active sub iterator
- RecursiveIteratorIterator::key — Access the current key
- RecursiveIteratorIterator::next — Move forward to the next element
- RecursiveIteratorIterator::nextElement — Next element
- RecursiveIteratorIterator::rewind — Rewind the iterator to the first element of the top level inner iterator
- RecursiveIteratorIterator::setMaxDepth — Set max depth
- RecursiveIteratorIterator::valid — Check whether the current position is valid
RecursiveRegexIterator — The RecursiveRegexIterator class
- RecursiveRegexIterator::__construct — Creates a new RecursiveRegexIterator.
- RecursiveRegexIterator::getChildren — Returns an iterator for the current entry.
- RecursiveRegexIterator::hasChildren — Returns whether an iterator can be obtained for the current entry.
RecursiveTreeIterator — The RecursiveTreeIterator class
- RecursiveTreeIterator::beginChildren — Begin children
- RecursiveTreeIterator::beginIteration — Begin iteration
- RecursiveTreeIterator::callGetChildren — Get children
- RecursiveTreeIterator::callHasChildren — Has children
- RecursiveTreeIterator::__construct — Construct a RecursiveTreeIterator
- RecursiveTreeIterator::current — Get current element
- RecursiveTreeIterator::endChildren — End children
- RecursiveTreeIterator::endIteration — End iteration
- RecursiveTreeIterator::getEntry — Get current entry
- RecursiveTreeIterator::getPostfix — Get the postfix
- RecursiveTreeIterator::getPrefix — Get the prefix
- RecursiveTreeIterator::key — Get the key of the current element
- RecursiveTreeIterator::next — Move to next element
- RecursiveTreeIterator::nextElement — Next element
- RecursiveTreeIterator::rewind — Rewind iterator
- RecursiveTreeIterator::setPrefixPart — Set a part of the prefix
- RecursiveTreeIterator::valid — Check validity
RegexIterator — The RegexIterator class
- RegexIterator::accept — Get accept status
- RegexIterator::__construct — Create a new RegexIterator
- RegexIterator::getFlags — Get flags
- RegexIterator::getMode — Returns operation mode.
- RegexIterator::getPregFlags — Returns the regular expression flags.
- RegexIterator::getRegex — Returns current regular expression
- RegexIterator::setFlags — Sets the flags.
- RegexIterator::setMode — Sets the operation mode.
- RegexIterator::setPregFlags — Sets the regular expression flags.

SPL provides a set of iterators to traverse over objects.

SPL Iterators Class Tree

ArrayIterator
- RecursiveArrayIterator
EmptyIterator
IteratorIterator
- AppendIterator
- CachingIterator
  - RecursiveCachingIterator
- FilterIterator
  - CallbackFilterIterator
    - RecursiveCallbackFilterIterator
  - RecursiveFilterIterator
    - ParentIterator
  - RegexIterator
    - RecursiveRegexIterator
- InfiniteIterator
- LimitIterator
- NoRewindIterator
MultipleIterator
RecursiveIteratorIterator
- RecursiveTreeIterator
DirectoryIterator (extends SplFileInfo)
- FilesystemIterator
  - GlobIterator
  - RecursiveDirectoryIterator

The AppendIterator class

Introduction

An Iterator that iterates over several iterators one after the other.

Class synopsis

AppendIterator

class AppendIterator extends IteratorIterator implements OuterIterator {

/* Methods */

public __construct ( void )

public void append ( Iterator $iterator )

public mixed current ( void )

public void getArrayIterator ( void )

public Iterator getInnerIterator ( void )

public int getIteratorIndex ( void )

public scalar key ( void )

public void next ( void )

public void rewind ( void )

public bool valid ( void )

/* Inherited methods */

public IteratorIterator::__construct ( Traversable $iterator )

public mixed IteratorIterator::current ( void )

public Traversable IteratorIterator::getInnerIterator ( void )

public scalar IteratorIterator::key ( void )

public void IteratorIterator::next ( void )

public void IteratorIterator::rewind ( void )

public bool IteratorIterator::valid ( void )

}

The ArrayIterator class

Introduction

This iterator allows to unset and modify values and keys while iterating over Arrays and Objects.

When you want to iterate over the same array multiple times you need to instantiate ArrayObject and let it create ArrayIterator instances that refer to it either by using foreach or by calling its getIterator() method manually.

Class synopsis

ArrayIterator

class ArrayIterator implements ArrayAccess , SeekableIterator , Countable , Serializable {

/* Methods */

public void append ( mixed $value )

public void asort ( void )

public __construct ([ mixed $array = array() [, int $flags = 0 ]] )

public int count ( void )

public mixed current ( void )

public array getArrayCopy ( void )

public void getFlags ( void )

public mixed key ( void )

public void ksort ( void )

public void natcasesort ( void )

public void natsort ( void )

public void next ( void )

public void offsetExists ( string $index )

public mixed offsetGet ( string $index )

public void offsetSet ( string $index , string $newval )

public void offsetUnset ( string $index )

public void rewind ( void )

public void seek ( int $position )

public string serialize ( void )

public void setFlags ( string $flags )

public void uasort ( string $cmp_function )

public void uksort ( string $cmp_function )

public string unserialize ( string $serialized )

public bool valid ( void )

}

The CachingIterator class

Introduction

This object supports cached iteration over another iterator.

Class synopsis

CachingIterator

class CachingIterator extends IteratorIterator implements OuterIterator , ArrayAccess , Countable {

/* Constants */

const integer CachingIterator::CALL_TOSTRING = 1 ;

const integer CachingIterator::CATCH_GET_CHILD = 16 ;

const integer CachingIterator::TOSTRING_USE_KEY = 2 ;

const integer CachingIterator::TOSTRING_USE_CURRENT = 4 ;

const integer CachingIterator::TOSTRING_USE_INNER = 8 ;

const integer CachingIterator::FULL_CACHE = 256 ;

/* Methods */

public __construct ( Iterator $iterator [, string $flags = self::CALL_TOSTRING ] )

public int count ( void )

public void current ( void )

public void getCache ( void )

public void getFlags ( void )

public Iterator getInnerIterator ( void )

public void hasNext ( void )

public scalar key ( void )

public void next ( void )

public void offsetExists ( string $index )

public void offsetGet ( string $index )

public void offsetSet ( string $index , string $newval )

public void offsetUnset ( string $index )

public void rewind ( void )

public void setFlags ( bitmask $flags )

public void __toString ( void )

public void valid ( void )

}

Predefined Constants

CachingIterator::CALL_TOSTRING: Convert every element to string.
CachingIterator::CATCH_GET_CHILD: Don't throw exception in accessing children.
CachingIterator::TOSTRING_USE_KEY: Use key for conversion to string.
CachingIterator::TOSTRING_USE_CURRENT: Use current for conversion to string.
CachingIterator::TOSTRING_USE_INNER: Use inner for conversion to string.
CachingIterator::FULL_CACHE: Cache all read data.

The CallbackFilterIterator class

Introduction

Class synopsis

CallbackFilterIterator

class CallbackFilterIterator extends FilterIterator implements OuterIterator {

/* Methods */

public __construct ( Iterator $iterator , callable $callback )

public string accept ( void )

/* Inherited methods */

public abstract bool FilterIterator::accept ( void )

public FilterIterator::__construct ( Iterator $iterator )

public mixed FilterIterator::current ( void )

public Iterator FilterIterator::getInnerIterator ( void )

public mixed FilterIterator::key ( void )

public void FilterIterator::next ( void )

public void FilterIterator::rewind ( void )

public bool FilterIterator::valid ( void )

}

Examples

The callback should accept up to three arguments: the current item, the current key and the iterator, respectively.

Example #1 Available callback arguments


<?php

/**
 * Callback for CallbackFilterIterator
 *
 * @param $current   Current item's value
 * @param $key       Current item's key
 * @param $iterator  Iterator being filtered
 * @return boolean   TRUE to accept the current item, FALSE otherwise
 */
function my_callback($current, $key, $iterator) {
    // Your filtering code here
}

?>

Any callable may be used; such as a string containing a function name, an array for a method, or an anonymous function.

Example #2 Callback basic examples


<?php

$dir = new FilesystemIterator(__DIR__);

// Filter large files ( > 100MB)
function is_large_file($current) {
    return $current->isFile() && $current->getSize() > 104857600;
}
$large_files = new CallbackFilterIterator($dir, 'is_large_file');

// Filter directories
$files = new CallbackFilterIterator($dir, function ($current, $key, $iterator) {
    return $current->isDir() && ! $iterator->isDot();
});

?>

The DirectoryIterator class

Introduction

The DirectoryIterator class provides a simple interface for viewing the contents of filesystem directories.

Class synopsis

DirectoryIterator

class DirectoryIterator extends SplFileInfo implements SeekableIterator {

/* Methods */

public __construct ( string $path )

public DirectoryIterator current ( void )

public int getATime ( void )

public string getBasename ([ string $suffix ] )

public int getCTime ( void )

public string getExtension ( void )

public string getFilename ( void )

public int getGroup ( void )

public int getInode ( void )

public int getMTime ( void )

public int getOwner ( void )

public string getPath ( void )

public string getPathname ( void )

public int getPerms ( void )

public int getSize ( void )

public string getType ( void )

public bool isDir ( void )

public bool isDot ( void )

public bool isExecutable ( void )

public bool isFile ( void )

public bool isLink ( void )

public bool isReadable ( void )

public bool isWritable ( void )

public string key ( void )

public void next ( void )

public void rewind ( void )

public void seek ( int $position )

public string __toString ( void )

public bool valid ( void )

}

Changelog

Version	Description
5.1.2	DirectoryIterator extends SplFileInfo.

The EmptyIterator class

Introduction

The EmptyIterator class for an empty iterator.

Class synopsis

EmptyIterator

class EmptyIterator implements Iterator {

/* Methods */

public void current ( void )

public void key ( void )

public void next ( void )

public void rewind ( void )

public void valid ( void )

}

The FilesystemIterator class

Introduction

The Filesystem iterator

Class synopsis

FilesystemIterator

class FilesystemIterator extends DirectoryIterator implements SeekableIterator {

/* Constants */

const integer FilesystemIterator::CURRENT_AS_PATHNAME = 32 ;

const integer FilesystemIterator::CURRENT_AS_FILEINFO = 0 ;

const integer FilesystemIterator::CURRENT_AS_SELF = 16 ;

const integer FilesystemIterator::CURRENT_MODE_MASK = 240 ;

const integer FilesystemIterator::KEY_AS_PATHNAME = 0 ;

const integer FilesystemIterator::KEY_AS_FILENAME = 256 ;

const integer FilesystemIterator::FOLLOW_SYMLINKS = 512 ;

const integer FilesystemIterator::KEY_MODE_MASK = 3840 ;

const integer FilesystemIterator::NEW_CURRENT_AND_KEY = 256 ;

const integer FilesystemIterator::SKIP_DOTS = 4096 ;

const integer FilesystemIterator::UNIX_PATHS = 8192 ;

/* Methods */

public __construct ( string $path [, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS ] )

public mixed current ( void )

public int getFlags ( void )

public string key ( void )

public void next ( void )

public void rewind ( void )

public void setFlags ([ int $flags ] )

/* Inherited methods */

public DirectoryIterator DirectoryIterator::current ( void )

public int DirectoryIterator::getATime ( void )

public string DirectoryIterator::getBasename ([ string $suffix ] )

public int DirectoryIterator::getCTime ( void )

public string DirectoryIterator::getExtension ( void )

public string DirectoryIterator::getFilename ( void )

public int DirectoryIterator::getGroup ( void )

public int DirectoryIterator::getInode ( void )

public int DirectoryIterator::getMTime ( void )

public int DirectoryIterator::getOwner ( void )

public string DirectoryIterator::getPath ( void )

public string DirectoryIterator::getPathname ( void )

public int DirectoryIterator::getPerms ( void )

public int DirectoryIterator::getSize ( void )

public string DirectoryIterator::getType ( void )

public bool DirectoryIterator::isDir ( void )

public bool DirectoryIterator::isDot ( void )

public bool DirectoryIterator::isExecutable ( void )

public bool DirectoryIterator::isFile ( void )

public bool DirectoryIterator::isLink ( void )

public bool DirectoryIterator::isReadable ( void )

public bool DirectoryIterator::isWritable ( void )

public string DirectoryIterator::key ( void )

public void DirectoryIterator::next ( void )

public void DirectoryIterator::rewind ( void )

public void DirectoryIterator::seek ( int $position )

public string DirectoryIterator::__toString ( void )

public bool DirectoryIterator::valid ( void )

}

Predefined Constants

FilesystemIterator::CURRENT_AS_PATHNAME: Makes FilesystemIterator::current return the pathname.
FilesystemIterator::CURRENT_AS_FILEINFO: Makes FilesystemIterator::current return an SplFileInfo instance.
FilesystemIterator::CURRENT_AS_SELF: Makes FilesystemIterator::current return $this (the FilesystemIterator).
FilesystemIterator::CURRENT_MODE_MASK: Masks FilesystemIterator::current
FilesystemIterator::KEY_AS_PATHNAME: Makes FilesystemIterator::key return the pathname.
FilesystemIterator::KEY_AS_FILENAME: Makes FilesystemIterator::key return the filename.
FilesystemIterator::FOLLOW_SYMLINKS: Makes RecursiveDirectoryIterator::hasChildren follow symlinks.
FilesystemIterator::KEY_MODE_MASK: Masks FilesystemIterator::key
FilesystemIterator::NEW_CURRENT_AND_KEY: Same as FilesystemIterator::KEY_AS_FILENAME | FilesystemIterator::CURRENT_AS_FILEINFO.
FilesystemIterator::SKIP_DOTS: Skips dot files (. and ..).
FilesystemIterator::UNIX_PATHS: Makes paths use Unix-style forward slash irrespective of system default.

Changelog

Version	Description
5.3.1	Added `FilesystemIterator::FOLLOW_SYMLINKS`

The FilterIterator class

Introduction

This abstract iterator filters out unwanted values. This class should be extended to implement custom iterator filters. The FilterIterator::accept must be implemented in the subclass.

Class synopsis

FilterIterator

abstract class FilterIterator extends IteratorIterator implements OuterIterator {

/* Methods */

public abstract bool accept ( void )

public __construct ( Iterator $iterator )

public mixed current ( void )

public Iterator getInnerIterator ( void )

public mixed key ( void )

public void next ( void )

public void rewind ( void )

public bool valid ( void )

}

The GlobIterator class

Introduction

Iterates through a file system in a similar fashion to glob.

Class synopsis

GlobIterator

class GlobIterator extends FilesystemIterator implements SeekableIterator , Countable {

/* Methods */

public __construct ( string $path [, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO ] )

public int count ( void )

/* Inherited methods */

public FilesystemIterator::__construct ( string $path [, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS ] )

public mixed FilesystemIterator::current ( void )

public int FilesystemIterator::getFlags ( void )

public string FilesystemIterator::key ( void )

public void FilesystemIterator::next ( void )

public void FilesystemIterator::rewind ( void )

public void FilesystemIterator::setFlags ([ int $flags ] )

}

The InfiniteIterator class

Introduction

The InfiniteIterator allows one to infinitely iterate over an iterator without having to manually rewind the iterator upon reaching its end.

Class synopsis

InfiniteIterator

class InfiniteIterator extends IteratorIterator implements OuterIterator {

/* Methods */

public __construct ( Iterator $iterator )

public void next ( void )

/* Inherited methods */

public IteratorIterator::__construct ( Traversable $iterator )

public mixed IteratorIterator::current ( void )

public Traversable IteratorIterator::getInnerIterator ( void )

public scalar IteratorIterator::key ( void )

public void IteratorIterator::next ( void )

public void IteratorIterator::rewind ( void )

public bool IteratorIterator::valid ( void )

}

The IteratorIterator class

Introduction

This iterator wrapper allows the conversion of anything that is Traversable into an Iterator. It is important to understand that most classes that do not implement Iterators have reasons as most likely they do not allow the full Iterator feature set. If so, techniques should be provided to prevent misuse, otherwise expect exceptions or fatal errors.

Class synopsis

IteratorIterator

class IteratorIterator implements OuterIterator {

/* Methods */

public __construct ( Traversable $iterator )

public mixed current ( void )

public Traversable getInnerIterator ( void )

public scalar key ( void )

public void next ( void )

public void rewind ( void )

public bool valid ( void )

}

The LimitIterator class

Introduction

The LimitIterator class allows iteration over a limited subset of items in an Iterator.

Class synopsis

LimitIterator

class LimitIterator extends IteratorIterator implements OuterIterator {

/* Methods */

public __construct ( Iterator $iterator [, int $offset = 0 [, int $count = -1 ]] )

public mixed current ( void )

public Iterator getInnerIterator ( void )

public int getPosition ( void )

public mixed key ( void )

public void next ( void )

public void rewind ( void )

public int seek ( int $position )

public bool valid ( void )

}

Examples

Example #1 LimitIterator usage example


<?php

// Create an iterator to be limited
$fruits = new ArrayIterator(array(
    'apple',
    'banana',
    'cherry',
    'damson',
    'elderberry'
));

// Loop over first three fruits only
foreach (new LimitIterator($fruits, 0, 3) as $fruit) {
    var_dump($fruit);
}

echo "\n";

// Loop from third fruit until the end
// Note: offset starts from zero for apple
foreach (new LimitIterator($fruits, 2) as $fruit) {
    var_dump($fruit);
}

?>

The above example will output:

string(5) "apple"
string(6) "banana"
string(6) "cherry"

string(6) "cherry"
string(6) "damson"
string(10) "elderberry"

The MultipleIterator class

Introduction

An Iterator that sequentially iterates over all attached iterators

Class synopsis

MultipleIterator

class MultipleIterator implements Iterator {

/* Constants */

const integer MultipleIterator::MIT_NEED_ANY = 0 ;

const integer MultipleIterator::MIT_NEED_ALL = 1 ;

const integer MultipleIterator::MIT_KEYS_NUMERIC = 0 ;

const integer MultipleIterator::MIT_KEYS_ASSOC = 2 ;

/* Methods */

public __construct ([ int $flags = MultipleIterator::MIT_NEED_ALL|MultipleIterator::MIT_KEYS_NUMERIC ] )

public void attachIterator ( Iterator $iterator [, string $infos ] )

public void containsIterator ( Iterator $iterator )

public void countIterators ( void )

public array current ( void )

public void detachIterator ( Iterator $iterator )

public void getFlags ( void )

public array key ( void )

public void next ( void )

public void rewind ( void )

public void setFlags ( int $flags )

public void valid ( void )

}

Predefined Constants

MultipleIterator::MIT_NEED_ANY: Do not require all sub iterators to be valid in iteration.
MultipleIterator::MIT_NEED_ALL: Require all sub iterators to be valid in iteration.
MultipleIterator::MIT_KEYS_NUMERIC: Keys are created from the sub iterators position.
MultipleIterator::MIT_KEYS_ASSOC: Keys are created from sub iterators associated information.

The NoRewindIterator class

Introduction

This iterator cannot be rewound.

Class synopsis

NoRewindIterator

class NoRewindIterator extends IteratorIterator {

/* Methods */

public __construct ( Iterator $iterator )

public mixed current ( void )

public iterator getInnerIterator ( void )

public mixed key ( void )

public void next ( void )

public void rewind ( void )

public bool valid ( void )

/* Inherited methods */

public IteratorIterator::__construct ( Traversable $iterator )

public mixed IteratorIterator::current ( void )

public Traversable IteratorIterator::getInnerIterator ( void )

public scalar IteratorIterator::key ( void )

public void IteratorIterator::next ( void )

public void IteratorIterator::rewind ( void )

public bool IteratorIterator::valid ( void )

}

The ParentIterator class

Introduction

This extended FilterIterator allows a recursive iteration using RecursiveIteratorIterator that only shows those elements which have children.

Class synopsis

ParentIterator

class ParentIterator extends RecursiveFilterIterator implements RecursiveIterator , OuterIterator {

/* Methods */

public bool accept ( void )

public __construct ( RecursiveIterator $iterator )

public ParentIterator getChildren ( void )

public bool hasChildren ( void )

public void next ( void )

public void rewind ( void )

}

The RecursiveArrayIterator class

Introduction

This iterator allows to unset and modify values and keys while iterating over Arrays and Objects in the same way as the ArrayIterator. Additionally it is possible to iterate over the current iterator entry.

Class synopsis

RecursiveArrayIterator

class RecursiveArrayIterator extends ArrayIterator implements RecursiveIterator {

/* Methods */

public RecursiveArrayIterator getChildren ( void )

public bool hasChildren ( void )

/* Inherits */

public void ArrayIterator::append ( mixed $value )

public void ArrayIterator::asort ( void )

public ArrayIterator::__construct ([ mixed $array = array() [, int $flags = 0 ]] )

public int ArrayIterator::count ( void )

public mixed ArrayIterator::current ( void )

public array ArrayIterator::getArrayCopy ( void )

public void ArrayIterator::getFlags ( void )

public mixed ArrayIterator::key ( void )

public void ArrayIterator::ksort ( void )

public void ArrayIterator::natcasesort ( void )

public void ArrayIterator::natsort ( void )

public void ArrayIterator::next ( void )

public void ArrayIterator::offsetExists ( string $index )

public mixed ArrayIterator::offsetGet ( string $index )

public void ArrayIterator::offsetSet ( string $index , string $newval )

public void ArrayIterator::offsetUnset ( string $index )

public void ArrayIterator::rewind ( void )

public void ArrayIterator::seek ( int $position )

public string ArrayIterator::serialize ( void )

public void ArrayIterator::setFlags ( string $flags )

public void ArrayIterator::uasort ( string $cmp_function )

public void ArrayIterator::uksort ( string $cmp_function )

public string ArrayIterator::unserialize ( string $serialized )

public bool ArrayIterator::valid ( void )

}

The RecursiveCachingIterator class

Introduction

...

Class synopsis

RecursiveCachingIterator

class RecursiveCachingIterator extends CachingIterator implements Countable , ArrayAccess , OuterIterator , RecursiveIterator {

/* Methods */

public __construct ( Iterator $iterator [, string $flags = self::CALL_TOSTRING ] )

public RecursiveCachingIterator getChildren ( void )

public bool hasChildren ( void )

/* Inherits */

public CachingIterator::__construct ( Iterator $iterator [, string $flags = self::CALL_TOSTRING ] )

public int CachingIterator::count ( void )

public void CachingIterator::current ( void )

public void CachingIterator::getCache ( void )

public void CachingIterator::getFlags ( void )

public Iterator CachingIterator::getInnerIterator ( void )

public void CachingIterator::hasNext ( void )

public scalar CachingIterator::key ( void )

public void CachingIterator::next ( void )

public void CachingIterator::offsetExists ( string $index )

public void CachingIterator::offsetGet ( string $index )

public void CachingIterator::offsetSet ( string $index , string $newval )

public void CachingIterator::offsetUnset ( string $index )

public void CachingIterator::rewind ( void )

public void CachingIterator::setFlags ( bitmask $flags )

public void CachingIterator::__toString ( void )

public void CachingIterator::valid ( void )

}

The RecursiveCallbackFilterIterator class

Introduction

Class synopsis

RecursiveCallbackFilterIterator

class RecursiveCallbackFilterIterator extends CallbackFilterIterator implements OuterIterator , RecursiveIterator {

/* Methods */

public __construct ( RecursiveIterator $iterator , string $callback )

public RecursiveCallbackFilterIterator getChildren ( void )

public void hasChildren ( void )

/* Inherited methods */

public string CallbackFilterIterator::accept ( void )

}

Examples

The callback should accept up to three arguments: the current item, the current key and the iterator, respectively.

Example #1 Available callback arguments


<?php

/**
 * Callback for RecursiveCallbackFilterIterator
 *
 * @param $current   Current item's value
 * @param $key       Current item's key
 * @param $iterator  Iterator being filtered
 * @return boolean   TRUE to accept the current item, FALSE otherwise
 */
function my_callback($current, $key, $iterator) {
    // Your filtering code here
}

?>

Filtering a recursive iterator generally involves two conditions. The first is that, to allow recursion, the callback function should return TRUE if the current iterator item has children. The second is the normal filter condition, such as a file size or extension check as in the example below.

Example #2 Recursive callback basic example


<?php

$dir = new RecursiveDirectoryIterator(__DIR__);

// Filter large files ( > 100MB)
$files = new RecursiveCallbackFilterIterator($dir, function ($current, $key, $iterator) {
    // Allow recursion
    if ($iterator->hasChildren()) {
        return TRUE;
    }
    // Check for large file
    if ($current->isFile() && $current->getSize() > 104857600) {
        return TRUE;
    }
    return FALSE;
});
 
foreach (new RecursiveIteratorIterator($files) as $file) {
    echo $file->getPathname() . PHP_EOL;
}

?>

The RecursiveDirectoryIterator class

Introduction

The RecursiveDirectoryIterator provides an interface for iterating recursively over filesystem directories.

Class synopsis

RecursiveDirectoryIterator

class RecursiveDirectoryIterator extends FilesystemIterator implements SeekableIterator , RecursiveIterator {

/* Methods */

public __construct ( string $path [, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO ] )

public mixed getChildren ( void )

public string getSubPath ( void )

public string getSubPathname ( void )

public bool hasChildren ([ bool $allow_links = false ] )

public string key ( void )

public void next ( void )

public void rewind ( void )

/* Inherits */

public FilesystemIterator::__construct ( string $path [, int $flags = FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS ] )

public mixed FilesystemIterator::current ( void )

public int FilesystemIterator::getFlags ( void )

public string FilesystemIterator::key ( void )

public void FilesystemIterator::next ( void )

public void FilesystemIterator::rewind ( void )

public void FilesystemIterator::setFlags ([ int $flags ] )

}

Changelog

Version	Description
5.3.0	The FilesystemIterator was introduced as the parent class. Previously, the parent was the DirectoryIterator.
5.3.0	Implements SeekableIterator.
5.2.11, 5.3.1	Added `RecursiveDirectoryIterator::FOLLOW_SYMLINKS`

The RecursiveFilterIterator class

Introduction

This abstract iterator filters out unwanted values for a RecursiveIterator. This class should be extended to implement custom filters. The RecursiveFilterIterator::accept must be implemented in the subclass.

Class synopsis

RecursiveFilterIterator

abstract class RecursiveFilterIterator extends FilterIterator implements OuterIterator , RecursiveIterator {

/* Methods */

public __construct ( RecursiveIterator $iterator )

public void getChildren ( void )

public void hasChildren ( void )

/* Inherited methods */

public abstract bool FilterIterator::accept ( void )

public FilterIterator::__construct ( Iterator $iterator )

public mixed FilterIterator::current ( void )

public Iterator FilterIterator::getInnerIterator ( void )

public mixed FilterIterator::key ( void )

public void FilterIterator::next ( void )

public void FilterIterator::rewind ( void )

public bool FilterIterator::valid ( void )

}

The RecursiveIteratorIterator class

Introduction

Can be used to iterate through recursive iterators.

Class synopsis

RecursiveIteratorIterator

class RecursiveIteratorIterator implements OuterIterator {

/* Constants */

const integer RecursiveIteratorIterator::LEAVES_ONLY = 0 ;

const integer RecursiveIteratorIterator::SELF_FIRST = 1 ;

const integer RecursiveIteratorIterator::CHILD_FIRST = 2 ;

const integer RecursiveIteratorIterator::CATCH_GET_CHILD = 16 ;

/* Methods */

public void beginChildren ( void )

public void beginIteration ( void )

public RecursiveIterator callGetChildren ( void )

public bool callHasChildren ( void )

public __construct ( Traversable $iterator [, int $mode = RecursiveIteratorIterator::LEAVES_ONLY [, int $flags = 0 ]] )

public mixed current ( void )

public void endChildren ( void )

public void endIteration ( void )

public int getDepth ( void )

public iterator getInnerIterator ( void )

public mixed getMaxDepth ( void )

public RecursiveIterator getSubIterator ([ int $level ] )

public mixed key ( void )

public void next ( void )

public void nextElement ( void )

public void rewind ( void )

public void setMaxDepth ([ string $max_depth = -1 ] )

public bool valid ( void )

/* Inherited methods */

public Iterator OuterIterator::getInnerIterator ( void )

}

Predefined Constants

RecursiveIteratorIterator::LEAVES_ONLY
RecursiveIteratorIterator::SELF_FIRST
RecursiveIteratorIterator::CHILD_FIRST
RecursiveIteratorIterator::CATCH_GET_CHILD

The RecursiveRegexIterator class

Introduction

This recursive iterator can filter another recursive iterator via a regular expression.

Class synopsis

RecursiveRegexIterator

class RecursiveRegexIterator extends RegexIterator implements RecursiveIterator {

/* Methods */

public __construct ( RecursiveIterator $iterator , string $regex [, int $mode = self::MATCH [, int $flags = 0 [, int $preg_flags = 0 ]]] )

public RecursiveRegexIterator getChildren ( void )

public bool hasChildren ( void )

/* Inherited methods */

public RecursiveIterator RecursiveIterator::getChildren ( void )

public bool RecursiveIterator::hasChildren ( void )

public bool RegexIterator::accept ( void )

public int RegexIterator::getFlags ( void )

public int RegexIterator::getMode ( void )

public int RegexIterator::getPregFlags ( void )

public string RegexIterator::getRegex ( void )

public void RegexIterator::setFlags ( int $flags )

public void RegexIterator::setMode ( int $mode )

public void RegexIterator::setPregFlags ( int $preg_flags )

}

The RecursiveTreeIterator class

Introduction

Allows iterating over a RecursiveIterator to generate an ASCII graphic tree.

Class synopsis

RecursiveTreeIterator

class RecursiveTreeIterator extends RecursiveIteratorIterator implements OuterIterator {

/* Constants */

const integer RecursiveTreeIterator::BYPASS_CURRENT = 4 ;

const integer RecursiveTreeIterator::BYPASS_KEY = 8 ;

const integer RecursiveTreeIterator::PREFIX_LEFT = 0 ;

const integer RecursiveTreeIterator::PREFIX_MID_HAS_NEXT = 1 ;

const integer RecursiveTreeIterator::PREFIX_MID_LAST = 2 ;

const integer RecursiveTreeIterator::PREFIX_END_HAS_NEXT = 3 ;

const integer RecursiveTreeIterator::PREFIX_END_LAST = 4 ;

const integer RecursiveTreeIterator::PREFIX_RIGHT = 5 ;

/* Methods */

public void beginChildren ( void )

public RecursiveIterator beginIteration ( void )

public RecursiveIterator callGetChildren ( void )

public bool callHasChildren ( void )

public __construct ( RecursiveIterator|IteratorAggregate $it [, int $flags = RecursiveTreeIterator::BYPASS_KEY [, int $cit_flags = CachingIterator::CATCH_GET_CHILD [, int $mode = RecursiveIteratorIterator::SELF_FIRST ]]] )

public string current ( void )

public void endChildren ( void )

public void endIteration ( void )

public string getEntry ( void )

public void getPostfix ( void )

public string getPrefix ( void )

public string key ( void )

public void next ( void )

public void nextElement ( void )

public void rewind ( void )

public void setPrefixPart ( int $part , string $value )

public bool valid ( void )

/* Inherited methods */

public void RecursiveIteratorIterator::beginChildren ( void )

public void RecursiveIteratorIterator::beginIteration ( void )

public RecursiveIterator RecursiveIteratorIterator::callGetChildren ( void )

public bool RecursiveIteratorIterator::callHasChildren ( void )

public RecursiveIteratorIterator::__construct ( Traversable $iterator [, int $mode = RecursiveIteratorIterator::LEAVES_ONLY [, int $flags = 0 ]] )

public mixed RecursiveIteratorIterator::current ( void )

public void RecursiveIteratorIterator::endChildren ( void )

public void RecursiveIteratorIterator::endIteration ( void )

public int RecursiveIteratorIterator::getDepth ( void )

public iterator RecursiveIteratorIterator::getInnerIterator ( void )

public mixed RecursiveIteratorIterator::getMaxDepth ( void )

public RecursiveIterator RecursiveIteratorIterator::getSubIterator ([ int $level ] )

public mixed RecursiveIteratorIterator::key ( void )

public void RecursiveIteratorIterator::next ( void )

public void RecursiveIteratorIterator::nextElement ( void )

public void RecursiveIteratorIterator::rewind ( void )

public void RecursiveIteratorIterator::setMaxDepth ([ string $max_depth = -1 ] )

public bool RecursiveIteratorIterator::valid ( void )

}

Predefined Constants

RecursiveTreeIterator::BYPASS_CURRENT
RecursiveTreeIterator::BYPASS_KEY
RecursiveTreeIterator::PREFIX_LEFT
RecursiveTreeIterator::PREFIX_MID_HAS_NEXT
RecursiveTreeIterator::PREFIX_MID_LAST
RecursiveTreeIterator::PREFIX_END_HAS_NEXT
RecursiveTreeIterator::PREFIX_END_LAST
RecursiveTreeIterator::PREFIX_RIGHT

The RegexIterator class

Introduction

This iterator can be used to filter another iterator based on a regular expression.

Class synopsis

RegexIterator

class RegexIterator extends FilterIterator {

/* Constants */

const integer MATCH = 0 ;

const integer GET_MATCH = 1 ;

const integer ALL_MATCHES = 2 ;

const integer SPLIT = 3 ;

const integer REPLACE = 4 ;

const integer USE_KEY = 1 ;

/* Methods */

public __construct ( Iterator $iterator , string $regex [, int $mode = self::MATCH [, int $flags = 0 [, int $preg_flags = 0 ]]] )

public bool accept ( void )

public int getFlags ( void )

public int getMode ( void )

public int getPregFlags ( void )

public string getRegex ( void )

public void setFlags ( int $flags )

public void setMode ( int $mode )

public void setPregFlags ( int $preg_flags )

/* Inherited methods */

public abstract bool FilterIterator::accept ( void )

public FilterIterator::__construct ( Iterator $iterator )

public mixed FilterIterator::current ( void )

public Iterator FilterIterator::getInnerIterator ( void )

public mixed FilterIterator::key ( void )

public void FilterIterator::next ( void )

public void FilterIterator::rewind ( void )

public bool FilterIterator::valid ( void )

}

Predefined Constants

RegexIterator operation modes

RegexIterator::ALL_MATCHES: Return all matches for the current entry (see preg_match_all).
RegexIterator::GET_MATCH: Return the first match for the current entry (see preg_match).
RegexIterator::MATCH: Only execute match (filter) for the current entry (see preg_match).
RegexIterator::REPLACE: Replace the current entry (see preg_replace; Not fully implemented yet)
RegexIterator::SPLIT: Returns the split values for the current entry (see preg_split).

RegexIterator Flags

RegexIterator::USE_KEY: Special flag: Match the entry key instead of the entry value.