reference/info/functions/assert.xml
b2cbcaea5b0e967d2b2cc6bbfa631343e49a7c28
...
...
@@ -14,8 +14,8 @@
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>
...
...
@@ -81,7 +81,9 @@
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>
...
...
@@ -106,6 +108,7 @@
106
108
<methodparam><type>string</type><parameter>assertion</parameter></methodparam>
107
109
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
108
110
</methodsynopsis>
111
+
Deprecated as of PHP 8.3.0.
109
112
</entry>
110
113
</row>
111
114
<row>
...
...
@@ -115,7 +118,9 @@
115
118
If &true; will throw an <classname>AssertionError</classname> if the
116
119
expectation isn't upheld.
117
120
</entry>
118
-
<entry/>
121
+
<entry>
122
+
Deprecated as of PHP 8.3.0.
123
+
</entry>
119
124
</row>
120
125
<row>
121
126
<entry><link linkend="ini.assert.bail">assert.bail</link></entry>
...
...
@@ -124,7 +129,9 @@
124
129
If &true; will abort execution of the PHP script if the
125
130
expectation isn't upheld.
126
131
</entry>
127
-
<entry/>
132
+
<entry>
133
+
Deprecated as of PHP 8.3.0.
134
+
</entry>
128
135
</row>
129
136
<row>
130
137
<entry><link linkend="ini.assert.warning">assert.warning</link></entry>
...
...
@@ -135,14 +142,13 @@
135
142
<link linkend="ini.assert.exception">assert.exception</link>
136
143
is enabled.
137
144
</entry>
138
-
<entry/>
145
+
<entry>
146
+
Deprecated as of PHP 8.3.0.
147
+
</entry>
139
148
</row>
140
149
</tbody>
141
150
</tgroup>
142
151
</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
152
</para>
147
153
</refsect1>
148
154

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

...
...
@@ -235,6 +252,12 @@
235
252
</thead>
236
253
<tbody>
237
254
<row>
255
+
<entry>8.3.0</entry>
256
+
<entry>
257
+
All <literal>assert.</literal> INI settings have been deprecated.
258
+
</entry>
259
+
</row>
260
+
<row>
238
261
<entry>8.0.0</entry>
239
262
<entry>
240
263
<function>assert</function> will no longer evaluate string arguments, instead they will be
...
...
@@ -293,209 +316,99 @@
293
316

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

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

388
+
assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
389
+
echo 'Hi!';
390
+
]]>
391
+
</programlisting>
376
392
<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:
393
+
If assertions are enabled the above example will output:
380
394
</para>
381
395
<screen>
382
396
<![CDATA[
383
-
Fatal error: Uncaught CustomError: True is not false! in -:4
397
+
Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4
384
398
Stack trace:
385
399
#0 {main}
386
-
thrown in - on line 4
400
+
thrown in example.php on line 4
387
401
]]>
388
402
</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>
403
+
<para>
404
+
If assertions are disabled the above example will output:
405
+
</para>
406
+
<screen>
481
407
<![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
408
+
Hi!
487
409
]]>
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>
410
+
</screen>
411
+
</example>
499
412
</refsect1>
500
413

501
414
<refsect1 role="seealso">
502
415