xref: /PHP-7.1/UPGRADING.INTERNALS (revision 03f3b847)
1PHP 7.1 INTERNALS UPGRADE NOTES
2
30. Wiki Examples
41. Internal API changes
5  e. Codepage handling on Windows
6  f. Path handling on Windows
7  g. SAPI logging
8
92. Build system changes
10  a. Unix build system changes
11  b. Windows build system changes
12
133. Module changes
14
15================
160. Wiki Examples
17================
18
19The wiki contains multiple examples and further explanations of the internal
20changes. See: https://wiki.php.net/phpng-upgrading
21
22
23========================
241. Internal API changes
25========================
26
27  e. Codepage handling on Windows
28
29    A set of new APIs was introduced, which allows to handle codepage
30    conversions. The corresponding prototypes and macros are contained
31    in win32/codepage.h.
32
33    Functions with php_win32_cp_* signatures provide handling for various
34    codepage aspects. Primarily they are in use at various places in the
35    I/O utils code and directly in the core where necessary, providing
36    conversions to/from UTF-16. Arbitrary conversions between codepages
37    are possible as well, whereby UTF-16 will be always an intermediate
38    state in this case.
39
40    For input length arguments, the macro PHP_WIN32_CP_IGNORE_LEN can be
41    passed, then the API will calculate the length.  For output length
42    arguments, the macro PHP_WIN32_CP_IGNORE_LEN_P can be passed, then
43    the API won't set the output length.
44
45    The mapping between encodings and codepages is provided by the predefined
46    array of data contained in win32/cp_enc_map.c. To change the data,
47    a generator win32/cp_enc_map_gen.c needs to be edited and run.
48
49  f. Path handling on Windows
50
51    A set of new APIs was introduced, which allows to handle UTF-8 paths. The
52    corresponding prototypes and macros are contained in win32/ioutil.h.
53
54    Functions with php_win32_ioutil_* signatures provide POSIX I/O analogues.
55    These functions are integrated in various places across the code base to
56    support Unicode filenames. While accepting char * arguments, internally
57    the conversion to wchar_t * happens. Internally almost no ANSI APIs are
58    used, but directly their wide equivalents. The string conversion rules
59    correspond to those already present in the core and depend on the current
60    encoding settings. Doing so allows to move away from the ANSI Windows API
61    with its dependency on the system OEM/ANSI codepage.
62
63    Thanks to the wide API usage, the long paths are now supported as well. The
64    PHP_WIN32_IOUTIL_MAXPATHLEN macro is defined to 2048 bytes and will override
65    the MAXPATHLEN in files where the header is included.
66
67    The most optimal use case for scripts is utilizing UTF-8 for any I/O
68    related functions. UTF-8 filenames are supported on any system disregarding
69    the system OEM/ANSI codepage.
70
71  g. SAPI logging
72    The log_message callback in the SAPI struct was extended with the severity
73    argument. This allows SAPI modules to implement mapping between PHP and
74    corresponding server error levels. A reference mapping implementation
75    can be found in apache2handler.
76
77
78========================
792. Build system changes
80========================
81
82  a. Unix build system changes
83
84  b. Windows build system changes
85    Static analysis with clang and Cppcheck is supported by passing "clang" or
86    "cppcheck" keyword to the --with-analyzer configure option.
87
88========================
893. Module changes
90========================
91