int extract ( array source [, int extract_type [, string prefix]])
Extract() is a very popular function that converts elements in an array into variables in their own right. Extract takes a minimum of one parameter, an array, and returns the number of elements extracted. This is best explained using code, so here goes:
After calling extract, the "England", "Scotland", and "Wales" keys become variables in their own right ($England, $Scotland, and $Wales), with their values set to "London", "Edinburgh", and "Cardiff" respectively. By default, extract() will overwrite any existing variables, meaning that $Wales's original value of "Swansea" will be overwritten with "Cardiff".
This behaviour can be altered using the second parameter, and averted using the third parameter. Parameter two takes a special constant value that allows you to decide how values will be treated if there is an existing variable, and parameter three allows you to prefix each extract variable with a special string. Here are the possible values of the second parameter:
On collision, overwrite the existing variable
On collision, do not overwrite the existing variable
On collision, prefix the variable name with the prefix specified by parameter three
Prefix all variables with the prefix specified by parameter three, whether or not there is a collision
Only use the prefix specified by parameter three when variables names would otherwise be illegal (e.g. "$9")
Only set variables if they already exist
Only create prefixed variables if non-prefixed version already exists
Extract variables as references
The last option, EXTR_REFS, can either be used on its own or in combination with others using the bitwise OR operator |.
Here are some examples based upon the $capitalcities array from the previous example:
On line one we pre-set $Wales to be a value so that you can clearly see how the second parameter works. On line two we call extract() using two parameters, with EXTR_SKIP as parameter two so that our $Wales will not be overwritten. However, as you will be able to see if you run the script, $England and $Scotland were set.
On line five we use EXTR_PREFIX_SAME, which will extract variables and use the third parameter as a prefix if it finds any collisions. As we set $Wales ourselves and our previous call to extract() created $England and $Scotland, all our variables will need to be prefixed. As you can see on line six, $Wales is still set to "Swansea", and on line seven we have our prefixed variable $country_England. Note that PHP places an underscore _ after your prefix to make the variable easy to read.
Finally we call extract() with EXTR_PREFIX_ALL, which will unconditionally create variables with prefixes, overwriting $country_England, etc. Note that EXTR_OVERWRITE is rarely if ever used, because it is the same as using extract() without second or third parameters.