reference/info/functions/assert.xml
2916fa4160bdf53bb316a5c7c018fc91df7cd951
...
...
@@ -14,13 +14,13 @@
14
14
<methodparam choice="opt"><type class="union"><type>Throwable</type><type>string</type><type>null</type></type><parameter>description</parameter><initializer>&null;</initializer></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
-
<function>assert</function> is not a function but a language construct.
18
-
allowing for the definition of expectations: assertions that take effect
17
+
<function>assert</function>
18
+
allows for the definition of expectations: assertions that take effect
19
19
in development and testing environments, but are optimised away to have
20
20
zero cost in production.
21
21
</para>
22
22
<para>
23
-
Assertions should be used as a debugging feature only.
23
+
Assertions can be used to aid debugging.
24
24
One use case for them is to act as sanity-checks for preconditions
25
25
that should always be &true; and that if they aren't upheld this indicates
26
26
some programming errors.
...
...
@@ -81,31 +81,40 @@
81
81
If &false;, <function>assert</function> does not check the expectation
82
82
and returns &true;, unconditionally.
83
83
</entry>
84
-
<entry/>
84
+
<entry>
85
+
Deprecated as of PHP 8.3.0.
86
+
</entry>
85
87
</row>
86
88
<row>
87
89
<entry><link linkend="ini.assert.callback">assert.callback</link></entry>
88
90
<entry>&null;</entry>
89
91
<entry>
90
-
A user defined function to call when an assertion fails.
91
-
It's signature should be:
92
-
<methodsynopsis role="procedural">
93
-
<type>void</type><methodname>assert_callback</methodname>
94
-
<methodparam><type>string</type><parameter>file</parameter></methodparam>
95
-
<methodparam><type>int</type><parameter>line</parameter></methodparam>
96
-
<methodparam><type>null</type><parameter>assertion</parameter></methodparam>
97
-
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
98
-
</methodsynopsis>
92
+
<para>
93
+
A user defined function to call when an assertion fails.
94
+
Its signature should be:
95
+
<methodsynopsis role="procedural">
96
+
<type>void</type><methodname>assert_callback</methodname>
97
+
<methodparam><type>string</type><parameter>file</parameter></methodparam>
98
+
<methodparam><type>int</type><parameter>line</parameter></methodparam>
99
+
<methodparam><type>null</type><parameter>assertion</parameter></methodparam>
100
+
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
101
+
</methodsynopsis>
102
+
</para>
99
103
</entry>
100
104
<entry>
101
-
Prior to PHP 8.0.0, the signature of the callback should be:
102
-
<methodsynopsis role="procedural">
103
-
<type>void</type><methodname>assert_callback</methodname>
104
-
<methodparam><type>string</type><parameter>file</parameter></methodparam>
105
-
<methodparam><type>int</type><parameter>line</parameter></methodparam>
106
-
<methodparam><type>string</type><parameter>assertion</parameter></methodparam>
107
-
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
108
-
</methodsynopsis>
105
+
<para>
106
+
Prior to PHP 8.0.0, the signature of the callback should be:
107
+
<methodsynopsis role="procedural">
108
+
<type>void</type><methodname>assert_callback</methodname>
109
+
<methodparam><type>string</type><parameter>file</parameter></methodparam>
110
+
<methodparam><type>int</type><parameter>line</parameter></methodparam>
111
+
<methodparam><type>string</type><parameter>assertion</parameter></methodparam>
112
+
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
113
+
</methodsynopsis>
114
+
</para>
115
+
<simpara>
116
+
Deprecated as of PHP 8.3.0.
117
+
</simpara>
109
118
</entry>
110
119
</row>
111
120
<row>
...
...
@@ -115,7 +124,9 @@
115
124
If &true; will throw an <classname>AssertionError</classname> if the
116
125
expectation isn't upheld.
117
126
</entry>
118
-
<entry/>
127
+
<entry>
128
+
Deprecated as of PHP 8.3.0.
129
+
</entry>
119
130
</row>
120
131
<row>
121
132
<entry><link linkend="ini.assert.bail">assert.bail</link></entry>
...
...
@@ -124,7 +135,9 @@
124
135
If &true; will abort execution of the PHP script if the
125
136
expectation isn't upheld.
126
137
</entry>
127
-
<entry/>
138
+
<entry>
139
+
Deprecated as of PHP 8.3.0.
140
+
</entry>
128
141
</row>
129
142
<row>
130
143
<entry><link linkend="ini.assert.warning">assert.warning</link></entry>
...
...
@@ -135,14 +148,13 @@
135
148
<link linkend="ini.assert.exception">assert.exception</link>
136
149
is enabled.
137
150
</entry>
138
-
<entry/>
151
+
<entry>
152
+
Deprecated as of PHP 8.3.0.
153
+
</entry>
139
154
</row>
140
155
</tbody>
141
156
</tgroup>
142
157
</table>
143
-

144
-
The options starting with <literal>assert.</literal> can be configured via
145
-
<function>assert_options</function>. However, this is not recommended.
146
158
</para>
147
159
</refsect1>
148
160

...
...
@@ -218,7 +230,19 @@
218
230
<refsect1 role="returnvalues">
219
231
&reftitle.returnvalues;
220
232
<para>
221
-
&false; if the assertion is false, &true; otherwise.
233
+
<function>assert</function> will always return &true; if at least one of the following is true:
234
+
</para>
235
+
<simplelist>
236
+
<member><literal>zend.assertions=0</literal></member>
237
+
<member><literal>zend.assertions=-1</literal></member>
238
+
<member><literal>assert.active=0</literal></member>
239
+
<member><literal>assert.exception=1</literal></member>
240
+
<member><literal>assert.bail=1</literal></member>
241
+
<member>A custom exception object is passed to <parameter>description</parameter>.</member>
242
+
</simplelist>
243
+
<para>
244
+
If none of the conditions are true <function>assert</function> will return &true; if
245
+
<parameter>assertion</parameter> is truthy and &false; otherwise.
222
246
</para>
223
247
</refsect1>
224
248

...
...
@@ -234,6 +258,12 @@
234
258
</row>
235
259
</thead>
236
260
<tbody>
261
+
<row>
262
+
<entry>8.3.0</entry>
263
+
<entry>
264
+
All <literal>assert.</literal> INI settings have been deprecated.
265
+
</entry>
266
+
</row>
237
267
<row>
238
268
<entry>8.0.0</entry>
239
269
<entry>
...
...
@@ -293,209 +323,99 @@
293
323

294
324
<refsect1 role="examples">
295
325
&reftitle.examples;
296
-
<refsect2>
297
-
<title>Expectations</title>
298
326
<example>
327
+
<title><function>assert</function> example</title>
299
328
<programlisting role="php">
300
329
<![CDATA[
301
330
<?php
302
-
assert(true == false);
331
+
assert(1 > 2);
303
332
echo 'Hi!';
304
-
?>
305
333
]]>
306
334
</programlisting>
307
335
<para>
308
-
With <link linkend="ini.zend.assertions">zend.assertions</link> set to 0,
336
+
If assertions are enabled (<link linkend="ini.zend.assertions"><literal>zend.assertions=1</literal></link>)
309
337
the above example will output:
310
338
</para>
311
339
<screen>
312
340
<![CDATA[
313
-
Hi!
341
+
Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
342
+
Stack trace:
343
+
#0 example.php(2): assert(false, 'assert(1 > 2)')
344
+
#1 {main}
345
+
thrown in example.php on line 2
314
346
]]>
315
347
</screen>
316
348
<para>
317
-
With <link linkend="ini.zend.assertions">zend.assertions</link> set to 1
318
-
and <link linkend="ini.assert.exception">assert.exception</link> set to 0,
349
+
If assertions are disabled (<literal>zend.assertions=0</literal> or <literal>zend.assertions=-1</literal>)
319
350
the above example will output:
320
351
</para>
321
352
<screen>
322
353
<![CDATA[
323
-
Warning: assert(): assert(true == false) failed in - on line 2
324
354
Hi!
325
-
]]>
326
-
</screen>
327
-
<para>
328
-
With <link linkend="ini.zend.assertions">zend.assertions</link> set to 1
329
-
and <link linkend="ini.assert.exception">assert.exception</link> set to 1,
330
-
the above example will output:
331
-
</para>
332
-
<screen>
333
-
<![CDATA[
334
-
Fatal error: Uncaught AssertionError: assert(true == false) in -:2
335
-
Stack trace:
336
-
#0 -(2): assert(false, 'assert(true == ...')
337
-
#1 {main}
338
-
thrown in - on line 2
339
355
]]>
340
356
</screen>
341
357
</example>
342
358
<example>
343
-
<title>Expectations with a custom exception</title>
359
+
<title>Using a custom message</title>
344
360
<programlisting role="php">
345
361
<![CDATA[
346
362
<?php
347
-
class CustomError extends AssertionError {}
348
-

349
-
assert(true == false, new CustomError('True is not false!'));
363
+
assert(1 > 2, "Expected one to be greater than two");
350
364
echo 'Hi!';
351
-
?>
352
365
]]>
353
366
</programlisting>
354
367
<para>
355
-
With <link linkend="ini.zend.assertions">zend.assertions</link> set to 0,
356
-
the above example will output:
368
+
If assertions are enabled the above example will output:
357
369
</para>
358
370
<screen>
359
371
<![CDATA[
360
-
Hi!
372
+
Fatal error: Uncaught AssertionError: Expected one to be greater than two in example.php:2
373
+
Stack trace:
374
+
#0 example.php(2): assert(false, 'Expected one to...')
375
+
#1 {main}
376
+
thrown in example.php on line 2
361
377
]]>
362
378
</screen>
363
379
<para>
364
-
With <link linkend="ini.zend.assertions">zend.assertions</link> set to 1
365
-
and <link linkend="ini.assert.exception">assert.exception</link> set to 0,
366
-
the above example will output:
380
+
If assertions are disabled the above example will output:
367
381
</para>
368
382
<screen>
369
383
<![CDATA[
370
-
Warning: assert(): CustomError: True is not false! in -:4
371
-
Stack trace:
372
-
#0 {main} failed in - on line 4
373
384
Hi!
374
385
]]>
375
386
</screen>
387
+
</example>
388
+
<example>
389
+
<title>Using a custom exception class</title>
390
+
<programlisting role="php">
391
+
<![CDATA[
392
+
<?php
393
+
class ArithmeticAssertionError extends AssertionError {}
394
+

395
+
assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
396
+
echo 'Hi!';
397
+
]]>
398
+
</programlisting>
376
399
<para>
377
-
With <link linkend="ini.zend.assertions">zend.assertions</link> set to 1
378
-
and <link linkend="ini.assert.exception">assert.exception</link> set to 1,
379
-
the above example will output:
400
+
If assertions are enabled the above example will output:
380
401
</para>
381
402
<screen>
382
403
<![CDATA[
383
-
Fatal error: Uncaught CustomError: True is not false! in -:4
404
+
Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4
384
405
Stack trace:
385
406
#0 {main}
386
-
thrown in - on line 4
407
+
thrown in example.php on line 4
387
408
]]>
388
409
</screen>
389
-
</example>
390
-
</refsect2>
391
-
<refsect2>
392
-
<title>Evaluated code assertions (PHP 7 only)</title>
393
-

394
-
<para>
395
-
With evaluated code assertions, <function>assert</function> callbacks
396
-
can be particularly useful as the code used for the assertion is passed
397
-
to the callback alongside information on where the assertion was done.
398
-
</para>
399
-
<para>
400
-
<example>
401
-
<title>Handle a failed assertion with a custom handler</title>
402
-
<programlisting role="php">
403
-
<![CDATA[
404
-
<?php
405
-
// Activate assert and make it quiet
406
-
assert_options(ASSERT_ACTIVE, 1);
407
-
assert_options(ASSERT_WARNING, 0);
408
-
assert_options(ASSERT_QUIET_EVAL, 1);
409
-

410
-
// Create a handler function
411
-
function my_assert_handler($file, $line, $code)
412
-
{
413
-
echo "<hr>Assertion Failed:
414
-
File '$file'<br />
415
-
Line '$line'<br />
416
-
Code '$code'<br /><hr />";
417
-
}
418
-

419
-
// Set up the callback
420
-
assert_options(ASSERT_CALLBACK, 'my_assert_handler');
421
-

422
-
// Make an assertion that should fail
423
-
$array = [];
424
-
assert('count($array);');
425
-
?>
426
-
]]>
427
-
</programlisting>
428
-
&example.outputs.72;
429
-
<screen>
430
-
<![CDATA[
431
-
Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 21
432
-
<hr>Assertion Failed:
433
-
File 'test.php'<br />
434
-
Line '21'<br />
435
-
Code 'count($array);'<br /><hr />
436
-
]]>
437
-
</screen>
438
-
&example.outputs.71;
439
-
<screen>
440
-
<![CDATA[
441
-
<hr>Assertion Failed:
442
-
File 'test.php'<br />
443
-
Line '21'<br />
444
-
Code 'count($array);'<br /><hr />
445
-
]]>
446
-
</screen>
447
-
</example>
448
-
</para>
449
-
<para>
450
-
<example>
451
-
<title>Using a custom handler to print a description</title>
452
-
<programlisting role="php">
453
-
<![CDATA[
454
-
<?php
455
-
// Activate assert and make it quiet
456
-
assert_options(ASSERT_ACTIVE, 1);
457
-
assert_options(ASSERT_WARNING, 0);
458
-
assert_options(ASSERT_QUIET_EVAL, 1);
459
-

460
-
// Create a handler function
461
-
function my_assert_handler($file, $line, $code, $desc = null)
462
-
{
463
-
echo "Assertion failed at $file:$line: $code";
464
-
if ($desc) {
465
-
echo ": $desc";
466
-
}
467
-
echo "\n";
468
-
}
469
-

470
-
// Set up the callback
471
-
assert_options(ASSERT_CALLBACK, 'my_assert_handler');
472
-

473
-
// Make an assertion that should fail
474
-
assert('2 < 1');
475
-
assert('2 < 1', 'Two is less than one');
476
-
?>
477
-
]]>
478
-
</programlisting>
479
-
&example.outputs.72;
480
-
<screen>
410
+
<para>
411
+
If assertions are disabled the above example will output:
412
+
</para>
413
+
<screen>
481
414
<![CDATA[
482
-
Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 21
483
-
Assertion failed at test.php:21: 2 < 1
484
-

485
-
Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 22
486
-
Assertion failed at test.php:22: 2 < 1: Two is less than one
415
+
Hi!
487
416
]]>
488
-
</screen>
489
-
&example.outputs.71;
490
-
<screen>
491
-
<![CDATA[
492
-
Assertion failed at test.php:21: 2 < 1
493
-
Assertion failed at test.php:22: 2 < 1: Two is less than one
494
-
]]>
495
-
</screen>
496
-
</example>
497
-
</para>
498
-
</refsect2>
417
+
</screen>
418
+
</example>
499
419
</refsect1>
500
420

501
421
<refsect1 role="seealso">
502
422



Translation status