Skip to content

Commit 09030e8

Browse files
authored
Merge pull request #6593 from kenjis/fix-docs-session
docs: improve session
2 parents dbb3426 + 30705d6 commit 09030e8

File tree

1 file changed

+25
-20
lines changed

1 file changed

+25
-20
lines changed

user_guide_src/source/libraries/sessions.rst

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ However, non-blocking requests in the context of sessions also means
7575
unsafe, because, modifications to session data (or session ID regeneration)
7676
in one request can interfere with the execution of a second, concurrent
7777
request. This detail was at the root of many issues and the main reason why
78-
CodeIgniter 4 has a completely re-written Session library.
78+
CodeIgniter 3 has a completely re-written Session library.
7979

8080
Why are we telling you this? Because it is likely that after trying to
8181
find the reason for your performance issues, you may conclude that locking
@@ -106,8 +106,13 @@ uses the session handlers' mechanism provided by PHP. Using session data is
106106
as simple as manipulating (read, set and unset values) the ``$_SESSION``
107107
array.
108108

109+
.. note:: In general, it is bad practice to use global variables.
110+
So using the superglobal ``$_SESSION`` directly is not recommended.
111+
109112
In addition, CodeIgniter also provides 2 special types of session data
110-
that are further explained below: flashdata and tempdata.
113+
that are further explained below: `Flashdata`_ and `Tempdata`_.
114+
115+
.. note:: For historical reasons, we refer to session data excluding Flashdata and Tempdata as "userdata".
111116

112117
Retrieving Session Data
113118
=======================
@@ -130,22 +135,22 @@ Or even through the session helper method:
130135
.. literalinclude:: sessions/007.php
131136

132137
Where ``item`` is the array key corresponding to the item you wish to fetch.
133-
For example, to assign a previously stored 'name' item to the ``$name``
138+
For example, to assign a previously stored ``name`` item to the ``$name``
134139
variable, you will do this:
135140

136141
.. literalinclude:: sessions/008.php
137142

138143
.. note:: The ``get()`` method returns null if the item you are trying
139144
to access does not exist.
140145

141-
If you want to retrieve all of the existing userdata, you can simply
146+
If you want to retrieve all of the existing session data, you can simply
142147
omit the item key (magic getter only works for single property values):
143148

144149
.. literalinclude:: sessions/009.php
145150

146151
.. important:: The ``get()`` method WILL return flashdata or tempdata items when
147152
retrieving a single item by key. It will not return flashdata or tempdata when
148-
grabbing all userdata from the session, however.
153+
grabbing all data from the session, however.
149154

150155
Adding Session Data
151156
===================
@@ -158,8 +163,7 @@ you need it.
158163
You can simply assign data to the ``$_SESSION`` array, as with any other
159164
variable. Or as a property of ``$session``.
160165

161-
The former userdata method is deprecated,
162-
but you can pass an array containing your new session data to the
166+
You can pass an array containing your new session data to the
163167
``set()`` method:
164168

165169
.. literalinclude:: sessions/010.php
@@ -183,11 +187,11 @@ Or you can call ``has()``:
183187

184188
.. literalinclude:: sessions/014.php
185189

186-
Pushing new value to session data
190+
Pushing New Value to Session Data
187191
=================================
188192

189-
The push method is used to push a new value onto a session value that is an array.
190-
For instance, if the 'hobbies' key contains an array of hobbies, you can add a new value onto the array like so:
193+
The ``push()`` method is used to push a new value onto a session value that is an array.
194+
For instance, if the ``hobbies`` key contains an array of hobbies, you can add a new value onto the array like so:
191195

192196
.. literalinclude:: sessions/015.php
193197

@@ -201,7 +205,7 @@ done through ``unset()``:
201205

202206
Also, just as ``set()`` can be used to add information to a
203207
session, ``remove()`` can be used to remove it, by passing the
204-
session key. For example, if you wanted to remove 'some_name' from your
208+
session key. For example, if you wanted to remove ``some_name`` from your
205209
session data array:
206210

207211
.. literalinclude:: sessions/017.php
@@ -249,19 +253,20 @@ through ``$_SESSION``:
249253

250254
.. important:: The ``get()`` method WILL return flashdata items when
251255
retrieving a single item by key. It will not return flashdata when
252-
grabbing all userdata from the session, however.
256+
grabbing all data from the session, however.
253257

254258
However, if you want to be sure that you're reading "flashdata" (and not
255259
any other kind), you can also use the ``getFlashdata()`` method:
256260

257261
.. literalinclude:: sessions/024.php
258262

263+
.. note:: The ``getFlashdata()`` method returns null if the item cannot be
264+
found.
265+
259266
Or to get an array with all flashdata, simply omit the key parameter:
260267

261268
.. literalinclude:: sessions/025.php
262269

263-
.. note:: The ``getFlashdata()`` method returns null if the item cannot be
264-
found.
265270

266271
If you find that you need to preserve a flashdata variable through an
267272
additional request, you can do so using the ``keepFlashdata()`` method.
@@ -311,20 +316,20 @@ To read a tempdata variable, again you can just access it through the
311316

312317
.. important:: The ``get()`` method WILL return tempdata items when
313318
retrieving a single item by key. It will not return tempdata when
314-
grabbing all userdata from the session, however.
319+
grabbing all data from the session, however.
315320

316321
Or if you want to be sure that you're reading "tempdata" (and not any
317322
other kind), you can also use the ``getTempdata()`` method:
318323

319324
.. literalinclude:: sessions/033.php
320325

326+
.. note:: The ``getTempdata()`` method returns null if the item cannot be
327+
found.
328+
321329
And of course, if you want to retrieve all existing tempdata:
322330

323331
.. literalinclude:: sessions/034.php
324332

325-
.. note:: The ``getTempdata()`` method returns null if the item cannot be
326-
found.
327-
328333
If you need to remove a tempdata value before it expires, you can directly
329334
unset it from the ``$_SESSION`` array:
330335

@@ -358,10 +363,10 @@ the cookie that contained the session id:
358363

359364
.. literalinclude:: sessions/038.php
360365

361-
Accessing session metadata
366+
Accessing Session Metadata
362367
==========================
363368

364-
In previous CodeIgniter versions, the session data array included 4 items
369+
In CodeIgniter 2, the session data array included 4 items
365370
by default: 'session_id', 'ip_address', 'user_agent', 'last_activity'.
366371

367372
This was due to the specifics of how sessions worked, but is now no longer

0 commit comments

Comments
 (0)