reference/info/functions/getenv.xml
1299a9808782769bba9f6a48bf52cb1c68182e78
...
...
@@ -3,17 +3,18 @@
3
3
<refentry xml:id="function.getenv" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>getenv</refname>
6
-
<refpurpose>Gets the value of an environment variable</refpurpose>
6
+
<refpurpose>Gets the value of a single or all environment variables</refpurpose>
7
7
</refnamediv>
8
8

9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>string</type><methodname>getenv</methodname>
13
-
<methodparam><type>string</type><parameter>varname</parameter></methodparam>
12
+
<type class="union"><type>string</type><type>array</type><type>false</type></type><methodname>getenv</methodname>
13
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>name</parameter><initializer>&null;</initializer></methodparam>
14
+
<methodparam choice="opt"><type>bool</type><parameter>local_only</parameter><initializer>&false;</initializer></methodparam>
14
15
</methodsynopsis>
15
16
<para>
16
-
Gets the value of an environment variable.
17
+
Gets the value of a single or all environment variables.
17
18
</para>
18
19
<para>
19
20
You can see a list of all the environmental variables by using
...
...
@@ -28,10 +29,19 @@
28
29
<para>
29
30
<variablelist>
30
31
<varlistentry>
31
-
<term><parameter>varname</parameter></term>
32
+
<term><parameter>name</parameter></term>
32
33
<listitem>
33
34
<para>
34
-
The variable name.
35
+
The variable name as a &string; or &null;.
36
+
</para>
37
+
</listitem>
38
+
</varlistentry>
39
+
<varlistentry>
40
+
<term><parameter>local_only</parameter></term>
41
+
<listitem>
42
+
<para>
43
+
When set to &true;, only local environment variables are returned, set by the operating system or putenv. It only has
44
+
an effect when <parameter>name</parameter> is a &string;.
35
45
</para>
36
46
</listitem>
37
47
</varlistentry>
...
...
@@ -43,11 +53,48 @@
43
53
&reftitle.returnvalues;
44
54
<para>
45
55
Returns the value of the environment variable
46
-
<parameter>varname</parameter>, or &false; if the environment
47
-
variable <parameter>varname</parameter> does not exist.
56
+
<parameter>name</parameter>, or &false; if the environment
57
+
variable <parameter>name</parameter> does not exist.
58
+
If <parameter>name</parameter> is &null;, all environment variables are
59
+
returned as an associative <type>array</type>.
48
60
</para>
49
61
</refsect1>
50
62

63
+
<refsect1 role="changelog">
64
+
&reftitle.changelog;
65
+
<informaltable>
66
+
<tgroup cols="2">
67
+
<thead>
68
+
<row>
69
+
<entry>&Version;</entry>
70
+
<entry>&Description;</entry>
71
+
</row>
72
+
</thead>
73
+
<tbody>
74
+
<row>
75
+
<entry>8.0.0</entry>
76
+
<entry>
77
+
The <parameter>name</parameter> is now nullable.
78
+
</entry>
79
+
</row>
80
+
<row>
81
+
<entry>7.1.0</entry>
82
+
<entry>
83
+
The <parameter>name</parameter> can now be omitted to retrieve an
84
+
associative <type>array</type> of all environment variables.
85
+
</entry>
86
+
</row>
87
+
<row>
88
+
<entry>7.0.9</entry>
89
+
<entry>
90
+
The <parameter>local_only</parameter> parameter has been added.
91
+
</entry>
92
+
</row>
93
+
</tbody>
94
+
</tgroup>
95
+
</informaltable>
96
+
</refsect1>
97
+

51
98
<refsect1 role="examples">
52
99
&reftitle.examples;
53
100
<para>
...
...
@@ -61,6 +108,10 @@ $ip = getenv('REMOTE_ADDR');
61
108

62
109
// Or simply use a Superglobal ($_SERVER or $_ENV)
63
110
$ip = $_SERVER['REMOTE_ADDR'];
111
+

112
+
// Safely get the value of an environment variable, ignoring whether
113
+
// or not it was set by a SAPI or has been changed with putenv
114
+
$ip = getenv('REMOTE_ADDR', true) ?: getenv('REMOTE_ADDR')
64
115
?>
65
116
]]>
66
117
</programlisting>
...
...
@@ -68,6 +119,19 @@ $ip = $_SERVER['REMOTE_ADDR'];
68
119
</para>
69
120
</refsect1>
70
121

122
+
<refsect1 role="notes">
123
+
&reftitle.notes;
124
+
<warning>
125
+
<para>
126
+
If PHP is running in a SAPI such as Fast CGI, this function will
127
+
always return the value of an environment variable set by the SAPI,
128
+
even if <function>putenv</function> has been used to set a local
129
+
environment variable of the same name. Use the <parameter>local_only</parameter>
130
+
parameter to return the value of locally-set environment variables.
131
+
</para>
132
+
</warning>
133
+
</refsect1>
134
+

71
135
<refsect1 role="seealso">
72
136
&reftitle.seealso;
73
137
<para>
...
...
@@ -80,7 +144,6 @@ $ip = $_SERVER['REMOTE_ADDR'];
80
144
</refsect1>
81
145

82
146
</refentry>
83
-

84
147
<!-- Keep this comment at the end of the file
85
148
Local variables:
86
149
mode: sgml
87
150