php-src Documentation

--EXPECT--
string(32) "# hello All, I sAid hi planet! #"

As you can see the file is divided into several sections. The TEST section holds a one line title of
the phpt test, this should be a simple description and shouldn't ever exceed one line, if you need
to write more explanation add comments in the body of the test case. The phpt files name is used
when generating a .php file. The FILE section is used as the body of the .php file, so don't forget
to open and close your php tags. The EXPECT section is the part used as a comparison to see if the
test passes. It is a good idea to generate output with var_dump() calls.

PHPT structure details

A phpt test can have many more parts than just the minimum. In fact some of the mandatory parts have
alternatives that may be used if the situation warrants it. The phpt sections are documented here.

Analyzing failing tests

While writing tests you will probably run into tests not passing while you think they should. The
'make test' command provides you with debug information. Several files will be added per test in the
same directory as the .phpt file itself. Considering your test file is named foo.phpt, these files
provide you with information that can help you find out what went wrong:

foo.diff

A diff file between the expected output (be it in EXPECT, EXPECTF or another option) and the
actual output.

foo.exp

The expected output.

foo.log

A log containing expected output, actual output and results. Most likely very similar to info in
the other files.

foo.out

The actual output of your .phpt test part.

foo.php

The php code that was executed for this test.

foo.sh

An executable file that executes the test for you as it was executed during failure.

Testing your test cases

Most people who write tests for PHP don't have access to a huge number of operating systems but the
tests are run on every system that runs PHP. It's good to test your test on as many platforms as you
can — Linux and Windows are the most important, it's increasingly important to make sure that tests
run on 64 bit as well as 32 bit platforms. If you only have access to one operating system — don't
worry, if you have karma, commit the test but watch [email protected] for reports of failures on
other platforms. If you don't have karma to commit have a look at the next section.

When you are testing your test case it's really important to make sure that you clean up any
temporary resources (eg files) that you used in the test. There is a special --CLEAN-- section
to help you do this — see here <#clean>_.

Tests run in parallel by default. Mutable resources such as files, directories, ports, database
objects, and IPC identifiers must therefore be unique to each test. Read-only fixtures may be
shared. If a resource cannot be isolated, declare the narrowest applicable conflict using
--CONFLICTS-- or a CONFLICTS file.

Another good check is to look at what lines of code in the PHP source your test case covers. This is
easy to do, there are some instructions on the PHP Wiki <https://wiki.php.net/doc/articles/writing-tests>_.

What should I do with my test case when I've written and tested it?

The next step is to get someone to review it. If it's short you can paste it into a note and send it
to [email protected]. If the test is a bit too long for that then put it somewhere were people
can download it (pastebin <https://pastebin.com/>_ is sometimes used). Appending tests to notes as
files doesn't work well - so please don't do that. Your note to [email protected] should say what
level of PHP you have tested it on and what platform(s) you've run it on. Someone from the PHP QA
group will review your test and reply to you. They may ask for some changes or suggest better ways
to do things, or they may commit it to PHP.

Writing Portable PHP Tests

Writing portable tests can be hard if you don't have access to all the many platforms that PHP can
run on. Do your best. If in doubt, don't disable a test. It is better that the test runs in as many
environments as possible.

If you know a new test won't run in a specific environment, try to write the complementary test for
that environment.

Make sure sets of data are consistently ordered. SQL queries are not guaranteed to return results in
the same order unless an ORDER BY clause is used. Directory listings are another example that can
vary: use an appropriate PHP function to sort them before printing. Both of these examples have
affected PHP tests in the past.

Make sure that any test touching parsing or display of dates uses a hard-defined timezone —
preferable 'UTC'. It is important that this is defined in the file section using:

.. code:: php

date_default_timezone_set('UTC');

and not in the INI section. This is because of the order in which settings are checked which is:

.. code::

date_default_timezone_set() -> TZ environmental -> INI setting -> System Setting

If a TZ environmental variable is found the INI setting will be ignored.

Tests that run, or only have matching EXPECT output, on 32bit platforms can use a SKIPIF section
like:

.. code:: php

--SKIPIF--

Tests for 64bit platforms can use:

.. code:: php

--SKIPIF--

To run a test only on Windows:

.. code:: php

--SKIPIF--

To run a test only on Linux:

.. code:: php

--SKIPIF--

To skip a test on Mac OS X Darwin:

.. code:: php

--SKIPIF--

Examples

EXPECTF

/ext/standard/tests/strings/str_shuffle.phpt is a good example for using EXPECTF instead of
EXPECT. From time to time the algorithm used for shuffle changed and sometimes the machine used
to execute the code has influence on the result of shuffle. But it always returns a three character
string detectable by %s (that matches any string until the end of the line). Other scan-able
forms are %a for any amount of chars (at least one), %i for integers, %d for numbers
only, %f for floating point values, %c for single characters, %x for hexadecimal values,
%w for any number of whitespace characters and %e for DIRECTORY_SEPARATOR ('\' or
'/').

See also EXPECTF <#expectf>_ details.

/ext/standard/tests/strings/str_shuffle.phpt

.. code:: php

--TEST--
Testing str_shuffle.
--FILE--

--EXPECTF--
string(3) "%s"
string(3) "123"

EXPECTREGEX

/ext/standard/tests/strings/strings001.phpt is a good example for using EXPECTREGEX instead
of EXPECT. This test also shows that in EXPECTREGEX some characters need to be escaped since
otherwise they would be interpreted as a regular expression.

/ext/standard/tests/strings/strings001.phpt

.. code:: php

--TEST--
Test whether strstr() and strrchr() are binary safe.
--FILE--

--EXPECTREGEX--
string(18) "nica\x00turska panica"
string(19) " nica\x00turska panica"

EXTENSIONS

Some tests depend on PHP extensions that may be unavailable. These extensions should be listed in
the EXTENSIONS section. If an extension is missing, PHP will try to find it in a shared module
and skip the test if it's not there.

/ext/sodium/tests/crypto_scalarmult.phpt

.. code:: php

--TEST--
Check for libsodium scalarmult
--EXTENSIONS--
sodium
--FILE--
<?php
$n = sodium_hex2bin("5dab087e624a8a4b79e17f8b83800ee66f3bb1292618b6fd1c2f8b27ff88e0eb");

SKIPIF

Some tests depend on modules or functions available only in certain versions or they even require
minimum version of php or zend. These tests should be skipped when the requirement cannot be
fulfilled. To achieve this you can use the SKIPIF section. To tell run-tests.php that your
test should be skipped the SKIPIF section must print out the word "skip" followed by a reason
why the test should skip.

ext/sodium/tests/pwhash_argon2i.phpt

.. code:: php

--TEST--
Check for libsodium argon2i
--EXTENSIONS--
sodium
--SKIPIF--

--FILE--
[snip]

Test script and SKIPIF code should be directly written into \*.phpt. However, it is
recommended to use include files when more test scripts depend on the same SKIPIF code or when
certain test files need the same values for some input.

Note: no file used by any test should have one of the following extensions: ".php", ".log", ".mem",
".exp", ".out" or ".diff". When you use an include file for the SKIPIF section it should be
named "skipif.inc" and an include file used in the FILE section of many tests should be named
"test.inc".

Final Notes

Cleaning up after running a test

Sometimes test cases create files or directories as part of the test case and it's important to
remove these after the test ends, the --CLEAN-- section is provided to help with this.

The PHP code in the --CLEAN-- section is executed separately from the code in the --FILE--
section. For example, this code:

.. code:: php

--TEST--
Will fail to clean up
--FILE--

--CLEAN--

--EXPECT--

will not remove the temporary file because the variable $temp_filename is not defined in the
--CLEAN-- section.

Here is a better way to write the code:

.. code:: php

--TEST--
This will remove temporary files
--FILE--

--CLEAN--

--EXPECT--

Note the use of the __DIR__ construct which will ensure that the temporary file is created in
the same directory as the phpt test script.

When creating temporary files it is a good idea to use an extension that indicates the use of the
file, eg .tmp. It's also a good idea to avoid using extensions that are already used for other
purposes, eg .inc, .php. Similarly, it is helpful to give the temporary file a name that is clearly
related to the test case. For example, mytest.phpt should create mytest.tmp (or mytestN.tmp, N=1,
2,3,...) then if by any chance the temporary file isnt't removed properly it will be obvious which
test case created it.

When writing and debugging a test case with a --CLEAN-- section it is helpful to remember that
the php code in the --CLEAN-- section is executed separately from the code in the --FILE--
section. For example, in a test case called mytest.phpt, code from the --FILE-- section is run
from a file called mytest.php and code from the --CLEAN-- section is run from a file called
mytest.clean.php. If the test passes, both the .php and .clean.php files are removed by
run-tests.php. You can prevent the removal by using the --keep option of run-tests.php, this
is a very useful option if you need to check that the --CLEAN-- section code is working as you
intended.

Finally — if you are using CVS it's helpful to add the extension that you use for test-related
temporary files to the .cvsignore file — this will help to prevent you from accidentally checking
temporary files into CVS.

Redirecting tests

Using --REDIRECTTEST-- it is possible to redirect from one test to a bunch of other tests. That
way multiple extensions can refer to the same set of test scripts probably using it with a different
configuration.

The block is eval'd and supposed to return an array describing how to redirect. The resulting array
must contain the key 'TEST' that stores the redirect target as a string. This string usually is the
directory where the test scripts are located and should be relative. Optionally you can use the
'ENV' as an array configuring the environment to be set when executing the tests. This way you can
pass configuration to the executed tests.

Redirect tests may especially contain --SKIPIF--, --ENV--, and --ARGS-- sections but
they no not use any --EXPECT-- section.

The redirected tests themselves are just normal tests.

Error reporting in tests

All tests should run correctly with error_reporting(E_ALL) and display_errors=1. This is the default
when called from run-tests.php. If you have a good reason for lowering the error reporting, use
--INI-- section and comment this in your testcode.

If your test intentionally generates a PHP warning message use $php_errormsg variable, which you can
then output. This will result in a consistent error message output across all platforms and PHP
configurations, preventing your test from failing due inconsistencies in the error message content.
Alternatively you can use --EXPECTF-- and check for the message by replacing the path of the
source of the message with %s and the line number with %d. The end of a message in a test
file example.phpt then looks like in %sexample.php on line %d. We explicitly dropped the
last path divider as that is a system dependent character / or \.

Last bit

Often you want to run test scripts without run-tests.php by executing them on command line like
any other php script. But sometimes it disturbs having a long --EXPECT-- block, so that you
don't see the actual output as it scrolls away overwritten by the blocks following the actual file
block. The workaround is to use terminate the --FILE-- section with the two lines ===DONE===
and <?php exit(0); ?>. When doing so run-tests.php does not execute the line containing the
exit call as that would suppress leak messages. Actually run-tests.php ignores any part after a
line consisting only of ===DONE===.

Here is an example:

.. code:: php

--TEST--
Test hypot() — dealing with mixed number/character input
--INI--
precision=14
--FILE--

===DONE===

--EXPECTF--
23abc :-33 float(40.224370722238)
===DONE===

If executed as PHP script the output will stop after the code on the --FILE-- section has been
run.

Reference

PHPT Sections

``--TEST--`` Copy Chapter

Description: Title of test as a single line short description.

Required: Yes

Format: Plain text. We recommend a single line only.

Example 1 (snippet):

.. code:: text

--TEST--
Test filter_input() with GET and POST data.

Example 1 (full): :ref:sample001.phpt

``--DESCRIPTION--`` Copy Chapter

Description: If your test requires more than a single line title to adequately describe it, you
can use this section for further explanation. Multiple lines are allowed and besides being used for
information, this section is completely ignored by the test binary.

Required: No

Format: Plain text, multiple lines.

Example 1 (snippet):

.. code:: text

--DESCRIPTION--
This test covers both valid and invalid usages of filter_input() with INPUT_GET and INPUT_POST data and several different filter sanitizers.

Example 1 (full): :ref:sample001.phpt

``--CREDITS--`` Copy Chapter

Description: Used to credit contributors without CVS commit rights, who put their name and email
on the first line. If the test was part of a TestFest event, then # followed by the name of the
event and the date (YYYY-MM-DD) on the second line.

Required: No. For newly created tests the section should no longer be used for simple authorship
claims or listing all contributors who edited the test; as it is already accurately tracked by Git.
It may be used if more specific attribution is useful, for example to credit the original reporter
of a bug or a contributor who is not credited via Co-authored-by tag.

Format: Name Email [Event]

Example 1 (snippet):

.. code:: text

--CREDITS--
Felipe Pena

Example 1 (full): :ref:sample001.phpt

Example 2 (snippet):

.. code:: text

--CREDITS--
Zoe Slattery [email protected]

TestFest Munich 2009-05-19

Example 2 (full): :ref:sample002.phpt

``--SKIPIF--`` Copy Chapter

Description: A condition or set of conditions used to determine if a test should be skipped.
Tests that are only applicable to a certain platform, extension or PHP version are good reasons for
using a --SKIPIF-- section.

A common practice for extension tests is to write your --SKIPIF-- extension criteria into a file
call skipif.inc and then including that file in the --SKIPIF-- section of all your extension
tests. This promotes the DRY principle and reduces future code maintenance.

Required: No.

Format: PHP code enclosed by PHP tags. If the output of this scripts starts with "skip", the
test is skipped. If the output starts with "xfail", the test is marked as expected failure. If the
output starts with "flaky", the test is marked as flaky test. The "xfail" convention is supported as
of PHP 7.2.0. The "flaky" convention is supported as of PHP 8.2.25 and PHP 8.3.13, respectively.

Example 1 (snippet):

.. code:: php

--SKIPIF--

Example 1 (full): :ref:sample001.phpt

Example 2 (snippet):

.. code:: php

--SKIPIF--

Example 2 (full): :ref:sample003.phpt

Example 3 (snippet):

.. code:: php

--SKIPIF--

Example 3 (full): :ref:xfailif.phpt

Example 4 (snippet):

.. code:: php

--SKIPIF--
<?php
if (getenv("GITHUB_ACTIONS") && PHP_OS_FAMILY === "Darwin") {
die("flaky Occasionally segfaults on macOS for unknown reasons");
}

``--CONFLICTS--`` Copy Chapter

Description: This section is only relevant for parallel test execution (available as of PHP
7.4.0), and allows to specify conflict keys. While a test that conflicts with key K is running, no
other test that conflicts with K is run. For tests conflicting with "all", no other tests are run in
parallel.

An alternative to have a --CONFLICTS-- section is to add a file named CONFLICTS to the
directory containing the tests. The contents of the CONFLICTS file must have the same format as
the contents of the --CONFLICTS-- section.

Required: No.

Format: One conflict key per line. Comment lines starting with # are also allowed.

Example 1 (snippet):

.. code:: text

--CONFLICTS--
server

Example 1 (full): :ref:conflicts_1.phpt

``--WHITESPACE_SENSITIVE--`` Copy Chapter

Description: This flag is used to indicate that the test should not be changed by automated
formatting changes. Available as of PHP 7.4.3.

Required: No.

Format: No value, just the --WHITESPACE_SENSITIVE-- statement.

``--CAPTURE_STDIO--`` Copy Chapter

Description: This section enables which I/O streams the run-tests.php test script will use
when comparing executed file to the expected output. The STDIN is the standard input stream.
When STDOUT is enabled, the test script will also check the contents of the standard output.
When STDERR is enabled, the test script will also compare the contents of the standard error I/O
stream.

If this section is left out of the test, by default, all three streams are enabled, so the tests
without this section capture all and is the same as enabling all three manually.

Required: No.

Format: A case insensitive space, newline or otherwise delimited list of one or more strings of
STDIN, STDOUT, and/or STDERR.

Example 1 (snippet):

.. code:: text

--CAPTURE_STDIO--
STDIN STDERR

Example 1 (full): :ref:capture_stdio_1.phpt

Example 2 (snippet):

.. code:: text

--CAPTURE_STDIO--
STDIN STDOUT

Example 2 (full): :ref:capture_stdio_2.phpt

Example 3 (snippet):

.. code:: text

--CAPTURE_STDIO--
STDIN STDOUT STDERR

Example 3(full): :ref:capture_stdio_3.phpt

``--EXTENSIONS--`` Copy Chapter

Description: Additional required shared extensions to be loaded when running the test. When the
run-tests.php script is executed it loads all the extensions that are available and enabled for
that particular PHP at the time. If the test requires additional extension to be loaded and they
aren't loaded prior to running the test, this section loads them.

Required: No.

Format: A case sensitive newline separated list of extension names.

Example 1 (snippet):

.. code:: text

--EXTENSIONS--
curl
imagick
tokenizer

Example 1 (full): :ref:extensions.phpt

``--POST--`` Copy Chapter

Description: POST variables or data to be passed to the test script. This section forces the use
of the CGI binary instead of the usual CLI one.

Required: No.

Requirements: PHP CGI binary.

Format: Follows the HTTP post data format.

Example 1 (snippet):

.. code:: text

--POST--
c=string&d=12345.7

Example 1 (full): :ref:sample001.phpt

Example 2 (snippet):

.. code:: xml

--POST--
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:si="http://soapinterop.org/xsd">
SOAP-ENV:Body
<ns1:test xmlns:ns1="http://testuri.org" />

Example 2 (full): :ref:sample005.phpt

``--POST_RAW--`` Copy Chapter

Description: Raw POST data to be passed to the test script. This differs from the section above
because it doesn't automatically set the Content-Type, this leaves you free to define your own
within the section. This section forces the use of the CGI binary instead of the usual CLI one.

Required: No.

Requirements: PHP CGI binary.

Test Script Support: run-tests.php

Format: Follows the HTTP post data format.

Example 1 (snippet):

.. code:: text

--POST_RAW--
Content-type: multipart/form-data, boundary=AaB03x

--AaB03x content-disposition: form-data; name="field1"

Joe Blow
--AaB03x
content-disposition: form-data; name="pics"; filename="file1.txt"
Content-Type: text/plain

abcdef123456789
--AaB03x--

Example 1 (full): :ref:sample006.phpt

``--PUT--`` Copy Chapter

Description: Similar to the section above, PUT data to be passed to the test script. This
section forces the use of the CGI binary instead of the usual CLI one.

Required: No.

Requirements: PHP CGI binary.

Test Script Support: run-tests.php

Format: Raw data optionally preceded by a Content-Type header.

Example 1 (snippet):

.. code:: text

--PUT--
Content-Type: text/json

{"name":"default output handler","type":0,"flags":112,"level":0,"chunk_size":0,"buffer_size":16384,"buffer_used":3}

``--GZIP_POST--`` Copy Chapter

Description: When this section exists, the POST data will be gzencode()'d. This section forces
the use of the CGI binary instead of the usual CLI one.

Required: No.

Test Script Support: run-tests.php

Format: Just add the content to be gzencode()'d in the section.

Example 1 (snippet):

.. code:: xml

--GZIP_POST--
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:si="http://soapinterop.org/xsd">
SOAP-ENV:Body
<ns1:test xmlns:ns1="http://testuri.org" />

Example 1 (full): :ref:sample005.phpt

``--DEFLATE_POST--`` Copy Chapter

Description: When this section exists, the POST data will be gzcompress()'ed. This section
forces the use of the CGI binary instead of the usual CLI one.

Required: No.

Requirements:

Test Script Support: run-tests.php

Format: Just add the content to be gzcompress()'ed in the section.

Example 1 (snippet):

.. code:: xml

--DEFLATE_POST--

<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:si="http://soapinterop.org/xsd">
SOAP-ENV:Body
<ns1:test xmlns:ns1="http://testuri.org" />

Example 1 (full): :ref:sample007.phpt

``--GET--`` Copy Chapter

Description: GET variables to be passed to the test script. This section forces the use of the
CGI binary instead of the usual CLI one.

Required: No.

Requirements: PHP CGI binary.

Format: A single line of text passed as the GET data to the script.

Example 1 (snippet):

.. code:: text

--GET--
a=test&b=http://example.com

Example 1 (full): :ref:sample001.phpt

Example 2 (snippet):

.. code:: text

--GET--
ar[elm1]=1234&ar[elm2]=0660&a=0234

Example 2 (full): :ref:sample008.phpt

``--COOKIE--`` Copy Chapter

Description: Cookies to be passed to the test script. This section forces the use of the CGI
binary instead of the usual CLI one.

Required: No.

Requirements: PHP CGI binary.

Test Script Support: run-tests.php

Format: A single line of text in a valid HTTP cookie format.

Example 1 (snippet):

.. code::

--COOKIE--
hello=World;goodbye=MrChips

Example 1 (full): :ref:sample002.phpt

``--STDIN--`` Copy Chapter

Description: Data to be fed to the test script's standard input.

Required: No.

Test Script Support: run-tests.php

Format: Any text within this section is passed as STDIN to PHP.

Example 1 (snippet):

.. code:: text

--STDIN--
fooBar
use this to input some thing to the php script

Example 1 (full): :ref:sample009.phpt

``--INI--`` Copy Chapter

Description: To be used if you need a specific php.ini setting for the test.

Required: No.

Format: Key value pairs including automatically replaced tags. One setting per line. Content
that is not a valid ini setting may cause failures.

The following is a list of all tags and what they are used to represent:

• {PWD}: Represents the directory of the file containing the --INI-- section.
• {TMP}: Represents the system's temporary directory. Available as of PHP 7.2.19 and 7.3.6.

Example 1 (snippet):

.. code:: text

--INI--
precision=14

Example 1 (full): :ref:sample001.phpt

Example 2 (snippet):

.. code:: text

--INI--
session.use_cookies=0
session.cache_limiter=
register_globals=1
session.serialize_handler=php
session.save_handler=files

Example 2 (full): :ref:sample003.phpt

``--ARGS--`` Copy Chapter

Description: A single line defining the arguments passed to PHP.

Required: No.

Format: A single line of text that is passed as the argument(s) to the PHP CLI.

Example 1 (snippet):

.. code:: text

--ARGS--
--arg value --arg=value -avalue -a=value -a value

Example 1 (full): :ref:sample010.phpt

``--ENV--`` Copy Chapter

Description: Configures environment variables such as those found in the $_SERVER global
array.

Required: No.

Format: Key value pairs. One setting per line.

Example 1 (snippet):

.. code:: text

--ENV--
SCRIPT_NAME=/frontcontroller10.php
REQUEST_URI=/frontcontroller10.php/hi
PATH_INFO=/hi

Example 1 (full): :ref:sample018.phpt

``--PHPDBG--`` Copy Chapter

Description: This section takes arbitrary phpdbg commands and executes the test file according
to them as it would be run in the phpdbg prompt.

Required: No.

Format: Arbitrary phpdbg commands

Example 1 (snippet):

.. code:: text

--PHPDBG--
b
4
b
del
0
b
5
r
b
del
1
r
y
q

Example 1 (full): :ref:phpdbg_1.phpt

``--FILE--`` Copy Chapter

Description: The test source code.

Required: One of the FILE type sections is required.

Format: PHP source code enclosed by PHP tags.

Example 1 (snippet):

.. code:: php

--FILE--

Example 1 (full): :ref:sample001.phpt

``--FILEEOF--`` Copy Chapter

Description: An alternative to --FILE-- where any trailing line breaks (\n || \r || \r\n
found at the end of the section) are omitted. This is an extreme edge-case feature, so 99.99% of the
time you won't need this section.

Required: One of the FILE type sections is required.

Test Script Support: run-tests.php

Format: PHP source code enclosed by PHP tags.

Example 1 (snippet):

.. code:: php

--FILEEOF--
<?php
eval("echo 'Hello'; // comment");
echo " World";
//last line comment

Example 1 (full): :ref:sample011.phpt

``--FILE_EXTERNAL--`` Copy Chapter

Description: An alternative to --FILE--. This is used to specify that an external file
should be used as the --FILE-- contents of the test file, and is designed for running the same
test file with different ini, environment, post/get or other external inputs. Basically it allows
you to DRY up some of your tests. The file must be in the same directory as the test file, or in a
subdirectory.

Required: One of the FILE type sections is required.

Test Script Support: run-tests.php

Format: path/to/file. Single line.

Example 1 (snippet):

.. code:: text

--FILE_EXTERNAL--
files/file012.inc

Example 1 (full): :ref:sample012.phpt

``--REDIRECTTEST--`` Copy Chapter

Description: This block allows you to redirect from one test to a bunch of other tests. It also
allows you to set configurations which are used on all tests in your destination.

Required: One of the FILE type sections is required.

Test Script Support: run-tests.php

Format: PHP source which is run through eval(). The tests destination is the value of an
array index 'TESTS'. Also, keep in mind, you can not use a REDIRECTTEST which is being pointed
to by another test which contains a REDIRECTTEST. In other words, no nesting.

The relative path declared in 'TESTS' is relative to the base directory for the PHP source code, not
relative to the current directory.

Last note, the array in this section must be returned to work.

Example 1 (snippet):

.. code:: php

--REDIRECTTEST--
return array(
'ENV' => array(
'PDOTEST_DSN' => 'sqlite2::memory:'
),
'TESTS' => 'ext/pdo/tests'
);

Example 1 (full): :ref:sample013.phpt Note: The destination tests for this example are not
included. See the PDO extension tests for reference to live tests using this section.

Example 2 (snippet):

.. code:: php

--REDIRECTTEST--

magic auto-configuration

$config = array(
'TESTS' => 'ext/pdo/tests'
);

if (false !== getenv('PDO_MYSQL_TEST_DSN')) {
# user set them from their shell
$config['ENV']['PDOTEST_DSN'] = getenv('PDO_MYSQL_TEST_DSN');
$config['ENV']['PDOTEST_USER'] = getenv('PDO_MYSQL_TEST_USER');
$config['ENV']['PDOTEST_PASS'] = getenv('PDO_MYSQL_TEST_PASS');
if (false !== getenv('PDO_MYSQL_TEST_ATTR')) {
$config['ENV']['PDOTEST_ATTR'] = getenv('PDO_MYSQL_TEST_ATTR');
}
} else {
$config['ENV']['PDOTEST_DSN'] = 'mysql:host=localhost;dbname=test';
$config['ENV']['PDOTEST_USER'] = 'root';
$config['ENV']['PDOTEST_PASS'] = '';
}

return $config;

Example 2 (full): :ref:sample014.phpt

Note: The destination tests for this example are not included. See the PDO extension tests for
reference to live tests using this section.

``--CGI--`` Copy Chapter

Description: This section takes no value. It merely provides a simple marker for tests that MUST
be run as CGI, even if there is no --POST-- or --GET-- sections in the test file.

Required: No.

Format: No value, just the --CGI-- statement.

Example 1 (snippet):

.. code:: text

--CGI--

Example 1 (full): :ref:sample016.phpt

``--XFAIL--`` Copy Chapter

Description: This section identifies this test as one that is currently expected to fail. It
should include a brief description of why it's expected to fail. Reasons for such expectations
include tests that are written before the functionality they are testing is implemented or notice of
a bug which is due to upstream code such as an extension which provides PHP support for some other
software.

Please do NOT include an --XFAIL-- without providing a text description for the reason it's
being used.

Required: No.

Test Script Support: run-tests.php

Format: A short plain text description of why this test is currently expected to fail.

Example 1 (snippet):

.. code:: text

--XFAIL--
This bug might be still open on aix5.2-ppc64 and hpux11.23-ia64

Example 1 (full): :ref:sample017.phpt

``--FLAKY--`` Copy Chapter

Description: This section identifies this test as one that occasionally fails. If the test
actually fails, it will be retried one more time, and that result will be reported. The section
should include a brief description of why the test is flaky. Reasons for this include tests that
rely on relatively precise timing, or temporary disc states. Available as of PHP 8.1.22 and 8.2.9,
respectively.

Please do NOT include a --FLAKY-- section without providing a text description for the reason it
is being used.

Required: No.

Test Script Support: run-tests.php

Format: A short plain text description of why this test is flaky.

Example 1 (snippet):

.. code::

--FLAKY--
This test frequently fails in CI

Example 1 (full): flaky.phpt

``--EXPECTHEADERS--`` Copy Chapter

Description: The expected headers. Any header specified here must exist in the response and have
the same value or the test fails. Additional headers found in the actual tests while running are
ignored.

Required: No.

Format: HTTP style headers. May include multiple lines.

Example 1 (snippet):

--EXPECTHEADERS-- Status: 404

Example 1 (snippet):

.. code:: text

--EXPECTHEADERS--
Content-type: text/html; charset=UTF-8
Status: 403 Access Denied

Example 1 (full): :ref:sample018.phpt

Note: The destination tests for this example are not included. See the phar extension tests for
reference to live tests using this section.

``--EXPECT--`` Copy Chapter

Description: The expected output from the test script. This must match the actual output from
the test script exactly for the test to pass.

Required: One of the EXPECT type sections is required.

Format: Plain text. Multiple lines of text are allowed.

Example 1 (snippet):

.. code:: text

--EXPECT--
array(2) {
["hello"]=>
string(5) "World"
["goodbye"]=>
string(7) "MrChips"
}

Example 1 (full): :ref:sample002.phpt

``--EXPECT_EXTERNAL--`` Copy Chapter

Description: Similar to --EXPECT-- section, but just stating a filename where to load the
expected output from.

Required: One of the EXPECT type sections is required.

Test Script Support: run-tests.php

Example 1 (snippet):

.. code:: text

--EXPECT_EXTERNAL--
test001.expected.txt

test001.expected.txt

.. code:: php

array(2) {
["hello"]=>
string(5) "World"
["goodbye"]=>
string(7) "MrChips"
}

``--EXPECTF--`` Copy Chapter

Description: An alternative of --EXPECT--. Where it differs from --EXPECT-- is that it
uses a number of substitution tags for strings, spaces, digits, etc. that appear in test case output
but which may vary between test runs. The most common example of this is to use %s and %d to match
the file path and line number which are output by PHP Warnings.

Required: One of the EXPECT type sections is required.

Format: Plain text including tags which are inserted to represent different types of output
which are not guaranteed to have the same value on subsequent runs or when run on different
platforms.

The following is a list of all tags and what they are used to represent:

• %e: Represents a directory separator, for example / on Linux.
• %s: One or more of anything (character or white space) except the end of line character.
• %S: Zero or more of anything (character or white space) except the end of line character.
• %a: One or more of anything (character or white space) including the end of line
  character.
• %A: Zero or more of anything (character or white space) including the end of line
  character.
• %w: Zero or more white space characters.
• %i: A signed integer value, for example +3142, -3142, 3142.
• %d: An unsigned integer value, for example 123456.
• %x: One or more hexadecimal character. That is, characters in the range 0-9, a-f, A-F.
• %f: A floating point number, for example: 3.142, -3.142, 3.142E-10, 3.142e+10.
• %c: A single character of any sort (.).
• %r...%r: Any string (...) enclosed between two %r will be treated as a regular
  expression.

Example 1 (snippet):

.. code:: text

--EXPECTF--
string(4) "test"
string(18) "http://example.com"
string(27) "<b>test</b>"

Notice: Object of class stdClass could not be converted to int in %ssample001.php on line %d
bool(false)
string(6) "string"
float(12345.7)
string(29) "<p>string</p>"
bool(false)

Warning: filter_var() expects parameter 2 to be long, string given in %s011.php on line %d
NULL

Warning: filter_input() expects parameter 3 to be long, string given in %s011.php on line %d
NULL

Warning: filter_var() expects at most 3 parameters, 5 given in %s011.php on line %d
NULL

Warning: filter_var() expects at most 3 parameters, 5 given in %s011.php on line %d
NULL
Done

Example 1 (full): :ref:sample001.phpt

Example 2 (snippet):

.. code:: text

--EXPECTF--
Warning: bzopen() expects exactly 2 parameters, 0 given in %s on line %d NULL

Warning: bzopen(): '' is not a valid mode for bzopen(). Only 'w' and 'r' are supported. in %s on line %d
bool(false)

Warning: bzopen(): filename cannot be empty in %s on line %d
bool(false)

Warning: bzopen(): filename cannot be empty in %s on line %d
bool(false)

Warning: bzopen(): 'x' is not a valid mode for bzopen(). Only 'w' and 'r' are supported. in %s on line %d
bool(false)

Warning: bzopen(): 'rw' is not a valid mode for bzopen(). Only 'w' and 'r' are supported. in %s on line %d
bool(false)

Warning: bzopen(no_such_file): failed to open stream: No such file or directory in %s on line %d
bool(false)
resource(%d) of type (stream) Done

Example 2 (full): :ref:sample019.phpt

Example 3 (snippet):

.. code:: text

--EXPECTF--
object(DOMNodeList)#%d (0) {
}
int(0)
bool(true)
bool(true)
string(0) ""
bool(true)
bool(true)
bool(false)
bool(false)

Example 2 (full): :ref:sample020.phpt

``--EXPECTF_EXTERNAL--`` Copy Chapter

Description: Similar to --EXPECTF-- section, but like the --EXPECT_EXTERNAL-- section
just stating a filename where to load the expected output from.

Required: One of the EXPECT type sections is required.

Test Script Support: run-tests.php

``--EXPECTREGEX--`` Copy Chapter

Description: An alternative of --EXPECT--. This form allows the tester to specify the result
in a regular expression.

Required: One of the EXPECT type sections is required.

Format: Plain text including regular expression patterns which represent data that can vary
between subsequent runs of a test or when run on different platforms.

Example 1 (snippet):

.. code:: text

--EXPECTREGEX--
M_E : 2.718281[0-9]*
M_LOG2E : 1.442695[0-9]*
M_LOG10E : 0.434294[0-9]*
M_LN2 : 0.693147[0-9]*
M_LN10 : 2.302585[0-9]*
M_PI : 3.141592[0-9]*
M_PI_2 : 1.570796[0-9]*
M_PI_4 : 0.785398[0-9]*
M_1_PI : 0.318309[0-9]*
M_2_PI : 0.636619[0-9]*
M_SQRTPI : 1.772453[0-9]*
M_2_SQRTPI: 1.128379[0-9]*
M_LNPI : 1.144729[0-9]*
M_EULER : 0.577215[0-9]*
M_SQRT2 : 1.414213[0-9]*
M_SQRT1_2 : 0.707106[0-9]*
M_SQRT3 : 1.732050[0-9]*

Example 1 (full): :ref:sample021.phpt

Example 2 (snippet):

.. code:: text

--EXPECTF--
*** Testing imap_append() : basic functionality ***
Create a new mailbox for test
Create a temporary mailbox and add 0 msgs
.. mailbox '%s' created
Add a couple of msgs to new mailbox {%s}INBOX.%s
bool(true)
bool(true)
Msg Count after append : 2
List the msg headers
array(2) {
[0]=>
string(%d) "%w%s 1)%s webmaster@something. Test message (%d chars)"
[1]=>
string(%d) "%w%s 2)%s webmaster@something. Another test (%d chars)"
}

Example 2 (full): :ref:sample025.phpt

Example 3 (snippet):

.. code:: text

--EXPECTREGEX--
string(4) "-012"
string(8) "2d303132"
(string(13) " 4294967284"|string(20) "18446744073709551604")
(string(26) "20202034323934393637323834"|string(40) "3138343436373434303733373039353531363034")

Example 3 (full): :ref:sample023.phpt

``--EXPECTREGEX_EXTERNAL--`` Copy Chapter

Description: Similar to --EXPECTREGEX-- section, but like the --EXPECT_EXTERNAL--
section just stating a filename where to load the expected output from.

Required: One of the EXPECT type sections is required.

Test Script Support: run-tests.php

``--CLEAN--`` Copy Chapter

Description: Code that is executed after a test completes. It's main purpose is to allow you to
clean up after yourself. You might need to remove files created during the test or close sockets or
database connections following a test. Infact, even if a test fails or encounters a fatal error
during the test, the code found in the --CLEAN-- section will still run.

Code in the clean section is run in a completely different process than the one the test was run in.
So do not try accessing variables you created in the --FILE-- section from inside the
--CLEAN-- section, they won't exist.

Using the switch --no-clean on run-tests.php, you can prevent the code found in the
--CLEAN-- section of a test from running. This allows you to inspect generated data or files
without them being removed by the --CLEAN-- section.

Required: No.

Test Script Support: run-tests.php

Format: PHP source code enclosed by PHP tags.

Example 1 (snippet):

.. code:: php

--CLEAN--

Example 1 (full): :ref:sample024.phpt

Example 2 (snippet):

.. code:: php

--CLEAN--

Example 2 (full): :ref:sample025.phpt

Example 3 (snippet):

.. code:: php

--CLEAN--

Example 3 (full): :ref:sample022.phpt

Samples

capture_stdio_1.phpt Copy Chapter

.. code:: php

--TEST--
Test covering the I/O stdin and stdout streams.
--DESCRIPTION--
This tests checks if the output of stdin and stdout I/O streams match the
expected content.
--CAPTURE_STDIO--
STDIN STDERR
--FILE--

--EXPECT--
This is error sent to the stderr I/O stream

capture_stdio_2.phpt Copy Chapter

.. code:: php

--TEST--
Test covering the I/O stdin and stderr streams.
--DESCRIPTION--
This tests checks if the output of stdin and stderr I/O streams match the
expected content.
--CAPTURE_STDIO--
STDIN STDOUT
--FILE--

--EXPECT--
Hello, world. This is sent to the stdout I/O stream

capture_stdio_3.phpt Copy Chapter

.. code:: php

--TEST--
Test covering the all standard I/O streams.
--DESCRIPTION--
This tests checks if the output of stdin, stdout and stderr I/O streams match
the expected content.
--CAPTURE_STDIO--
STDIN STDOUT STDERR
--FILE--

--EXPECT--
Hello, world. This is sent to the stdout I/O stream
This is error sent to the stderr I/O stream

clean.php Copy Chapter

.. code:: php

conflicts_1.phpt Copy Chapter

.. code:: php

--TEST--
Test get_headers() function : test with context
--CONFLICTS--
server
--FILE--
<?php

include DIR."/../../../../sapi/cli/tests/php_cli_server.inc";
php_cli_server_start('header("X-Request-Method: ".$_SERVER["REQUEST_METHOD"]);');

$opts = array(
'http' => array(
'method' => 'HEAD'
)
);

$context = stream_context_create($opts);
$headers = get_headers("http://".PHP_CLI_SERVER_ADDRESS, 1, $context);
echo $headers["X-Request-Method"]."\n";

stream_context_set_default($opts);
$headers = get_headers("http://".PHP_CLI_SERVER_ADDRESS, 1);
echo $headers["X-Request-Method"]."\n";

echo "Done";
?>
--EXPECT--
HEAD
HEAD
Done

extensions.phpt Copy Chapter

.. code:: php

--TEST--
phpt EXTENSIONS directive with shared extensions
--DESCRIPTION--
This test covers the presence of some loaded extensions with a list of additional
extensions to be loaded when running test.
--EXTENSIONS--
curl
imagick
tokenizer
--FILE--

--EXPECT--
bool(true)
bool(true)
bool(true)

file012.phpt Copy Chapter

.. code:: php

phpdbg_1.phpt Copy Chapter

.. code:: php

--TEST--
Test deleting breakpoints
--PHPDBG--
b 4
b del 0
b 5
r
b del 1
r
y
q
--EXPECTF--
[Successful compilation of %s]
prompt> [Breakpoint #0 added at %s:4]
prompt> [Deleted breakpoint #0]
prompt> [Breakpoint #1 added at %s:5]
prompt> 12
[Breakpoint #1 at %s:5, hits: 1]

00005: echo $i++;
00006: echo $i++;
00007:

prompt> [Deleted breakpoint #1]
prompt> Do you really want to restart execution? (type y or n): 1234
[Script ended normally]
prompt>
--FILE--
<?php
$i = 1;
echo $i++;
echo $i++;
echo $i++;
echo $i++;

sample001.phpt Copy Chapter

.. code:: php

--TEST--
Test filter_input() with GET and POST data.
--DESCRIPTION--
This test covers both valid and invalid usages of
filter_input() with INPUT_GET and INPUT_POST data
and several different filter sanitizers.
--CREDITS--
Felipe Pena [email protected]
--INI--
precision=14
--SKIPIF--

--GET--
a=test&b=https://example.com
--POST--
c=string&d=12345.7
--FILE--

--EXPECTF--
string(4) "test"
string(19) "https://example.com"
string(27) "<b>test</b>"

Notice: Object of class stdClass could not be converted to int in %ssample001.php on line %d
bool(false)
string(6) "string"
float(12345.7)
string(29) "<p>string</p>"
bool(false)

Warning: filter_var() expects parameter 2 to be long, string given in %ssample001.php on line %d
NULL

Warning: filter_input() expects parameter 3 to be long, string given in %ssample001.php on line %d
NULL

Warning: filter_var() expects at most 3 parameters, 5 given in %ssample001.php on line %d
NULL

Warning: filter_var() expects at most 3 parameters, 5 given in %ssample001.php on line %d
NULL
Done

sample002.phpt Copy Chapter

.. code:: php

--TEST--
Test receipt of cookie data.
--CREDITS--
Zoe Slattery [email protected]

TestFest Munich 2009-05-19

--COOKIE--
hello=World;goodbye=MrChips
--FILE--

--EXPECT--
array(2) {
["hello"]=>
string(5) "World"
["goodbye"]=>
string(7) "MrChips"
}

sample003.phpt Copy Chapter

.. code:: php

--TEST--
session object deserialization
--SKIPIF--

--INI--
session.use_cookies=0
session.cache_limiter=
register_globals=1
session.serialize_handler=php
session.save_handler=files
--FILE--
<?php
error_reporting(E_ALL);

class foo {
public $bar = "ok";
function method() { $this->yes++; }
}

session_id("abtest");
session_start();
session_decode('baz|O:3:"foo":2:{s:3:"bar";s:2:"ok";s:3:"yes";i:1;}arr|a:1:{i:3;O:3:"foo":2:{s:3:"bar";s:2:"ok";s:3:"yes";i:1;}}');

$baz->method();
$arr[3]->method();

var_dump($baz);
var_dump($arr);
session_destroy();
--EXPECT--
object(foo)#1 (2) {
["bar"]=>
string(2) "ok"
["yes"]=>
int(2)
}
array(1) {
[3]=>
object(foo)#2 (2) {
["bar"]=>
string(2) "ok"
["yes"]=>
int(2)
}
}

sample005.phpt Copy Chapter

.. code:: php

--TEST--
SOAP Server 19: compressed request (gzip)
--SKIPIF--

--INI--
precision=14
--GZIP_POST--
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:si="http://soapinterop.org/xsd">
SOAP-ENV:Body
<ns1:test xmlns:ns1="http://testuri.org" />


--FILE--
<?php
function test() {
return "Hello World";
}

$server = new soapserver(null,array('uri'=>"http://testuri.org"));
$server->addfunction("test");
$server->handle();
echo "ok\n";
?>
--EXPECT--

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://testuri.org" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">SOAP-ENV:Bodyns1:testResponseHello World
ok

sample006.phpt Copy Chapter

.. code:: php

--TEST--
is_uploaded_file() function
--CREDITS--
Dave Kelsey [email protected]
--SKIPIF--

--POST_RAW--
Content-type: multipart/form-data, boundary=AaB03x

--AaB03x
content-disposition: form-data; name="field1"

Joe Blow
--AaB03x
content-disposition: form-data; name="pics"; filename="file1.txt"
Content-Type: text/plain

abcdef123456789
--AaB03x--
--FILE--
<?php
// uploaded file
var_dump(is_uploaded_file($_FILES['pics']['tmp_name']));

// not an uploaded file
var_dump(is_uploaded_file($_FILES['pics']['name']));

// not an uploaded file
var_dump(is_uploaded_file('random_filename.txt'));

// not an uploaded file
var_dump(is_uploaded_file('FILE'));

// Error cases
var_dump(is_uploaded_file());
var_dump(is_uploaded_file('a', 'b'));

?>
--EXPECTF--
bool(true)
bool(false)
bool(false)
bool(false)

Warning: is_uploaded_file() expects exactly 1 parameter, 0 given in %s on line %d
NULL

Warning: is_uploaded_file() expects exactly 1 parameter, 2 given in %s on line %d
NULL

sample007.phpt Copy Chapter

.. code:: php

--TEST--
SOAP Server 20: compressed request (deflate)
--SKIPIF--

--INI--
precision=14
--DEFLATE_POST--

<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:si="http://soapinterop.org/xsd">
SOAP-ENV:Body
<ns1:test xmlns:ns1="http://testuri.org" />


--FILE--
<?php
function test() {
return "Hello World";
}

$server = new soapserver(null,array('uri'=>"http://testuri.org"));
$server->addfunction("test");
$server->handle();
echo "ok\n";
?>
--EXPECT--

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://testuri.org" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">SOAP-ENV:Bodyns1:testResponseHello World
ok

sample008.phpt Copy Chapter

.. code:: php

--TEST--
GET/POST/REQUEST Test with input_filter
--SKIPIF--

--POST--
d=379
--GET--
ar[elm1]=1234&ar[elm2]=0660&a=0234
--FILE--
<?php
$ret = filter_input(INPUT_GET, 'a', FILTER_VALIDATE_INT);
var_dump($ret);

$ret = filter_input(INPUT_GET, 'a', FILTER_VALIDATE_INT, array('flags'=>FILTER_FLAG_ALLOW_OCTAL));
var_dump($ret);

$ret = filter_input(INPUT_GET, 'ar', FILTER_VALIDATE_INT, array('flags'=>FILTER_REQUIRE_ARRAY));
var_dump($ret);

$ret = filter_input(INPUT_GET, 'ar', FILTER_VALIDATE_INT, array('flags'=>FILTER_FLAG_ALLOW_OCTAL|FILTER_REQUIRE_ARRAY));
var_dump($ret);

?>
--EXPECT--
bool(false)
int(156)
array(2) {
["elm1"]=>
int(1234)
["elm2"]=>
bool(false)
}
array(2) {
["elm1"]=>
int(1234)
["elm2"]=>
int(432)
}

sample009.phpt Copy Chapter

.. code:: php

--TEST--
STDIN input
--FILE--

--STDIN--
fooBar
use this to input some thing to the php script
--EXPECT--
string(54) "fooBar
use this to input some thing to the php script
"

sample010.phpt Copy Chapter

.. code:: php

--TEST--
getopt#005 (Required values)
--ARGS--
--arg value --arg=value -avalue -a=value -a value
--INI--
register_argc_argv=On
variables_order=GPS
--FILE--

--EXPECT--
array(2) {
["arg"]=>
array(2) {
[0]=>
string(5) "value"
[1]=>
string(5) "value"
}
["a"]=>
array(3) {
[0]=>
string(5) "value"
[1]=>
string(5) "value"
[2]=>
string(5) "value"
}
}

sample011.phpt Copy Chapter

.. code:: php

--TEST--
Bug #35382 (Comment in end of file produces fatal error)
--FILEEOF--
<?php
eval("echo 'Hello'; // comment");
echo " World";
//last line comment
--EXPECTF--
Hello World

sample012.phpt Copy Chapter

.. code:: php

--TEST--
sample test for file_external
--FILE_EXTERNAL--
files/file012.inc
--EXPECT--
hello world

sample013.phpt Copy Chapter

.. code:: php

--TEST--
SQLite2
--SKIPIF--

--REDIRECTTEST--
return array(
'ENV' => array(
'PDOTEST_DSN' => 'sqlite2::memory:'
),
'TESTS' => 'ext/pdo/tests'
);

sample014.phpt Copy Chapter

.. code:: php

--TEST--
MySQL
--SKIPIF--

--REDIRECTTEST--

magic auto-configuration

$config = array(
'TESTS' => 'ext/pdo/tests'
);

if (false !== getenv('PDO_MYSQL_TEST_DSN')) {
# user set them from their shell
$config['ENV']['PDOTEST_DSN'] = getenv('PDO_MYSQL_TEST_DSN');
$config['ENV']['PDOTEST_USER'] = getenv('PDO_MYSQL_TEST_USER');
$config['ENV']['PDOTEST_PASS'] = getenv('PDO_MYSQL_TEST_PASS');
if (false !== getenv('PDO_MYSQL_TEST_ATTR')) {
$config['ENV']['PDOTEST_ATTR'] = getenv('PDO_MYSQL_TEST_ATTR');
}
} else {
$config['ENV']['PDOTEST_DSN'] = 'mysql:host=localhost;dbname=test';
$config['ENV']['PDOTEST_USER'] = 'root';
$config['ENV']['PDOTEST_PASS'] = '';
}

return $config;

sample016.phpt Copy Chapter

.. code:: php

--TEST--
Test get variables with CGI binary
--GET--
hello=World&goodbye=MrChips
--CGI--
--FILE--

--EXPECT--
array(2) {
["hello"]=>
string(5) "World"
["goodbye"]=>
string(7) "MrChips"
}

sample017.phpt Copy Chapter

.. code:: php

--TEST--
PDO Common: Bug #34630 (inserting streams as LOBs)
--SKIPIF--

--FILE--
<?php
if (getenv('REDIR_TEST_DIR') === false) putenv('REDIR_TEST_DIR='.DIR . '/../../pdo/tests/');
require_once getenv('REDIR_TEST_DIR') . 'pdo_test.inc';
$db = PDOTest::factory();

$driver = $db->getAttribute(PDO::ATTR_DRIVER_NAME);
$is_oci = $driver == 'oci';

if ($is_oci) {
$db->exec('CREATE TABLE test (id int NOT NULL PRIMARY KEY, val BLOB)');
} else {
$db->exec('CREATE TABLE test (id int NOT NULL PRIMARY KEY, val VARCHAR(256))');
}
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

$fp = tmpfile();
fwrite($fp, "I am the LOB data");
rewind($fp);

if ($is_oci) {
/* oracle is a bit different; you need to initiate a transaction otherwise
* the empty blob will be committed implicitly when the statement is
* executed */
$db->beginTransaction();
$insert = $db->prepare("insert into test (id, val) values (1, EMPTY_BLOB()) RETURNING val INTO :blob");
} else {
$insert = $db->prepare("insert into test (id, val) values (1, :blob)");
}
$insert->bindValue(':blob', $fp, PDO::PARAM_LOB);
$insert->execute();
$insert = null;

$db->setAttribute(PDO::ATTR_STRINGIFY_FETCHES, true);
var_dump($db->query("SELECT * from test")->fetchAll(PDO::FETCH_ASSOC));

?>
--XFAIL--
This bug might be still open on aix5.2-ppc64 and hpux11.23-ia64
--EXPECT--
array(1) {
[0]=>
array(2) {
["id"]=>
string(1) "1"
["val"]=>
string(17) "I am the LOB data"
}
}

sample018.phpt Copy Chapter

.. code:: php

--TEST--
Phar front controller rewrite access denied [cache_list]
--INI--
default_charset=UTF-8
phar.cache_list={PWD}/frontcontroller10.php
--SKIPIF--

--ENV--
SCRIPT_NAME=/frontcontroller10.php
REQUEST_URI=/frontcontroller10.php/hi
PATH_INFO=/hi
--FILE_EXTERNAL--
files/frontcontroller4.phar
--EXPECTHEADERS--
Content-type: text/html; charset=UTF-8
Status: 403 Access Denied
--EXPECT--

<h1>403 - File /hi Access Denied</h1>

sample019.phpt Copy Chapter

.. code:: php

--TEST--
bzopen() and invalid parameters
--SKIPIF--

--FILE--
<?php

var_dump(bzopen());
var_dump(bzopen("", ""));
var_dump(bzopen("", "r"));
var_dump(bzopen("", "w"));
var_dump(bzopen("", "x"));
var_dump(bzopen("", "rw"));
var_dump(bzopen("no_such_file", "r"));

$fp = fopen(FILE,"r");
var_dump(bzopen($fp, "r"));

echo "Done\n";
?>
--EXPECTF--
Warning: bzopen() expects exactly 2 parameters, 0 given in %s on line %d
NULL

Warning: bzopen(): '' is not a valid mode for bzopen(). Only 'w' and 'r' are supported. in %s on line %d
bool(false)

Warning: bzopen(): filename cannot be empty in %s on line %d
bool(false)

Warning: bzopen(): filename cannot be empty in %s on line %d
bool(false)

Warning: bzopen(): 'x' is not a valid mode for bzopen(). Only 'w' and 'r' are supported. in %s on line %d
bool(false)

Warning: bzopen(): 'rw' is not a valid mode for bzopen(). Only 'w' and 'r' are supported. in %s on line %d
bool(false)

Warning: bzopen(no_such_file): failed to open stream: No such file or directory in %s on line %d
bool(false)
resource(%d) of type (stream)
Done

sample020.phpt Copy Chapter

.. code:: php

--TEST--
Bug #42082 (NodeList length zero should be empty)
--FILE--
<?php
$doc = new DOMDocument();
$xpath = new DOMXPath($doc);
$nodes = $xpath->query('*');
var_dump($nodes);
var_dump($nodes->length);
$length = $nodes->length;
var_dump(empty($nodes->length), empty($length));

$doc->loadXML("");
var_dump($doc->firstChild->nodeValue, empty($doc->firstChild->nodeValue), isset($doc->firstChild->nodeValue));
var_dump(empty($doc->nodeType), empty($doc->firstChild->nodeType))
?>
--EXPECTF--
object(DOMNodeList)#%d (0) {
}
int(0)
bool(true)
bool(true)
string(0) ""
bool(true)
bool(true)
bool(false)
bool(false)

sample021.phpt Copy Chapter

.. code:: php

--TEST--
Math constants
--INI--
precision=14
--FILE--

--EXPECTREGEX--
M_E : 2.718281[0-9]*
M_LOG2E : 1.442695[0-9]*
M_LOG10E : 0.434294[0-9]*
M_LN2 : 0.693147[0-9]*
M_LN10 : 2.302585[0-9]*
M_PI : 3.141592[0-9]*
M_PI_2 : 1.570796[0-9]*
M_PI_4 : 0.785398[0-9]*
M_1_PI : 0.318309[0-9]*
M_2_PI : 0.636619[0-9]*
M_SQRTPI : 1.772453[0-9]*
M_2_SQRTPI: 1.128379[0-9]*
M_LNPI : 1.144729[0-9]*
M_EULER : 0.577215[0-9]*
M_SQRT2 : 1.414213[0-9]*
M_SQRT1_2 : 0.707106[0-9]*
M_SQRT3 : 1.732050[0-9]*

sample022.phpt Copy Chapter

.. code:: php

--TEST--
shm_detach() tests
--SKIPIF--

--FILE--
<?php

$key = ftok(DIR.'/003.phpt', 'q');

var_dump(shm_detach());
var_dump(shm_detach(1,1));

$s = shm_attach($key);

var_dump(shm_detach($s));
var_dump(shm_detach($s));
shm_remove($s);

var_dump(shm_detach(0));
var_dump(shm_detach(1));
var_dump(shm_detach(-1));

echo "Done\n";
?>
--CLEAN--

--EXPECTF--
Warning: shm_detach() expects exactly 1 parameter, 0 given in %ssample022.php on line %d
NULL

Warning: shm_detach() expects exactly 1 parameter, 2 given in %ssample022.php on line %d
NULL
bool(true)

Warning: shm_detach(): %d is not a valid sysvshm resource in %ssample022.php on line %d
bool(false)

Warning: shm_remove(): %d is not a valid sysvshm resource in %ssample022.php on line %d

Warning: shm_detach() expects parameter 1 to be resource, integer given in %ssample022.php on line %d
NULL

Warning: shm_detach() expects parameter 1 to be resource, integer given in %ssample022.php on line %d
NULL

Warning: shm_detach() expects parameter 1 to be resource, integer given in %ssample022.php on line %d
NULL
Done

sample023.phpt Copy Chapter

.. code:: php

--TEST--
Bug #23894 (sprintf() decimal specifiers problem)
--FILE--

--EXPECTREGEX--
string(4) "-012"
string(8) "2d303132"
(string(13) " 4294967284"|string(20) "18446744073709551604")
(string(26) "20202034323934393637323834"|string(40) "3138343436373434303733373039353531363034")

sample024.phpt Copy Chapter

.. code:: php

--TEST--
DOMDocument::save Test basic function of save method
--SKIPIF--

--FILE--
<?php
$doc = new DOMDocument('1.0');
$doc->formatOutput = true;

$root = $doc->createElement('book');

$root = $doc->appendChild($root);

$title = $doc->createElement('title');
$title = $root->appendChild($title);

$text = $doc->createTextNode('This is the title');
$text = $title->appendChild($text);

$temp_filename = DIR.'/DomDocument_save_basic.tmp';

echo 'Wrote: ' . $doc->save($temp_filename) . ' bytes'; // Wrote: 72 bytes
?>
--CLEAN--

--EXPECTF--
Wrote: 72 bytes

sample025.phpt Copy Chapter

.. code:: php

--TEST--
Test imap_append() function : basic functionality
--SKIPIF--

--FILE--
<?php
/* Prototype : bool imap_append ( resource $imap_stream , string $mailbox , string $message [, string $options ] )
* Description: Append a string message to a specified mailbox.
* Source code: ext/imap/php_imap.c
*/

echo "*** Testing imap_append() : basic functionality ***\n";

require_once(DIR.'/imap_include.inc');

echo "Create a new mailbox for test\n";
$imap_stream = setup_test_mailbox("", 0);
if (!is_resource($imap_stream)) {
exit("TEST FAILED: Unable to create test mailbox\n");
}

$mb_details = imap_mailboxmsginfo($imap_stream);
echo "Add a couple of msgs to new mailbox " . $mb_details->Mailbox . "\n";
var_dump(imap_append($imap_stream, $mb_details->Mailbox
, "From: [email protected]\r\n"
. "To: [email protected]\r\n"
. "Subject: Test message\r\n"
. "\r\n"
. "this is a test message, please ignore\r\n"
));

var_dump(imap_append($imap_stream, $mb_details->Mailbox
, "From: [email protected]\r\n"
. "To: [email protected]\r\n"
. "Subject: Another test\r\n"
. "\r\n"
. "this is another test message, please ignore it too!!\r\n"
));

$check = imap_check($imap_stream);
echo "Msg Count after append : ". $check->Nmsgs . "\n";

echo "List the msg headers\n";
var_dump(imap_headers($imap_stream));

imap_close($imap_stream);
?>
--CLEAN--

--EXPECTF--
*** Testing imap_append() : basic functionality ***
Create a new mailbox for test
Create a temporary mailbox and add 0 msgs
.. mailbox '%s' created
Add a couple of msgs to new mailbox {%s}INBOX.%s
bool(true)
bool(true)
Msg Count after append : 2
List the msg headers
array(2) {
[0]=>
string(%d) "%w%s 1)%s webmaster@something. Test message (%d chars)"
[1]=>
string(%d) "%w%s 2)%s webmaster@something. Another test (%d chars)"
}

sample026.phpt Copy Chapter

.. code:: php

--TEST--
SPL: ArrayIterator implementing RecursiveIterator
--FILE--
<?php

$array = array(1, 2 => array(21, 22 => array(221, 222), 23 => array(231)), 3);

$dir = new RecursiveIteratorIterator(new RecursiveArrayIterator($array), RecursiveIteratorIterator::LEAVES_ONLY);

foreach ($dir as $file) {
print "$file\n";
}

?>
===DONE===

--EXPECT--
1
21
221
222
231
3

skipif2.phpt Copy Chapter

.. code:: php

skipif.phpt Copy Chapter

.. code:: php

xfailif.phpt Copy Chapter

.. code:: php

--TEST--
Handling of errors during linking
--INI--
opcache.enable=1
opcache.enable_cli=1
opcache.optimization_level=-1
opcache.preload={PWD}/preload_inheritance_error_ind.inc
--SKIPIF--

--FILE--

--EXPECTF--
Fatal error: Declaration of B::foo($bar) must be compatible with A::foo() in %spreload_inheritance_error.inc on line 8

Source Core Data Structures Fci Fcc (`docs/source/core/data-structures/fci-fcc.rst`) Copy Section

#######################################################
PHP Callables (zend_fcall_info/zend_fcall_info_cache)
#######################################################

A common pattern for custom behaviour is to accept a user callback. As such we need a way to
represent PHP callables in C. For this purpose there exists two structures zend_fcall_info and
zend_fcall_info_cache. zend_fcall_info_cache is a pure representation of a PHP callable, and
should be the structure used to store PHP callables. zend_fcall_info contains all the required
information to perform a call to a PHP callable. We will use the commonly used abbreviation of FCI
and FCC when talking about zend_fcall_info and zend_fcall_info_cache respectively. The most
likely way to encounter those structs is by using the ZPP f argument specifier.

Generic callable API

There is a set of common parameters used within the callable APIs which are:

.. list-table:: Common callable API parameter meaning
:header-rows: 1

• • Name
  • Type
  • Description
• • fn
  • zend_function*
  • The function pointer to call, usually stored in EG(function_table) for global functions
    or zend_class_entry->function_table for class methods.
• • this_ptr
  • zend_object*
  • Object pointer representing $this.
• • called_scope
  • zend_class_entry*
  • Scope where the method is called, NULL for global functions.
• • retval
  • zval*
  • zval pointer where the return value of the called function will be stored.
• • param_count
  • uint32_t
  • Number of parameters passed to the function via the params argument.
• • params
  • zval*
  • Pointer to a C zval array containing the arguments to the function, may be NULL if
    param_count is 0.

• • named_params

  • HashTable*

  • HashTable containing named argument as name=>val, can also contain positional argument if
    the key is numeric (in which case the positional argument is pushed as the next argument
    regardless of its index)

• • consumed_args
  • uint32_t
  • Arguments consumed by the call. See zend_fcall_info.

There are some functions that do not require the use of either the FCI or the FCC structs:

.. list-table:: Basic callable API
:header-rows: 1

• • Function/Macro
  • Description

• • .. code:: c

    bool zend_is_callable(
    const zval *callable,
    zend_fcall_info_cache *fcc,
    char **error
    
    )

  • Check if the callable zval is a PHP callable. Returns true if it is, false otherwise.
    fcc is an out parameter constructing the FCC struct, see below for details. error
    is an optional out parameter holding the error message if callable is not a PHP
    callable. Note: the signature used to be bool zend_is_callable(zval *callable, uint32_t check_flags, zend_string **callable_name) prior to PHP 8.7.

• • .. code:: c

    bool zend_is_callable_ex(
    zval *callable,
    zend_object *object,
    uint32_t check_flags,
    zend_string **callable_name,
    zend_fcall_info_cache *fcc,
    char **error
    
    )

  • Same as zend_is_callable() with additional arguments. object if callable is a
    string, this zend_object* represents the class instance to check if such a method
    exists. check_flags is a bit mask of IS_CALLABLE_CHECK_SYNTAX_ONLY and
    IS_CALLABLE_SUPPRESS_DEPRECATIONS, generally should be left to 0. callable_name is
    an optional out parameter, it will be set to the string representation of the callable
    zval, set even in case of failure.

• • .. code:: c

    zend_call_known_function(
    zend_function *fn,
    zend_object *this_ptr,
    zend_class_entry *called_scope,
    zval *retval,
    uint32_t param_count,
    zval *params,
    HashTable *named_params
    
    )

  • Call a known function with given parameters. retval may be NULL in which case the
    return value of the function is discarded. If this_ptr is NULL it must be a global
    function or static method. called_scope must not be NULL if fn is a method
    (instanced or static).

• • .. code:: c

    zend_call_known_function_ex(
    zend_function *fn,
    zend_object *this_ptr,
    zend_class_entry *called_scope,
    zval *retval,
    uint32_t param_count,
    zval *params,
    HashTable *named_params
    uint32_t consumed_args
    
    )

  • Same as zend_call_known_function(), with an additional consumed_args parameter (see
    zend_fcall_info).

• • .. code:: c

    zend_call_known_instance_method(
    zend_function *fn,
    zend_object *this_ptr,
    zval *retval,
    uint32_t param_count,
    zval *params
    
    )

  • Same as zend_call_known_function(), where the called_scope is derived from
    this_ptr->ce.

• • .. code:: c

    zend_call_known_instance_method_with_0_params(
    zend_function *fn,
    zend_object *this_ptr,
    zval *retval,
    
    )

  • Helper function around zend_call_known_instance_method().

• • .. code:: c

    zend_call_known_instance_method_with_1_params(
    zend_function *fn,
    zend_object *this_ptr,
    zval *retval,
    zval *param
    
    )

  • Helper function around zend_call_known_instance_method().

• • .. code:: c

    zend_call_known_instance_method_with_2_params(
    zend_function *fn,
    zend_object *this_ptr,
    zval *retval,
    zval *param1,
    zval *param2
    
    )

  • Helper function around zend_call_known_instance_method().

• • .. code:: c

    zend_call_method_if_exists(
    zend_object *this_ptr,
    zend_string *method_name,
    zval *retval,
    uint32_t param_count,
    zval *params
    
    )

  • Returns FAILURE if the method_name does not exists on the object, SUCCESS
    otherwise. The retval will be UNDEF if the return value is ``FAILURE```, as such the
    retval can be unconditionally destroyed. However it may also be UNDEF in an exception was
    thrown.

• • .. code:: c

    call_user_function(
    function_table,
    object,
    function_name,
    retval,
    param_count,
    params
    
    )

  • Deprecated API. Checks that function_name (and optionally object) is a valid PHP
    callable via zend_is_callable_ex() and calls it with the given parameters and return
    value. function_table is ignored and should always be NULL. It is recommended to
    instead use zend_is_callable() to fetch an FCC and call it with
    zend_call_known_fcc(), see below for more details.

• • .. code:: c

    call_user_function_named(
    function_table,
    object,
    function_name,
    retval,
    param_count,
    params,
    named_params
    
    )

  • Deprecated API. Same as call_user_function() with the extra named_params argument.

zend_fcall_info_cache

.. code:: c

typedef struct _zend_fcall_info_cache {
zend_function *function_handler;
zend_class_entry *calling_scope;
zend_class_entry *called_scope;
zend_object object; / Pointer for object representing $this */
zend_object closure; / Closure reference, only if the callable is the object */
} zend_fcall_info_cache;

function_handler:
The actual body of a PHP function that will be used by the VM, can be retrieved from the global
function table or a class function table (zend_class_entry->function_table). May be NULL
for trampolines, see details below.

object:
If the function is an instance object method, this field represents the value of $this. Should
be NULL for static methods and global functions.

called_scope:
The scope in which to call the method, generally it's object->ce.

calling_scope:
The scope in which this call is made, only used by zend_is_callable_ex() to resolve the
actual scope for the deprecated partially supported callables (e.g. [$obj, "parent::method"]). Can be ignored as it is not used when actually calling a function.

closure:
Storage field for the Closure object or the object containing the __invoke() /
__call() / __callStatic() method pointed at in function_handler.

.. note::

Prior to PHP 8.3.0, the FCC did not contain the closure field, and the relevant FCC API
didn't exist.

FCCs are the goto structure to handle and store PHP callables as most of the time they don't need
any reference counting. The one exception is when the FCC represents a trampoline. A trampoline is a
heap-allocated zend_function*, the most common trampolines are calls to a non existing class
method handled by the __call() or __callStatic() magic methods. A trampoline releases the
zend_function* when it is called, as the op array will be consumed. However the f ZPP
argument specifier will free the trampoline and assign NULL to function_handler, making
the FCC uninitialized. The trampoline can be manually fetched by using zend_is_callable() or to
prevent ZPP from freeing it one can use the F argument specifier`. However, in that case careful
consideration need to be done to free the potential trampoline in any failure path, including ZPP
failure.

The only case where an FCC may be uninitialized is if the function is a trampoline, i.e. when the
method of a class does not exist but is handled by the magic methods
__call()/__callStatic(). This is because a trampoline is freed by ZPP as it is a newly
allocated zend_function struct with the op array copied, and is freed when called. To retrieve
it manually use zend_is_callable_ex(). To free a trampoline the void zend_release_fcall_info_cache(zend_fcall_info_cache *fcc) should be used to release it. This
function can be called even if the FCC is not a trampoline. However, if a reference to the closure
is kept, this must be called prior to freeing the closure, as the trampoline will partially
refer to a zend_function * entry in the closure CE.

.. note::

There is investigative work being done to simplify the handling of trampoline in the future.

FCC API

The FCC API is defined in Zend/zend_API.h.

.. list-table:: zend_fcall_info_cache API
:header-rows: 1

• • Function/Macro
  • Description
• • ZEND_FCC_INITIALIZED(fcc)
  • Check if an FCC is initialized.

• • .. code:: c

    zend_fcc_addref(
    zend_fcall_info_cache *fcc
    
    )

  • Adds necessary reference increments and copies to an FCC pointer.

• • .. code:: c

    zend_fcc_dup(
    zend_fcall_info_cache *dest,
    const zend_fcall_info_cache *src,
    
    )

  • Duplicates the source FCC pointer into the destination FCC pointer.

• • zend_fcc_equals(fcc_1, fcc_2)
  • Determines if two FCCs represent the same function.
• • zend_fcc_closure_equals_ex(fcc_1, fcc_2)
  • Determine if both FCCs represent the same function as a Closure may be a
    ZEND_ACC_FAKE_CLOSURE

• • .. code:: c

    zend_fcc_dtor(
    zend_fcall_info_cache *fcc
    
    )

  • Releases data hold by an FCC, including freeing trampolines.

• • zend_get_gc_buffer_add_fcc(gc_buffer, fcc)
  • For use with the get_gc object handler in case the FCC is stored by an internal object.

• • .. code:: c

    zend_call_known_fcc(
    zend_fcall_info_cache *fcc,
    zval *retval,
    uint32_t param_count,
    zval *params,
    HashTable *named_params
    
    )

  • Calls an initialized FCC, all other parameters are optional.

• • zend_get_callable_zval_from_fcc(fcc, callable)
  • Creates a representation of the FCC into the given callable zval*. Note static class
    methods that can be represented as strings or an array pair are returned as an array pair

• • .. code:: c

    zend_release_fcall_info_cache(
    zend_fcall_info_cache *fcc
    
    )

  • Release potential trampoline held by the FCC.

zend_fcall_info

.. code:: c

typedef struct _zend_fcall_info {
size_t size;
zval function_name;
zval *retval;
zval *params;
zend_object object;
uint32_t param_count;
uint32_t consumed_args;
/ This hashtable can also contain positional arguments (with integer keys),
* which will be appended to the normal params[]. This makes it easier to
* integrate APIs like call_user_func_array(). The usual restriction that
* there may not be position arguments after named arguments applies. */
HashTable *named_params;
} zend_fcall_info;

size:
Mandatory field, which is the size of an FCI structure, thus always: sizeof(zend_fcall_info)

function_name:
The actual callable, do not be fooled by the name of this field as this is a leftover when PHP
didn't have objects and class methods. It must be a string zval or an array following the same
rules as callables in PHP, namely the first index is a class or instance object, and the second
one is the method name. If an initialized FCC representing the function exists, it may be
omitted.

object:
Only used for callability checks in conjunction with function_name, see
zend_is_callable_ex() for more details. If an initialized FCC representing the function
exists, it may be omitted.

retval:
Mandatory field, which will contain the result of the PHP function.

param_count:
Mandatory field, the number of arguments that will be provided to this call to the function.

consumed_args:
Specifies positional arguments whose ownership is transfered to the function being called. This
is used as an optimization to avoid an unnecessary Z_ADDREF_P()/zval_ptr_dtor() when the
value is not used after the call. Only one argument can be specified at once with
zend_fci_consumed_arg(n) (zero-based), and the value must not be a reference. Must be set to
0 when no parameter applies. New since PHP 8.6.

params:
contains positional arguments that will be provided to this call to the function. If
param_count = 0, it can be NULL.

named_params:
A HashTable containing named (or positional) arguments.

FCI API

The FCI API is defined in Zend/zend_API.h.

.. list-table:: zend_fcall_info API
:header-rows: 1

• • Function/Macro
  • Description
• • ZEND_FCI_INITIALIZED(fci)
  • Check if an FCI is initialized.

• • zend_call_function(fci, fcc)

  • Calls a function, fcc is a pointer to an FCC that may be NULL, in this case the FCC
    will be derived from the FCI function_name zval, including a callability check. This
    function only returns FAILURE if EG(active) is false during late engine shutdown.
    If the call or call setup throws, EG(exception) will be set and the retval will be UNDEF.
    Otherwise, the retval will be a non-UNDEF value.

• • .. code:: c

    zend_call_function_with_return_value(
    zend_fcall_info *fci,
    zend_fcall_info_cache *fcc,
    zval *retval
    
    )

  • Same as zend_call_function but sets the FCI return value to retval.

• • .. code:: c

    zend_fcall_info_init(
    const zval *callable,
    uint32_t check_flags,
    zend_fcall_info *fci,
    zend_fcall_info_cache *fcc,
    zend_string **callable_name,
    char **error
    
    )

  • Build a FCI/FCC pair from a zval* by forwarding callable, check_flags, fcc,
    callable_name, and error to zend_is_callable_ex(). As such callable_name
    and error are optional and may be NULL. Returns FAILURE if callable is not
    a PHP callable, SUCCESS otherwise.

Deprecated FCI API

There is also a set of FCI API that is now considered deprecated as it is unintuitive and does
unnecessary parameter copying.

In general the IS_ARRAY zval should be assigned to the named_params field of the FCI instead of
copying the arguments.

.. list-table:: Deprecated zend_fcall_info API
:header-rows: 1

• • Function
  • Description

• • .. code:: c

    zend_fcall_info_call(
    zend_fcall_info *fci,
    zend_fcall_info_cache *fcc,
    zval *retval,
    zval *args
    
    )

  • Call a function using information created by zend_fcall_info_init()/args() functions. If
    args is given then those replace the argument info in FCI is temporarily. args must
    be an IS_ARRAY zval. It is recommended to replace calls to this function by
    zend_call_function_with_return_value() and if args is not NULL to set the
    fci.named_params = Z_ARR_P(args);.

• • .. code:: c

    zend_fcall_info_args_clear(
    zend_fcall_info *fci,
    bool free_mem
    
    )

  • Clear arguments connected with the FCI. If free_mem is true then the params array gets
    free'd as well.

• • .. code:: c

    zend_fcall_info_args_save(
    zend_fcall_info *fci,
    uint32_t *param_count,
    zval **params
    
    )

  • Save current arguments from the FCI, the params array will be set to NULL.

• • .. code:: c

    zend_fcall_info_args_restore(
    zend_fcall_info *fci,
    uint32_t param_count,
    zval *params
    
    )

  • Free arguments connected with the FCI, and set back saved ones.

• • .. code:: c

    zend_fcall_info_args(
    zend_fcall_info *fci,
    zval *args
    
    )

  • Sets the arguments in the FCI taking care of refcount. args must be an IS_ARRAY zval.
    If args is NULL the FCI arguments are cleared. It is recommended to migrate away
    from this API by setting fci.named_params=Z_ARR_P(args) and calling
    zend_call_function(fci, NULL).

• • .. code:: c

    zend_fcall_info_args_ex(
    zend_fcall_info *fci,
    zend_function *func,
    zval *args
    
    )

  • Same as zend_fcall_info_args() but if func is not NULL it will check if a
    by-value argument needs to be passed by-ref and wraps it in a reference. This behaviour is
    NON STANDARD PHP behaviour and should never be used.

• • .. code:: c

    zend_fcall_info_argp(
    zend_fcall_info *fci,
    uint32_t argc,
    zval *argv
    
    )

  • Sets the arguments in the FCI taking care of refcount. If argc is 0 the FCI
    arguments are cleared, else pass a variable amount of zval** arguments.

• • .. code:: c

    zend_fcall_info_argv(
    zend_fcall_info *fci,
    uint32_t argc,
    va_list *argv
    
    )

  • Sets the arguments in the FCI taking care of refcount. If argc is 0 the FCI
    arguments are cleared, else pass a variable amount of zval** arguments.

• • .. code:: c

    zend_fcall_info_argn(
    zend_fcall_info *fci,
    uint32_t argc,
    ...
    
    )

  • Sets the arguments in the FCI taking care of refcount. If argc is 0 the FCI
    arguments are cleared, else pass a variable amount of zval** arguments.

Source Core Data Structures Index (`docs/source/core/data-structures/index.rst`) Copy Section

#################
Data structures
#################

.. toctree::
:hidden:

zval
reference-counting
zend_string
zend_constant
fci-fcc

This section provides an overview of the core data structures used in php-src.

Source Core Data Structures Reference Counting (`docs/source/core/data-structures/reference-counting.rst`) Copy Section

####################
Reference counting
####################

In languages like C, when you need memory for storing data for an indefinite period of time or in a
large amount, you call malloc and free to acquire and release blocks of memory of some size.
This sounds simple on the surface but turns out to be quite tricky, mainly because the data may not
be freed for as long as it is used anywhere in the program. Sometimes this makes it unclear who is
responsible for freeing the memory, and when to do so. Failure to handle this correctly may result
in a use-after-free, double-free, or memory leak.

In PHP you usually do not need to think about memory management. The engine takes care of allocating
and freeing memory for you by tracking which values are no longer needed. It does this by assigning
a reference count to each allocated value, often abbreviated as refcount or RC. Whenever a reference
to a value is passed somewhere else, its reference count is increased to indicate the value is now
used by another party. When the party no longer needs the value, it is responsible for decreasing
the reference count. Once the reference count reaches zero, we know the value is no longer needed
anywhere, and that it may be freed.

.. code:: php

$a = new stdClass; // RC 1
$b = $a; // RC 2
unset($a); // RC 1
unset($b); // RC 0, free

Reference counting is needed for types that store auxiliary data, which are the following:

• Strings
• Arrays
• Objects
• References
• Resources

These are either reference types (objects, references and resources) or they are large types that
don't fit in a single zend_value directly (strings, arrays). Simpler types either don't store a
value at all (null, false, true) or their value is small enough to fit directly in
zend_value (int, float).

All of the reference counted types share a common initial struct sequence.

.. code:: c

typedef struct _zend_refcounted_h {
uint32_t refcount; /* reference counter 32-bit */
union {
uint32_t type_info;
} u;
} zend_refcounted_h;

struct _zend_string {
    zend_refcounted_h gc;
    // ...
};

struct _zend_array {
    zend_refcounted_h gc;
    // ...
};

The zend_refcounted_h struct is simple. It contains the reference count, and a type_info
field that repeats some of the type information that is also stored in the zval, for situations
where we're not dealing with a zval directly. It also stores some additional fields, described
under GC flags_.

Macros

As with zval, zend_refcounted_h members should not be accessed directly. Instead, you should
use the provided macros. There are macros that work with reference counted types directly, prefixed
with GC_, or macros that work on zval values, usually prefixed with Z_. Unfortunately,
naming is not always consistent.

.. list-table:: zval macros
:header-rows: 1

• • Macro
  • Non-RC [#non-rc]_
  • Description
• • Z_REFCOUNT[_P]
  • No
  • Returns the reference count.
• • Z_ADDREF[_P]
  • No
  • Increases the reference count.
• • Z_TRY_ADDREF[_P]
  • Yes
  • Increases the reference count. May be called on any zval.
• • zval_ptr_dtor
  • Yes
  • Decreases the reference count and frees the value if the reference count reaches zero.

.. [#non-rc]

Whether the macro works with non-reference counted types. If it does, the operation is usually a
no-op. If it does not, using the macro on these values is undefined behavior.

.. list-table:: zend_refcounted_h macros
:header-rows: 1

• • Macro
  • Immutable [#immutable]_
  • Description
• • GC_REFCOUNT[_P]
  • Yes
  • Returns the reference count.
• • GC_ADDREF[_P]
  • No
  • Increases the reference count.
• • GC_TRY_ADDREF[_P]
  • Yes
  • Increases the reference count.
• • GC_DTOR[_P]
  • Yes
  • Decreases the reference count and frees the value if the reference count reaches zero.

.. [#immutable]

Whether the macro works with immutable types, described under Immutable reference counted types_.

Separation

PHP has value and reference types. Reference types are types that are shared through a reference, a
"pointer" to the value, rather than the value itself. Modifying such a value in one place changes it
for all of its observers. For example, writing to a property changes the property in every place the
object is referenced. Value types, on the other hand, are copied when passed to another party.
Modifying the original value does not affect the copy, and vice versa.

In PHP, arrays and strings are value types. Since they are also reference counted types, this
requires some special care when modifying values. In particular, we need to make sure that modifying
the value is not observable from other places. Modifying a value with RC 1 is unproblematic, since
we are the values sole owner. However, if the value has a reference count of >1, we need to create a
fresh copy before modifying it. This process is called separation or CoW (copy on write).

.. code:: php

$a = [1, 2, 3]; // RC 1
$b = $a; // RC 2
$b[] = 4; // Separation, $a RC 1, $b RC 1
var_dump($a); // [1, 2, 3]
var_dump($b); // [1, 2, 3, 4]

Immutable reference counted types

Sometimes, even a reference counted type is not reference counted. When PHP runs in a multi-process
or multi-threaded environment with opcache enabled, it shares some common values between processes
or threads to reduce memory consumption. As you may know, sharing memory between processes or
threads can be tricky and requires special care when modifying values. In particular, modification
usually requires exclusive access to the memory so that the other processes or threads wait until
the value is done being updated. In this case, this synchronization is avoided by making the value
immutable and never modifying the reference count. Such values will receive the GC_IMMUTABLE
flag in their gc->u.type_info field.

Some macros like GC_TRY_ADDREF will guard against immutable values. You should not use immutable
values on some macros, like GC_ADDREF. This will result in undefined behavior, because the macro
will not check whether the value is immutable before performing the reference count modifications.
You may execute PHP with the -d opcache.protect_memory=1 flag to mark the shared memory as
read-only and trigger a hardware exception if the code accidentally attempts to modify it.

Cycle collector

Sometimes, reference counting is not enough. Consider the following example:

.. code:: php

$a = new stdClass;
$b = new stdClass;
$a->b = $b;
$b->a = $a;
unset($a);
unset($b);

When this code finishes, the reference count of both instances of stdClass will still be 1, as
they reference each other. This is called a reference cycle.

PHP implements a cycle collector that detects such cycles and frees values that are only reachable
through their own references. The cycle collector will record values that may be involved in a
cycle, and run when this buffer becomes full. It is also possible to invoke it explicitly by calling
the gc_collect_cycles() function. The cycle collectors design is described in the Cycle collector <todo>_ chapter.

GC flags

.. code:: c

/* zval_gc_flags(zval.value->gc.u.type_info) (common flags) /
#define GC_NOT_COLLECTABLE (1<<4)
#define GC_PROTECTED (1<<5) / used for recursion detection /
#define GC_IMMUTABLE (1<<6) / can't be changed in place /
#define GC_PERSISTENT (1<<7) / allocated using malloc /
#define GC_PERSISTENT_LOCAL (1<<8) / persistent, but thread-local */

The GC_NOT_COLLECTABLE flag indicates that the value may not be involved in a reference cycle.
This allows for a fast way to detect values that don't need to be added to the cycle collector
buffer. Only arrays and objects may actually be involved in reference cycles.

The GC_PROTECTED flag is used to protect against recursion in various internal functions. For
example, var_dump recursively prints the contents of values, and marks visited values with the
GC_PROTECTED flag. If the value is recursive, it prevents the same value from being visited
again.

GC_IMMUTABLE has been discussed in Immutable reference counted types_.

The GC_PERSISTENT flag indicates that the value was allocated using malloc, instead of PHPs
own allocator. Usually, such values are alive for the entire lifetime of the process, instead of
being freed at the end of the request. See the Zend allocator <todo>_ chapter for more
information.

The GC_PERSISTENT_LOCAL flag indicates that a GC_PERSISTENT value is only accessible in one
thread, and is thus still safe to modify. This flag is only used in debug builds to satisfy an
assert.

Source Core Data Structures Zend Constant (`docs/source/core/data-structures/zend_constant.rst`) Copy Section

###############
zend_constant
###############

PHP constants (referring to non-class constants) are stored in a dedicated structure
zend_constant, which holds both the value of the constant and details for using it.

definition

.. code:: c

typedef struct _zend_constant {
zval value;
zend_string *name;
zend_string *filename;
HashTable *attributes;
} zend_constant;

The value field stores both the value itself and some metadata. The name and filename
store the name of the constant and the name of the file in which it was defined. The attributes
field stores the attributes applied to the constant.

value

The value of the constant is stored in the :doc:./zval value. However, since the zval
structure has extra space, for constants this is used to store both the number of the module that
the constant was defined in, and a combination of the flags that affect the usage of the constant.

This extra information is placed in the uint32_t field value.u2.constant_flags.

The bottom 16 bits are used to hold flags about the constant

.. code:: c

#define CONST_PERSISTENT (1<<0) /* Persistent /
#define CONST_NO_FILE_CACHE (1<<1) / Can't be saved in file cache /
#define CONST_DEPRECATED (1<<2) / Deprecated /
#define CONST_OWNED (1<<3) / constant should be destroyed together
with class */

These bottom 16 bits can be accessed with the ZEND_CONSTANT_FLAGS() macro, which is given a
zend_constant pointer as a parameter.

On the other hand, the top 16 bits are used to store the number of the PHP module that registered
the constant. For constants defined by the user, the module number stored will be
PHP_USER_CONSTANT. This module number can be accessed with the ZEND_CONSTANT_MODULE_NUMBER()
macro, which is likewise given a zend_constant pointer as a parameter.

name

The name holds a :doc:zend_string with the name of the constant, to allow searching for
constants that have already been defined. This string is released when the constant itself is freed.

filename

The filename holds another zend_string with the name of the file in which the constant was
defined, or NULL if not defined userland code. This field provides the foundation for the PHP
method ReflectionConstant::getFileName().

attributes

The attributes holds a HashTable (essentially an array) with the details of the attributes
that were applied to the constant. Note that attributes can only be added to constants declared at
compile time via const, e.g. const EXAMPLE = 123, not those declared at runtime, e.g.
define( 'EXAMPLE', 123 );.

Source Core Data Structures Zend String (`docs/source/core/data-structures/zend_string.rst`) Copy Section

#############
zend_string
#############

In C, strings are represented as sequential lists of characters, char* or char[]. The end of
the string is usually indicated by the special NUL character, '\0'. This comes with a few
significant downsides:

• Calculating the length of the string is expensive, as it requires walking the entire string to
  look for the terminating NUL character.
• The string may not contain the NUL character itself.
• It is easy to run into buffer overflows if the NUL byte is accidentally missing.

php-src uses the zend_string struct as an abstraction over char*, which explicitly stores
the strings length, along with some other fields. It looks as follows:

.. code:: c

struct _zend_string {
zend_refcounted_h gc;
zend_ulong h; /* hash value */
size_t len;
char val[1];
};

The gc field is used for :doc:./reference-counting. The h field contains a hash value,
which is used for hash table <todo>__ lookups. The len field stores the length of the string
in bytes, and the val field contains the actual string data.

You may wonder why the val field is declared as char val[1]. This is called the struct hack_ in C. It is used to create structs with a flexible size, namely by allowing the last element
to be expanded arbitrarily. In this case, the size of zend_string depends on the string's
length, which is determined at runtime (see _ZSTR_STRUCT_SIZE). When allocating the string, we
append enough bytes to the allocation to hold the strings content.

.. _struct hack: https://www.geeksforgeeks.org/struct-hack/

Here's a basic example of how to use zend_string:

.. code:: c

// Allocate the string.
zend_string string = ZSTR_INIT_LITERAL("Hello world!", / persistent */ false);
// Write it to the output buffer.
zend_write(ZSTR_VAL(string), ZSTR_LEN(string));
// Decrease the reference count and free it if necessary.
zend_string_release(string);

ZSTR_INIT_LITERAL creates a zend_string from a string literal. It is just a wrapper around
zend_string_init(char *string, size_t length, bool persistent) that provides the length of the
string at compile time. The persistent parameter indicates whether the string is allocated using
malloc (persistent == true) or emalloc, PHPs custom allocator <todo>__ (persistent == false) that is emptied after each request.

When you're done using the string, you must call zend_string_release, or the memory will leak.
zend_string_release will automatically call malloc or emalloc, depending on how the
string was allocated. After releasing the string, you must not access any of its fields anymore, as
it may have been freed if you were its last user.

API

The string API is defined in Zend/zend_string.h. It provides a number of functions for creating
new strings.

.. list-table:: zend_string creation
:header-rows: 1

• • Function/Macro [#persistent]_
  • Description
• • ZSTR_INIT_LITERAL(s, p)
  • Creates a new string from a string literal.
• • zend_string_init(s, l, p)
  • Creates a new string from a character buffer.
• • zend_string_alloc(l, p)
  • Creates a new string of a given length without initializing its content.
• • zend_string_concat2(s1, l1, s2, l2)
  • Creates a non-persistent string by concatenating two character buffers.
• • zend_string_concat3(...)
  • Same as zend_string_concat2, but for three character buffers.
• • ZSTR_EMPTY_ALLOC()
  • Gets an immutable, empty string. This does not allocate memory.
• • ZSTR_CHAR(char)
  • Gets an immutable, single-character string. This does not allocate memory.

• • ZSTR_KNOWN(ZEND_STR_const)

  • Gets an immutable, predefined string. Used for string common within PHP itself, e.g.
    "class". See ZEND_KNOWN_STRINGS in Zend/zend_string.h. This does not allocate
    memory.

.. [#persistent]

s = zend_string, l = length, p = persistent.

As per php-src fashion, you are not supposed to access the zend_string fields directly. Instead,
use the following macros. There are macros for both zend_string and zvals known to contain
strings.

.. list-table:: Accessor macros
:header-rows: 1

• • zend_string
  • zval
  • Description
• • ZSTR_LEN
  • Z_STRLEN[_P]
  • Returns the length of the string in bytes.
• • ZSTR_VAL
  • Z_STRVAL[_P]
  • Returns the string data as a char*.
• • ZSTR_HASH
  • Z_STRHASH[_P]
  • Computes the string hash if it hasn't already been, and returns it.
• • ZSTR_H
  • -
  • Returns the string hash. This macro assumes that the hash has already been computed.

.. list-table:: Reference counting macros
:header-rows: 1

• • Macro
  • Description
• • zend_string_copy(s)
  • Increases the reference count and returns the same string. The reference count is not
    increased if the string is interned.
• • zend_string_release(s)
  • Decreases the reference count and frees the string if it goes to 0.
• • zend_string_dup(s, p)
  • Creates a true copy of the string in a new allocation, except if the string is interned.
• • zend_string_separate(s)
  • Duplicates the string if the reference count is greater than 1. See
    :doc:./reference-counting for details.

• • zend_string_realloc(s, l, p)

  • Changes the size of the string. If the string has a reference count greater than 1 or if
    the string is interned, a new string is created. You must always use the return value of
    this function, as the original array may have been moved to a new location in memory.

There are various functions to compare strings. The zend_string_equals function compares two
strings in full, while zend_string_starts_with checks whether the first argument starts with the
second. There are variations for _ci and _literal, i.e. case-insensitive comparison and
literal strings, respectively. We won't go over all variations here, as they are straightforward to
use.

Interned strings

Programs use some strings many times. For example, if your program declares a class called
MyClass, it would be wasteful to allocate a new string "MyClass" every time it is referenced
within your program. Instead, when repeated strings are expected, php-src uses a technique called
string interning. Essentially, this is just a simple HashTable <todo>__ where existing interned
strings are stored. When creating a new interned string, php-src first checks the interned string
buffer. If it finds it there, it can return a pointer to the existing string. If it doesn't, it
allocates a new string and adds it to the buffer.

.. code:: c

zend_string str1 = zend_new_interned_string(
ZSTR_INIT_LITERAL("MyClass", / persistent */ false));

// In some other place entirely.
zend_string str2 = zend_new_interned_string(
ZSTR_INIT_LITERAL("MyClass", / persistent */ false));

assert(ZSTR_IS_INTERNED(str1));
assert(ZSTR_IS_INTERNED(str2));
assert(str1 == str2);

Interned strings are not reference counted, as they are expected to live for the entire request,
or longer.

With opcache, this goes one step further by sharing strings across different processes. For example,
if you're using php-fpm with 8 workers, all workers will share the same interned strings buffer. It
gets a bit more complicated. During requests, no interned strings are actually created. Instead,
this is delayed until the script is persisted to shared memory. This means that
zend_new_interned_string may not actually return an interned string if opcache is enabled.
Usually you don't have to worry about this.

Source Core Data Structures Zval (`docs/source/core/data-structures/zval.rst`) Copy Section

zval

PHP is a dynamic language. A variable can typically contain a value of any type, and the type of the
variable may even change during the execution of the program. Under the hood, this is implemented
through the zval struct. It is one of the most important data structures in php-src. It is
implemented as a "tagged union", meaning it stores what type of value it contains, and the value
itself. Let's look at the type first.

zval types

.. code:: c

#define IS_UNDEF 0 /* A variable that was never written to. /
#define IS_NULL 1
#define IS_FALSE 2
#define IS_TRUE 3
#define IS_LONG 4 / An integer value. /
#define IS_DOUBLE 5 / A floating point value. */
#define IS_STRING 6
#define IS_ARRAY 7
#define IS_OBJECT 8
#define IS_RESOURCE 9
#define IS_REFERENCE 10

These simple integer constants determine what value is currently stored in a variable. If you are a
PHP developer, these types should sound fairly familiar. They are pretty much an exact reflection of
the types you may use in regular PHP code. One small oddity is that IS_FALSE and IS_TRUE are
implemented as separate types, instead of as a IS_BOOL type.

Some of these types are self-contained, they don't store any auxiliary data. This includes
IS_UNDEF, IS_NULL, IS_FALSE and IS_TRUE. For the rest of the types, we are going to
require some additional memory to store the actual value of the variable.

zend_value

.. code:: c

typedef union _zend_value {
zend_long lval; /* long value, i.e. int. /
double dval; / double value, i.e. float. */
zend_refcounted *counted;
zend_string *str;
zend_array *arr;
zend_object *obj;
zend_resource *res;
zend_reference *ref;
// Less important for now.
zend_ast_ref *ast;
zval *zv;
void *ptr;
zend_class_entry *ce;
zend_function *func;
struct {
uint32_t w1;
uint32_t w2;
} ww;
} zend_value;

A C union is a data type that may store any one of its members at a time, by being (at least) as big
as its biggest member. For example, zend_value may store the lval member, or the dval
member, but never both at the same time. However, it doesn't know which member is being stored.
Remembering this is our job, and that's exactly what the IS_* constants are for.

The top members of zend_value mostly mirror the IS_* constants, with the exception of
counted. counted polymorphically refers to any reference counted <todo>__ value, including
strings, arrays, objects, resources and references. null and bool are missing from
zend_value because their types are self-contained.

The rest of the fields aren't important for now.

zval

Together, the value and the tag make up the zval, along with some other fields. It may look
intimidating at first. We'll go over it step by step.

.. code:: c

typedef struct _zval_struct zval;

struct _zval_struct {
zend_value value;
union {
uint32_t type_info;
struct {
ZEND_ENDIAN_LOHI_3(
uint8_t type, /* active type /
uint8_t type_flags,
union {
uint16_t extra; / not further specified /
} u)
} v;
} u1;
union {
uint32_t next; / hash collision chain /
uint32_t cache_slot; / cache slot (for RECV_INIT) /
uint32_t opline_num; / opline number (for FAST_CALL) /
uint32_t lineno; / line number (for ast nodes) /
uint32_t num_args; / arguments number for EX(This) /
uint32_t fe_pos; / foreach position /
uint32_t fe_iter_idx; / foreach iterator index /
uint32_t guard; / recursion and single property guard /
uint32_t constant_flags; / constant flags /
uint32_t extra; / not further specified */
} u2;
};

zval.value reserves space for the actual variable data, as discussed above.

zval.u1 stores the variable type, the given IS_* constant, along with some other flags. It's
definition looks a bit complicated. You can think of the entire field as a 4 byte integer, split
into 3 parts. v.type stores the actual variable type, v.type_flags is used for some
reference counting <todo>__ flags, and v.u.extra is pretty much unused.

zval.u2 defines some more storage for various contexts that is often unoccupied. It's there
because the memory would otherwise be wasted due to padding, so we may as well make use of it. We'll
go over the relevant ones in their corresponding chapters.

Macros

The fields in zval should never be accessed directly. Instead, there are a plethora of macros to
access them, concealing some of the implementation details of the zval struct. For many macros,
there's a _P-suffixed variant that performs the same operation on a pointer to the given
zval.

.. list-table:: zval macros
:header-rows: 1

• • Macro
  • Description
• • Z_TYPE[_P]
  • Access the zval.u1.v.type part of the type flags, containing the IS_* type.
• • Z_LVAL[_P]
  • Access the underlying int value.
• • Z_DVAL[_P]
  • Access the underlying float value.
• • Z_STR[_P]
  • Access the underlying zend_string pointer.
• • Z_STRVAL[_P]
  • Access the strings raw char * pointer.
• • Z_STRLEN[_P]
  • Access the strings length.
• • ZVAL_COPY_VALUE(t, s)
  • Copy one zval to another, including type and value.
• • ZVAL_COPY(t, s)
  • Same as ZVAL_COPY_VALUE, but if the value is reference counted, increase the counter.

..
_todo: There are many more.

Other zval types

zval\ s are sometimes used internally with types that don't exist in userland.

.. code:: c

#define IS_CONSTANT_AST 11
#define IS_INDIRECT 12
#define IS_PTR 13
#define IS_ALIAS_PTR 14
#define _IS_ERROR 15

IS_CONSTANT_AST is used to represent constant values (the right hand side of const,
property/parameter initializers, etc.) before they are evaluated. The evaluation of a constant
expression is not always possible during compilation, because they may contain references to values
only available at runtime. Until that evaluation is possible, the constants contain the AST of the
expression rather than the concrete values. Check the parser <todo>__ chapter for more information
on ASTs. When this flag is set, the zval.value.ast union member is set accordingly.

IS_INDIRECT indicates that the zval.value.zv member is populated. This field stores a
pointer to some other zval. This type is mainly used in two situations, namely for intermediate
values between FETCH and ASSIGN instructions, and for the sharing of variables in the symbol
table.

..
_todo: There are many more.

IS_PTR is used for pointers to arbitrary data. Most commonly, this type is used internally for
HashTable, as HashTable may only store zval values. For example, EG(class_table)
represents the class table, which is a hash map of class names to the corresponding
zend_class_entry, representing the class. The same goes for functions and many other data types.
IS_ALIAS_PTR is used for class aliases registered via class_alias. Essentially, it just
allows differencing between members in the class table that are aliases, or actual classes.
Otherwise, it is essentially the same as IS_PTR. Arbitrary data is accessed through
zval.value.ptr, and casted to the correct type depending on context. If ptr stores a class
or function, the zval.value.ce or zval.value.func fields may be used, respectively.

_IS_ERROR is used as an error value for some object handlers <todo>__. It is described in more
detail in its own chapter.

.. code:: c

/* Fake types used only for type hinting.
* These are allowed to overlap with the types below. */
#define IS_CALLABLE 12
#define IS_ITERABLE 13
#define IS_VOID 14
#define IS_STATIC 15
#define IS_MIXED 16
#define IS_NEVER 17

/* used for casts */
#define _IS_BOOL 18
#define _IS_NUMBER 19

These flags are never actually stored in zval.u1. They are used for type hinting and in the
object handler <todo>__ API.

This only leaves the zval.value.ww field. In short, this field is used on 32-bit platforms when
copying data from one zval to another. Normally, zval.value.counted is copied as a generic
value, no matter what the actual underlying type is. zend_value always consists of 8 bytes due
to the double field. Pointers, however, consist only of 4. Because we would otherwise miss the
other 4 bytes, they are copied manually using z->value.ww.w2 = _w2;. This happens in the
ZVAL_COPY_VALUE_EX macro, you won't ever have to care about this.

Source Introduction Ides Index (`docs/source/introduction/ides/index.rst`) Copy Section

IDEs

.. toctree::
:hidden:

visual-studio-code

Here you can find instructions on how to effectively use common IDEs for php-src development.

Source Introduction Ides Visual Studio Code (`docs/source/introduction/ides/visual-studio-code.rst`) Copy Section

####################
Visual Studio Code
####################

.. note::

These instructions have been tested on Linux. macOS should mostly work the same. For Windows,
ymmv.

An IDE can make navigating large code bases tremendously easier. Visual Studio Code is a popular and
free IDE that is well-suited for C development. It contains syntax highlighting, navigation,
auto-completion and a debugger. Check the official website <https://code.visualstudio.com/>__ for
installation instructions.

.. note::

The settings.json file referenced below can be opened in the Settings page by pressing the
"Open Settings (JSON)" button in the top right corner. Most of these settings can also be
adjusted through the GUI.

C/C++ extension

The C/C++ extension_ provides most of the features we'll need for php-src development. You can
find it in the extensions marketplace. You will also need gcc or clang installed. The
extension will mostly work out of the box, but it is advisable to use the compile_commands.json
file. It contains a list of all compiled files, along with the commands used to compile them. It
provides the extension with the necessary information about include paths and other compiler flags.

.. _c/c++ extension: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools

To generate the compile_commands.json file, you can use the compiledb_ tool. Install it using
pip, and then prefix your make command accordingly:

.. _compiledb: https://github.com/nickdiego/compiledb

.. code:: bash

Install compiledb

pip install compiledb

Compile php-src and generate compile_commands.json

compiledb make -j8

To tell the C/C++ extension to use the compile_commands.json file, add the following to your
settings.json file:

.. code:: json

{
"C_Cpp.default.compileCommands": "${workspaceFolder}/compile_commands.json"
}

clangd

The C/C++ extension usually works well enough. Some people find that clangd works better.
clangd is a language server built on top of the clang compiler. It only provides navigation
and code completion but no syntax highlighting and no debugger. As such, it should be used in
conjunction with the C/C++ extension. For the two extensions not to clash, add the following to your
settings.json file:

.. code:: json

{
"C_Cpp.intelliSenseEngine": "disabled"
}

Follow the official installation instructions for clangd <https://clangd.llvm.org/installation.html>_, and then install the clangd extension.
Alternatively, you can let the extension install clangd for you. clangd requires a
compile_commands.json file, so make sure to follow the instructions from the previous section.
By default, clangd will auto-include header files on completion. php-src headers are somewhat
peculiar, so you might want to disable this option in your settings.json file: