Doc #64292 [Com]: Missing documentation details for return value of DirectoryIterator::current()

Edit report at https://bugs.php.net/bug.php?id=64292&edit=1 ID: 64292 Comment by: maciej dot sz at gmail dot com Reported by: maciej dot sz at gmail dot com Summary: Missing documentation details for return value of DirectoryIterator::current() Status: Not a bug Type: Documentation Problem Package: Documentation problem Operating System: irrelevant PHP Version: Irrelevant Block user comment: N Private report: N New Comment: This was a "missing documentation" report, not a bug report. Could you please paste your response to the DirectoryIterator documentation as a note or something similar? Maybe here: http://www.php.net/manual/en/directoryiterator.current.php It should be included in documentation, because: a) This is a very common misconception as using DirectoryIterator recursively seems like a natural thing (and the documentation is not clear about this) b) This mistake can easily go unnoticed until late stages in application lifecycle Previous Comments: ------------------------------------------------------------------------ [2013-02-27 04:03:34] frozenfire@php.net This is not a bug. For recursively iterating directory contents, use RecursiveDirectoryIterator. DirectoryIterator is intended to give you a single level of directory contents that you can iterate. The current item is not a way to reference and iterate an item's children. ------------------------------------------------------------------------ [2013-02-24 15:19:15] maciej dot sz at gmail dot com Description: ------------ Since DirectoryIterator::current() returns itself there is many confusion while using it. It can't for instance be used as an argument of recursive method. Test script: --------------- foreach ( new DirectoryIterator(__DIR__) as $Current ) { var_dump($Di === $Current); } bool(true) bool(true) bool(true) ... Expected result: ---------------- In order to use DirectoryIterator object as a function parameter you MUST clone it: function iterateDirRecursive(DirectoryIterator $Di) { foreach ( $Di as $Item ) { $Current = clone $Item; // notice the clone here if ( $Current->isDir() && ! $Current->isDot() ) { iterateDirRecursive($Current); } } } iterateDirRecursive(new DirectoryIterator(__DIR__)); Actual result: -------------- Otherwise it will fail with "out of memory" or "maximum nesting level reached" depending on your PHP compilation: function iterateDirRecursive(DirectoryIterator $Di) { foreach ( $Di as $Item ) { $Current = $Item; // clone is missing if ( $Current->isDir() && ! $Current->isDot() ) { iterateDirRecursive($Current); } } } iterateDirRecursive(new DirectoryIterator(__DIR__)); ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=64292&edit=1