reference/info/functions/assert.xml
27dcb487a7e9c0f04559522a6d2aacf860d622cd
...
...
@@ -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,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
+
It's 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,18 @@
218
230
<refsect1 role="returnvalues">
219
231
&reftitle.returnvalues;
220
232
<para>
221
-
&false; if <parameter>assertion</parameter> 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.exception=1</literal></member>
239
+
<member><literal>assert.bail=1</literal></member>
240
+
<member>A custom exception object is passed to <parameter>description</parameter>.</member>
241
+
</simplelist>
242
+
<para>
243
+
If none of the conditions are true <function>assert</function> will return &true; if
244
+
<parameter>assertion</parameter> is truthy and &false; otherwise.
222
245
</para>
223
246
</refsect1>
224
247

...
...
@@ -235,6 +258,12 @@
235
258
</thead>
236
259
<tbody>
237
260
<row>
261
+
<entry>8.3.0</entry>
262
+
<entry>
263
+
All <literal>assert.</literal> INI settings have been deprecated.
264
+
</entry>
265
+
</row>
266
+
<row>
238
267
<entry>8.0.0</entry>
239
268
<entry>
240
269
<function>assert</function> will no longer evaluate string arguments, instead they will be
...
...
@@ -293,209 +322,99 @@
293
322

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

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

394
+
assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
395
+
echo 'Hi!';
396
+
]]>
397
+
</programlisting>
376
398
<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:
399
+
If assertions are enabled the above example will output:
380
400
</para>
381
401
<screen>
382
402
<![CDATA[
383
-
Fatal error: Uncaught CustomError: True is not false! in -:4
403
+
Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4
384
404
Stack trace:
385
405
#0 {main}
386
-
thrown in - on line 4
406
+
thrown in example.php on line 4
387
407
]]>
388
408
</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>
481
-
<![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
487
-
]]>
488
-
</screen>
489
-
&example.outputs.71;
490
-
<screen>
409
+
<para>
410
+
If assertions are disabled the above example will output:
411
+
</para>
412
+
<screen>
491
413
<![CDATA[
492
-
Assertion failed at test.php:21: 2 < 1
493
-
Assertion failed at test.php:22: 2 < 1: Two is less than one
414
+
Hi!
494
415
]]>
495
-
</screen>
496
-
</example>
497
-
</para>
498
-
</refsect2>
416
+
</screen>
417
+
</example>
499
418
</refsect1>
500
419

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



Tools (Turkish Manual)