{"id":716,"date":"2013-09-15T17:34:53","date_gmt":"2013-09-15T15:34:53","guid":{"rendered":"http:\/\/codingexplained.com\/?p=716"},"modified":"2017-06-11T22:09:48","modified_gmt":"2017-06-11T20:09:48","slug":"introduction-to-php-generators","status":"publish","type":"post","link":"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators","title":{"rendered":"Introduction to PHP Generators"},"content":{"rendered":"

One of the key features of PHP 5.5 is the implementation of so-called generators<\/em> with the yield<\/span> keyword. The purpose of this article is to give you an overview of PHP generators and why they are an important addition to the PHP language.<\/p>\n

What is a Generator?<\/h3>\n

Before we get into the details of generators, I will first begin by introducing generators by explaining what they can do and why they matter.<\/p>\n

A generator is similar to the regular functions that we already know. Generators generate<\/em> data to be iterated over but does not return this data with the return<\/span> keyword as would normally be the case. The difference is that a generator gradually makes data available to whatever code uses it instead of building the entire data set and then<\/em> returning it, at which point the execution of the function ends. For instance, consider PHP’s range<\/span> function which builds an array of integers such as from 1 to 100 and then returns it. A generator would yield<\/em> each number one by one as they are requested – perhaps by a foreach<\/span> loop. Therefore values are made available as they are needed, which is the same as the Just in time<\/em> (JIT) terminology. Therefore a generator is called every time a foreach<\/span> loop needs more data, and every time a generator yields a value, the state of the generator is saved internally such that it can be resumed when additional values are needed.<\/p>\n

Once there are no more values to be yielded from the generator, then the generator function can simply exit and stop execution. The calling code (e.g. a foreach<\/span> loop) then continues just as if it were using an array that has run out of values.<\/p>\n

The key to understanding generators is thus that the generator function provides a piece of data to the calling code. When this code requests more data, the execution of the generator is continued, hence why the state of the generator is maintained internally.<\/p>\n

Do not worry if all of this sounds confusing at first; this is all easier to understand with code examples. Below I have made an implementation of a function that is quite similar to PHP’s range<\/span> function.<\/p>\n

\/**\r\n * Returns an array of integers between $from and $to (similar to range())\r\n *\r\n * @param int $from\r\n * @param int $to\r\n *\r\n * @return int[]\r\n *\/\r\nfunction getNumberRange($from, $to) {\r\n\t\/\/ Parameter validation excluded for simplicity\r\n\t\r\n\t$results = array();\r\n\r\n\twhile ($from <= $to) {\r\n\t\t$results[] = $from;\r\n\t\t$from++;\r\n\t}\r\n\t\r\n\treturn $results;\r\n}<\/code><\/pre>\n
The function above is indeed quite simple; it builds an array of integers and returns it. To use it, we could simply call it within a foreach<\/span> loop to print out the numbers.<\/p>\n
foreach (getNumberRange(1, 10) as $number) {\r\n\techo $number . '...';\r\n}\r\n\r\n\/\/ Output: 1...2...3...4...5...6...7...8...9...10...<\/code><\/pre>\n
What happens is that the getNumberRange<\/span> function generates all of its result and returns it, and then<\/em> the foreach<\/span> loop begins to iterate on this result set, which is an array.<\/p>\n
If we were to implement the same functionality with a generator, which is available since PHP 5.5, then we could change the getNumberRange<\/span> like below.<\/p>\n
\/**\r\n * Yields integers between $from and $to\r\n *\r\n * @param int $from\r\n * @param int $to\r\n *\/\r\nfunction getNumberRangeGenerator($from, $to) {\r\n\twhile ($from <= $to) {\r\n\t\tyield $from;\r\n\t\t$from++;\r\n\t}\r\n}<\/code><\/pre>\n
The first thing to note is that no return<\/span> keyword is being used to return the results. Instead, the yield<\/span> keyword comes into play. For each iteration of the while<\/span> loop, an integer is yielded or \"made available\" to the code that uses the generator, such that data is provided without having to build the entire array first. Below is an example of how this generator can be used.<\/p>\n
foreach (getNumberRangeGenerator(1, 10) as $number) {\r\n\techo $number . '...';\r\n}\r\n\r\n\/\/ Output: 1...2...3...4...5...6...7...8...9...10...<\/code><\/pre>\n
As you can see in the above example, using the generator is exactly the same as if it had been a regular function returning an array. Instead of waiting for the entire array to be returned, the foreach<\/span> loop begins to iterate when the first value is yielded. When the loop is ready to continue iterate, the generator is prompted for another value and so forth.<\/p>\n
Why Generators are Important<\/h3>\n
Initially, this may not seem like a big deal. However, imagine the following example. For whatever reason, we have to build an array of integers between 1 and 1,000,000. With a traditional function, this array would have to be constructed before it could be used. The important thing to note here is the memory footprint this causes; that is a lot of memory that is required just for holding these values! More often than not, each value just has to be used once before it can effectively be removed from memory. As such, this leaves us with a waste of the server's resources. Instead, each value can be made available individually (by yielding from a generator) to a foreach loop, which means that the server no longer needs to hold all of the values in memory, but merely a single value at a time. This would effectively reduce the memory usage from over 100 MB to less than 1 KB!<\/p>\n
Can't I Just Implement the Iterator Interface?<\/h3>\n
By now you might be asking yourself if you cannot just implement the Iterator<\/span> interface. You can<\/em>, but you will find that you end up writing a lot of boilerplate code every time. Such code is not necessary with generators as this all happens behind the scenes and is completely abstracted from the developers. As such, what happens internally is that a Generator<\/span> object is created for us when a generator is initially called. This object takes care of managing the state of the generator; the Generator<\/span> class fortunately implements the Iterator<\/span> interface, so we do not have to implement this ourselves. In the end there is nothing stopping you from implementing the interface on your own, but it is less convenient. This is particularly evident in this example<\/a>.<\/p>\n
Yielding Key-Value Pairs<\/h3>\n
If you need to return a key-value pair, you will be happy to know that this is possible from within a generator, too. The syntax can be seen in the example below.<\/p>\n
\/**\r\n * Yields key-value pairs. Key: first name, value: last name\r\n *\r\n * @param array $users\r\n *\/\r\nfunction getUserNames(array $users) {\r\n\t$i = 0;\r\n\t$userCount = count($users);\r\n\t\r\n\twhile ($i < $userCount) {\r\n\t\tyield $users[$i]['firstName'] => $users[$i]['lastName'];\r\n\t\r\n\t\t$i++;\r\n\t}\r\n}<\/code><\/pre>\n<\/p>\n
$users = array(\r\n\t0 => array(\r\n\t\t'firstName' => 'Antoine',\r\n\t\t'lastName' => 'Cryan',\r\n\t),\r\n\t1 => array(\r\n\t\t'firstName' => 'Krystina',\r\n\t\t'lastName' => 'Peasley',\r\n\t),\r\n\t2 => array(\r\n\t\t'firstName' => 'Jenice',\r\n\t\t'lastName' => 'Sepeda',\r\n\t),\r\n);\r\n\r\n\/\/ Print out the names of the users\r\nforeach (getUserNames($users) as $firstName => $lastName) {\r\n\techo $firstName . ' ' . $lastName . '<br \/>';\r\n}\r\n\r\n\/\/ Output:
\r\nAntoine Cryan
\r\nKrystina Peasley
\r\nJenice Sepeda<\/code><\/pre>\n
Of course the above could be accomplished solely with the foreach<\/span> loop, so it is merely an example of how key-value pairs can be yielded from a generator.<\/p>\n
Stopping Execution of Generators<\/h3>\n
I previously mentioned that generators do not return data, and attempting to do so will result in a syntax error. However, the return<\/span> keyword on its own can be used to stop the execution of a generator - exactly as is possible in a regular function.<\/p>\n
\/**\r\n * Yields the integers that up till a given number\r\n *\r\n * @param int $stop\r\n *\r\n *\/\r\nfunction rangeStop($stop) {\r\n\tif (!is_int($stop) || $stop <= 0) {\r\n\t\treturn;\r\n\t}\r\n\r\n\t$i = 0;\r\n\t\r\n\twhile ($i < $stop) {\r\n\t\tyield $i;\r\n\r\n\t\t$i++;\r\n\t}\r\n}<\/code><\/pre>\n
The above example stops the generator if it is called with an invalid parameter. In practice, you would, however, probably want to throw an exception instead.<\/p>\n
Yielding by Reference<\/h3>\n
In the generators we have discussed so far, we have been yielding by value<\/em>. This means that when the values are iterated upon, one cannot change the values within the generator from which they originated. The same principle applies to regular functions; parameters are passed by value by default, meaning that a copy<\/em> of the data is used within the function. As such, the parameters are so-called local variables that are automatically cleared from memory when they run out of scope (which in this case means that the function ends). If one wanted to change a parameter such that it is reflected outside of the function, one can pass these by reference<\/em>. To do so, simply prepend an ampersand &<\/span> to the function name as well as the parameter name. Explaining this in details is outside the scope of this article, but it is important to understand this as it is the basis for yielding by reference. If you need to refresh your memory, then the official documentation<\/a> is an excellent choice.<\/p>\n
Applying this to generators is simple. All one has to do is to prepend an ampersand to the name of the generator and to the variable used in the iteration. That is all.<\/p>\n
\/**\r\n * Loops while $from > 0 and yields $from on each iteration. Yields by reference.\r\n *\r\n * @param int $from\r\n *\/\r\nfunction &countdown($from) {\r\n\twhile ($from > 0) {\r\n\t\tyield $from;\r\n\t}\r\n}\r\n\r\nforeach (countdown(10) as &$value) {\r\n\t$value--;\r\n\techo $value . '...';\r\n}\r\n\r\n\/\/ Output: 9...8...7...6...5...4...3...2...1...0...<\/code><\/pre>\n
The above example shows how changing the iterated values within the foreach<\/span> loop changes the $from<\/span> variable within the generator. This is because $from<\/span> is yielded by reference due to the ampersand before the generator name. As such, the $value<\/span> variable within the foreach<\/span> loop is a reference to the $from<\/span> variable within the generator function.<\/p>\n
Yielding NULL<\/span> Values<\/h3>\n
In functions you can return NULL<\/span>, and in generators you can yield NULL<\/span>. The latter is done by simply leaving out a value after the yield<\/span> keyword or alternatively to enter NULL<\/span>, as demonstrated below.<\/p>\n
function yieldNullImplicitly() {\r\n\tyield; \/\/ Yields NULL\r\n}\r\n\r\nfunction yieldNullExplicitly() {\r\n\tyield null;\r\n}<\/code><\/pre>\n
The generators above are equivalent.<\/p>\n
Conclusion<\/h3>\n
There is surely more to generators than what has been covered in this article. However, you should now have a good understanding of how generators work and what the advantages of using them are.<\/p>\n
I began by explaining how generators yield values to the calling code one by one rather than building an entire result set at once as would normally be the case. This means that to iterate on a sequence of 100 values, for instance, the web server only needs to store one value in memory at a time. Without a generator function, all 100 would have to be stored in memory, leading to high memory consumption.<\/p>\n
We have also seen how implementing a generator is simpler than implementing the Iterator<\/span> interface as this would require a lot of boilerplate code. Instead, generators handle the details of this behind the scenes, making developers' jobs easier. We have also seen how generators can yield key-value pairs instead of only single values and how this can be paired with a foreach<\/span> loop. Lastly, I demonstrated how values can be yielded by reference, meaning that the values used within generators can be changed from the calling code - exactly as with regular functions.<\/p>\n
I hope that this article has given you a good understanding of how generators work in PHP 5.5. Generators are powerful once you get the hang of it. Thank you for reading!<\/p>\n","protected":false},"excerpt":{"rendered":"
With the release of PHP 5.5, so-called generator functions are now available. Generators can among others be used to decrease the memory usage of your web server. This article gives you an overview of the generators in PHP 5.5.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"jetpack_post_was_ever_published":false,"jetpack_publicize_message":"","jetpack_is_tweetstorm":false,"jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","enabled":false}}},"categories":[6],"tags":[76,40,78,77],"series":[],"jetpack_publicize_connections":[],"yoast_head":"\nIntroduction to PHP Generators<\/title>\n<meta name=\"description\" content=\"With the release of PHP 5.5, generators became available. Read what generator functions are and why they are such an important addition to PHP.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Introduction to PHP Generators\" \/>\n<meta property=\"og:description\" content=\"With the release of PHP 5.5, generators became available. Read what generator functions are and why they are such an important addition to PHP.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators\" \/>\n<meta property=\"og:site_name\" content=\"Coding Explained\" \/>\n<meta property=\"article:publisher\" content=\"https:\/\/www.facebook.com\/codingexplained\" \/>\n<meta property=\"article:author\" content=\"https:\/\/www.facebook.com\/codingexplained\" \/>\n<meta property=\"article:published_time\" content=\"2013-09-15T15:34:53+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2017-06-11T20:09:48+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/codingexplained.com\/wp-content\/uploads\/2015\/11\/codingexplained-fb-promote.png\" \/>\n\t<meta property=\"og:image:width\" content=\"1200\" \/>\n\t<meta property=\"og:image:height\" content=\"444\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"author\" content=\"Bo Andersen\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@codingexplained\" \/>\n<meta name=\"twitter:site\" content=\"@codingexplained\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Bo Andersen\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"5 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators\",\"url\":\"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators\",\"name\":\"Introduction to PHP Generators\",\"isPartOf\":{\"@id\":\"https:\/\/codingexplained.com\/#website\"},\"datePublished\":\"2013-09-15T15:34:53+00:00\",\"dateModified\":\"2017-06-11T20:09:48+00:00\",\"author\":{\"@id\":\"https:\/\/codingexplained.com\/#\/schema\/person\/e19c92ec991f571605f047cefeaa950d\"},\"description\":\"With the release of PHP 5.5, generators became available. Read what generator functions are and why they are such an important addition to PHP.\",\"breadcrumb\":{\"@id\":\"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/codingexplained.com\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Introduction to PHP Generators\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/codingexplained.com\/#website\",\"url\":\"https:\/\/codingexplained.com\/\",\"name\":\"Coding Explained\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/codingexplained.com\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/codingexplained.com\/#\/schema\/person\/e19c92ec991f571605f047cefeaa950d\",\"name\":\"Bo Andersen\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/codingexplained.com\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/28f5826f9d5d544b0c5e1ec321dfdfb8?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/28f5826f9d5d544b0c5e1ec321dfdfb8?s=96&d=mm&r=g\",\"caption\":\"Bo Andersen\"},\"description\":\"I am a back-end web developer with a passion for open source technologies. I have been a PHP developer for many years, and also have experience with Java and Spring Framework. I currently work full time as a lead developer. Apart from that, I also spend time on making online courses, so be sure to check those out!\",\"sameAs\":[\"https:\/\/codingexplained.com\",\"https:\/\/www.facebook.com\/codingexplained\",\"https:\/\/www.linkedin.com\/in\/ba0708\",\"https:\/\/twitter.com\/codingexplained\",\"https:\/\/www.youtube.com\/c\/codingexplained\"],\"url\":\"https:\/\/codingexplained.com\/author\/andy\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Introduction to PHP Generators","description":"With the release of PHP 5.5, generators became available. Read what generator functions are and why they are such an important addition to PHP.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators","og_locale":"en_US","og_type":"article","og_title":"Introduction to PHP Generators","og_description":"With the release of PHP 5.5, generators became available. Read what generator functions are and why they are such an important addition to PHP.","og_url":"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators","og_site_name":"Coding Explained","article_publisher":"https:\/\/www.facebook.com\/codingexplained","article_author":"https:\/\/www.facebook.com\/codingexplained","article_published_time":"2013-09-15T15:34:53+00:00","article_modified_time":"2017-06-11T20:09:48+00:00","og_image":[{"width":1200,"height":444,"url":"https:\/\/codingexplained.com\/wp-content\/uploads\/2015\/11\/codingexplained-fb-promote.png","type":"image\/png"}],"author":"Bo Andersen","twitter_card":"summary_large_image","twitter_creator":"@codingexplained","twitter_site":"@codingexplained","twitter_misc":{"Written by":"Bo Andersen","Est. reading time":"5 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators","url":"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators","name":"Introduction to PHP Generators","isPartOf":{"@id":"https:\/\/codingexplained.com\/#website"},"datePublished":"2013-09-15T15:34:53+00:00","dateModified":"2017-06-11T20:09:48+00:00","author":{"@id":"https:\/\/codingexplained.com\/#\/schema\/person\/e19c92ec991f571605f047cefeaa950d"},"description":"With the release of PHP 5.5, generators became available. Read what generator functions are and why they are such an important addition to PHP.","breadcrumb":{"@id":"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/codingexplained.com\/coding\/php\/introduction-to-php-generators#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/codingexplained.com\/"},{"@type":"ListItem","position":2,"name":"Introduction to PHP Generators"}]},{"@type":"WebSite","@id":"https:\/\/codingexplained.com\/#website","url":"https:\/\/codingexplained.com\/","name":"Coding Explained","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/codingexplained.com\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/codingexplained.com\/#\/schema\/person\/e19c92ec991f571605f047cefeaa950d","name":"Bo Andersen","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/codingexplained.com\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/28f5826f9d5d544b0c5e1ec321dfdfb8?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/28f5826f9d5d544b0c5e1ec321dfdfb8?s=96&d=mm&r=g","caption":"Bo Andersen"},"description":"I am a back-end web developer with a passion for open source technologies. I have been a PHP developer for many years, and also have experience with Java and Spring Framework. I currently work full time as a lead developer. Apart from that, I also spend time on making online courses, so be sure to check those out!","sameAs":["https:\/\/codingexplained.com","https:\/\/www.facebook.com\/codingexplained","https:\/\/www.linkedin.com\/in\/ba0708","https:\/\/twitter.com\/codingexplained","https:\/\/www.youtube.com\/c\/codingexplained"],"url":"https:\/\/codingexplained.com\/author\/andy"}]}},"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p3mJkW-by","_links":{"self":[{"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/posts\/716"}],"collection":[{"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/comments?post=716"}],"version-history":[{"count":16,"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/posts\/716\/revisions"}],"predecessor-version":[{"id":3030,"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/posts\/716\/revisions\/3030"}],"wp:attachment":[{"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/media?parent=716"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/categories?post=716"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/tags?post=716"},{"taxonomy":"series","embeddable":true,"href":"https:\/\/codingexplained.com\/wp-json\/wp\/v2\/series?post=716"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}