php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login

go to bug id or search bugs for

Doc Bug #79256 generator->next() not behaving as documented.
Submitted: 2020-02-11 10:39 UTC Modified: 2020-03-13 18:08 UTC
From: selanefa at outlook dot com Assigned: ekin (profile)
Status: Closed Package: Unknown/Other Function
PHP Version: 7.2.27 OS: Ubuntu 18.04.3
Private report: No CVE-ID: None
View Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
If you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: selanefa at outlook dot com
New email:
PHP Version: OS:

 

 [2020-02-11 10:39 UTC] selanefa at outlook dot com 
Description:
------------
---
From manual page: https://php.net/generator.next
---

The documentation states:
Calling Generator::next() is equivalent to calling Generator::send() with NULL as argument. 

However, calling Generator::send(null) moves the pointer and returns the current value, while Generator::next() only moves the pointer and returns nothing.




Test script:
---------------
function generateCountdown(int $start) {
            while ($start>=0) {
                yield $start--;
            }
        }

$gen = generateCountdown(3);

echo $gen->current().PHP_EOL;
echo $gen->send(null).PHP_EOL;
echo $gen->send(null).PHP_EOL;
$gen->next();
echo $gen->current().PHP_EOL;

Expected result:
----------------
3
2
1
0

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2020-02-13 17:41 UTC] ekin@php.net 
Hi, I see your point, though the signature documented should make it obvious that Generator::next() will not return a value:

public Generator::next ( void ) : void

Is it confusing enough to need clarification, knowing the signature mentions the return type?
 [2020-02-14 13:34 UTC] peehaa@php.net 
I agree with OP here. They are not exactly equivalent.

Maybe just remove the description and at a note with something like:

> calling Generator::send() will already advance so there is no need to manually call Generator::next()

?
 [2020-02-14 13:35 UTC] peehaa@php.net
-Status: Open +Status: Assigned -Assigned To: +Assigned To: ekin
 [2020-02-14 13:37 UTC] ekin@php.net 
Yeah, I can see that if you're not coming from the Generator::send() page this comment alone can confuse one.
 [2020-02-16 14:45 UTC] ekin@php.net 
Looking at this again, I see why that comment is valid.

Calling next() is actually equivalent to send(null), in that they would both advance and also give you NULL. https://3v4l.org/WokSV

Attempting to use the return value of a void function will evaluate to NULL, with no warnings emitted. This is what's happening in the next() case.
 [2020-03-13 18:07 UTC] cmb@php.net 
Automatic comment from SVN on behalf of cmb
Revision: http://svn.php.net/viewvc/?view=revision&revision=349409
Log: Fix #79256: Generator::next not behaving as documented

Patch provided by ekin@php.net.
 [2020-03-13 18:08 UTC] cmb@php.net
-Status: Assigned +Status: Closed
 [2020-03-13 18:08 UTC] phpdocbot@php.net 
Automatic comment on behalf of cmb
Revision: http://git.php.net/?p=doc/en.git;a=commit;h=3c28f4f9d08ed6b7694853493eb4ac4c1d799615
Log: Fix #79256: Generator::next not behaving as documented
 [2020-03-13 21:18 UTC] mumumu@php.net 
Automatic comment from SVN on behalf of mumumu
Revision: http://svn.php.net/viewvc/?view=revision&revision=349414
Log: Fix #79256: Generator::next not behaving as documented
 [2020-03-13 21:20 UTC] phpdocbot@php.net 
Automatic comment on behalf of mumumu
Revision: http://git.php.net/?p=doc/ja.git;a=commit;h=fd1bded710f2ce0847cb871b4784f1f707e6e452
Log: Fix #79256: Generator::next not behaving as documented
 [2020-12-30 11:59 UTC] nikic@php.net 
Automatic comment on behalf of mumumu
Revision: http://git.php.net/?p=doc/ja.git;a=commit;h=74efba96fc22c9e3413dbce75ae3a7b259c7bd11
Log: Fix #79256: Generator::next not behaving as documented
 
PHP Copyright © 2001-2025 The PHP Group
All rights reserved. 		Last updated: Fri Oct 31 22:00:01 2025 UTC