Contributions are ready for review

From:	phpdoc at lists dot php dot net	Date:	Mon, 18 Jun 2018 12:00:04 +0000
Subject:	Contributions are ready for review
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969386976@lists.php.net to get a copy of this message

Hello PHP EN Documentation team, There are contributions within the online editor queue for this language. Please review, then commit or delete these patches. Patches for review : ----------------------- New file: en/reference/phpdbg/reference.xml By: Grummfy on 2017-07-06 14:40:49 =================================================================== --- en/reference/phpdbg/reference.xml +++ en/reference/phpdbg/reference.xml @@ -0,0 +1,42 @@ +<?xml version="1.0" encoding="utf-8"?> + + +<reference xml:id="ref.extname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>PHPDbg &Functions;</title> + + + + &reference.phpdbg.entities.functions; + +</reference> + + + => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=74455 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=74455 ------------------------------------------------------------------ New file: en/reference/phpdbg/book.xml By: Grummfy on 2017-07-06 14:46:58 =================================================================== --- en/reference/phpdbg/book.xml +++ en/reference/phpdbg/book.xml @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="utf-8"?> + + +<book xml:id="book.extname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <title>PHPDbg</title> + <titleabbrev>PHPDbg</titleabbrev> + +  + <preface xml:id="intro.extname"> + &reftitle.intro; + <para> + Implemented as a SAPI module, phpdbg can exert complete control over the environment without impacting the functionality or performance of your code. + </para> + </preface> +  + + &reference.phpdbg.setup; + &reference.phpdbg.cli; + &reference.phpdbg.reference; + +</book> + + + => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=74454 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=74454 ------------------------------------------------------------------ New file: en/reference/phpdbg/setup.xml By: Grummfy on 2017-07-06 14:47:12 =================================================================== --- en/reference/phpdbg/setup.xml +++ en/reference/phpdbg/setup.xml @@ -0,0 +1,59 @@ +<?xml version="1.0" encoding="utf-8"?> + + +<chapter xml:id="phpdbg.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + &reftitle.setup; + +  + <section xml:id="phpdbg.requirements"> + &reftitle.required; + &no.requirement; + </section> +  + +  + <section xml:id="phpdbg.installation"> + &reftitle.install; + &no.install; + </section> +  +  + +  + <section xml:id="phpdbg.configuration"> + &reftitle.runtime; + &no.config; + </section> +  +  + +  + <section xml:id="phpdbg.resources"> + &reftitle.resources; + &no.resource; + </section> +  + +</chapter> + + + => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=74456 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=74456 ------------------------------------------------------------------ New file: en/reference/phpdbg/functions/phpdbg-start-oplog.xml By: Grummfy on 2017-07-06 15:13:23 =================================================================== --- en/reference/phpdbg/functions/phpdbg-start-oplog.xml +++ en/reference/phpdbg/functions/phpdbg-start-oplog.xml @@ -0,0 +1,46 @@ +<?xml version="1.0" encoding="utf-8"?> + + +<refentry xml:id="function.phpdbg-start-oplog" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> + <refnamediv> + <refname>phpdbg_start_oplog</refname> + <refpurpose>Start registring code coverage</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <type>void</type><methodname>phpdbg_start_oplog</methodname> + <void/> + </methodsynopsis> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + No return value. + </para> + </refsect1> + +</refentry> + + => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=74458 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=74458 ------------------------------------------------------------------ Modified: en/chapters/intro.xml By: Barb H. on 2017-12-01 18:38:55 =================================================================== --- en/chapters/intro.xml +++ en/chapters/intro.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="utf-8"?> - + <chapter xml:id="introduction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <info><title>Introduction</title></info> @@ -31,39 +31,55 @@ ?> </body> + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> +  + <type>thereturned type</type><methodname>func_name</methodname> +  + <methodparam><type>param1type</type><parameter>firstparameter</parameter></methodparam> +  + <methodparam choice="opt"><type>int</type><parameter role="reference">secondparameter</parameter></methodparam> +  + <void /> + </methodsynopsis> + <para> + The function description goes here. + </para> + </refsect1> </html> ]]> </programlisting> </example> </para> <para> - Instead of lots of commands to output HTML (as seen in C or Perl), + Rather than require a lot of commands to output HTML (as seen in C or Perl), PHP pages contain HTML with embedded code that does "something" (in this case, output "Hi, I'm a PHP script!"). The PHP code is enclosed in special <link linkend="language.basic-syntax.phpmode">start and end processing instructions <code><?php</code> and <code>?></code></link> - that allow you to jump into and out of "PHP mode." + that allow you to jump in and out of "PHP mode." </para> <para> What distinguishes PHP from something like client-side JavaScript is that the code is executed on the server, generating HTML which - is then sent to the client. The client would receive + is then sent to the client. The client receives the results of running that script, but would not know what the underlying code was. You can even configure your web server - to process all your HTML files with PHP, and then there's really no + to process all your HTML files with PHP, so there's really no way that users can tell what you have up your sleeve. </para> <para> - The best things in using PHP are that it is extremely simple + The best thing about using PHP is that it is extremely simple for a newcomer, but offers many advanced features for - a professional programmer. Don't be afraid reading the long - list of PHP's features. You can jump in, in a short time, and + a professional programmer. Don't be afraid to read the long + list of PHP's features. You can jump in and start writing simple scripts in a few hours. </para> <para> Although PHP's development is focused on server-side scripting, - you can do much more with it. Read on, and see more in the + you can do much more with it. To find out how much more, read the <link linkend="intro-whatcando">What can PHP do?</link> section, or go right to the <link linkend="tutorial">introductory tutorial</link> if you are only interested in web programming. @@ -74,81 +90,93 @@ <info><title>What can PHP do?</title></info> <para> Anything. PHP is mainly focused on server-side scripting, - so you can do anything any other CGI program can do, such + so you can do the same things any other CGI program can do, such as collect form data, generate dynamic page content, or - send and receive cookies. But PHP can do much more. + send and receive cookies. And PHP can do much more. </para> <para> There are three main areas where PHP scripts are used. <itemizedlist> <listitem> <simpara> - Server-side scripting. This is the most traditional - and main target field for PHP. You need three things - to make this work: the PHP parser (CGI or server - module), a web server and a web browser. You need to - run the web server, with a connected PHP installation. - You can access the PHP program output with a web browser, - viewing the PHP page through the server. All these can - run on your home machine if you are just experimenting - with PHP programming. See the + Server-Side Scripting: This is the most traditional + and main purpose of PHP. You need three pieces + to make this work: a PHP parser (CGI or server + module), a web server, and a web browser. The web server + runs with a connected PHP installation which parses PHP code. + You can see the PHP program output using a web browser + with a URL address to your files on the web server. If you + are just experimenting with PHP programming, all of these + pieces can run on your home machine. See the <link linkend="install">installation instructions</link> section for more information. </simpara> </listitem> <listitem> <simpara> - Command line scripting. You can make a PHP script - to run it without any server or browser. - You only need the PHP parser to use it this way. - This type of usage is ideal for scripts regularly - executed using cron (on *nix or Linux) or Task Scheduler (on + Command Line Scripting: You can run PHP code + without any server or browser. To be used this way, + only the PHP parser is required. + It is ideal for scripts regularly executed + using cron (on *nix or Linux) or Task Scheduler (on Windows). These scripts can also be used for simple text processing tasks. See the section about - <link linkend="features.commandline">Command line usage of PHP</link> + <link linkend="features.commandline">command line usage of PHP</link> for more information. </simpara> </listitem> <listitem> <simpara> - Writing desktop applications. PHP is probably - not the very best language to create a desktop - application with a graphical user interface, but if - you know PHP very well, and would like to use some - advanced PHP features in your client-side applications - you can also use PHP-GTK to write such programs. You also + Writing Desktop Applications: PHP is probably + not the best language to create a desktop + application with a graphical user interface, but the + PHP-GTK extension enables you to do this. As an + extension, it is not included in the main distribution. + If you know PHP very well and would like to use some + advanced PHP features in your client-side applications, + you can use PHP-GTK to write such programs. You also have the ability to write cross-platform applications this - way. PHP-GTK is an extension to PHP, not available in - the main distribution. If you are interested - in PHP-GTK, visit <link xlink:href="&url.php.gtk;">its + way. If you are interested in PHP-GTK, visit + <link xlink:href="&url.php.gtk;">its own website</link>. </simpara> </listitem> </itemizedlist> </para> <para> - PHP can be <link linkend="install">used</link> on all major operating systems, including + PHP can be <link linkend="install">installed</link> on all major operating systems, including Linux, many Unix variants (including HP-UX, Solaris and OpenBSD), - Microsoft Windows, macOS, RISC OS, and probably others. + Microsoft Windows, Mac OS X, RISC OS, and others. PHP also has support for most of the web servers today. This - includes Apache, IIS, and many others. And this includes any + includes Apache, IIS, and many others as well as any web server that can utilize the FastCGI PHP binary, like lighttpd - and nginx. PHP works as either a module, or as a CGI processor. + and nginx. PHP can work either as a module or as a CGI processor. </para> <para> - So with PHP, you have the freedom of choosing an operating - system and a web server. Furthermore, you also have the choice + Not only does PHP offer you the freedom to choose your + operating system and web server, you also have the choice of using procedural programming or object oriented - programming (OOP), or a mixture of them both. - </para> - <para> - With PHP you are not limited to output HTML. PHP's abilities - includes outputting images, PDF files and even Flash movies - (using libswf and Ming) generated on the fly. You can also - output easily any text, such as XHTML and any other XML file. - PHP can autogenerate these files, and save them in the file - system, instead of printing it out, forming a server-side - cache for your dynamic content. + programming (OOP) or even a mixture of both. And your output + is not limited to HTML. PHP can output + images, PDF files and Flash movies, using + libswf and Ming, generated on the fly. + </para> + <para> + PHP has many useful <link linkend="refs.basic.text"> + text processing</link> features including tools for + working with Perl compatible regular expressions (<link + linkend="book.pcre">PCRE</link>) and + <link linkend="refs.xml">parsing and accessing XML</link>. + PHP standardizes all of the XML extensions on the solid + base of <link linkend="book.libxml">libxml2</link>. + The XML feature set of PHP is extended with support for + <link linkend="book.simplexml">SimpleXML</link>, <link + linkend="book.xmlreader">XMLReader</link> and + <link linkend="book.xmlwriter">XMLWriter</link>. + These text processing features enable you to easily + create text-based files such as XHTML and other XML files. + PHP can print them or save them in the file system + forming a server-side cache for your dynamic content. </para> <para> One of the strongest and most significant features in PHP is its @@ -162,37 +190,31 @@ like CouchDB. </para> <para> - PHP also has support for talking to other services using protocols + PHP supports talking to other services using protocols such as LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (on Windows) and countless others. You can also open raw network sockets and interact using any other protocol. PHP has support for the WDDX complex data exchange between virtually all Web programming - languages. Talking about interconnection, PHP has support for + languages. PHP interconnection even offers support for instantiation of Java objects and using them transparently as PHP objects. </para> <para> - PHP has useful <link linkend="refs.basic.text">text processing</link> features, - which includes the Perl compatible regular expressions (<link linkend="book.pcre">PCRE</link>), - and many extensions and tools to <link linkend="refs.xml">parse and access XML documents</link>. - PHP standardizes all of the XML extensions on the solid base of <link linkend="book.libxml">libxml2</link>, - and extends the feature set adding <link linkend="book.simplexml">SimpleXML</link>, - <link linkend="book.xmlreader">XMLReader</link> and <link linkend="book.xmlwriter">XMLWriter</link> support. - </para> - <para> - And many other interesting extensions exist, which are categorized both - <link linkend="extensions">alphabetically</link> and by <link linkend="funcref">category</link>. - And there are additional PECL extensions that may or may not be documented - within the PHP manual itself, like <link xlink:href="&url.xdebug;">XDebug</link>. - </para> - <para> - As you can see this page is not enough to list all - the features and benefits PHP can offer. Read on in - the sections about <link linkend="install">installing - PHP</link>, and see the <link linkend="funcref">function - reference</link> part for explanation of the extensions - mentioned here. + Many other interesting extensions exist in PHP which are categorized both + <link linkend="extensions">alphabetically</link> and by <link linkend="funcref">category</link>. There are additional PECL extensions + that may or may not be documented within the PHP manual itself, like <link xlink:href="&url.xdebug;">XDebug</link>. + </para> + <para> + This page is not enough to list all + the features and benefits PHP offers. Get started by + <link linkend="install">installing + PHP</link>. Read the <link linkend="funcref">function + reference</link> for explanations of the extensions to PHP + mentioned here. With your PHP environment set up, check out + <link linkend="tutorial">a simple tutorial</link> or explore + <link linkend="langref">the language reference</link> section. </para> + </section> </chapter> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=76914 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=76914 ------------------------------------------------------------------ Modified: en/reference/funchand/functions/call-user-func.xml By: anonymous on 2017-12-17 16:19:24 =================================================================== --- en/reference/funchand/functions/call-user-func.xml +++ en/reference/funchand/functions/call-user-func.xml @@ -54,20 +54,21 @@ } $a = 0; +// Warning: Parameter 1 to increment() expected to be a reference, value given in ... call_user_func('increment', $a); -echo $a."n"; +echo "Passed by value: ".$a."n"; // You can use this instead call_user_func_array('increment', array(&$a)); -echo $a."n"; +echo "Passed by reference: ".$a."n"; ?> ]]> </programlisting> &example.outputs; <screen> <![CDATA[ -0 -1 +Passed by value: 0 +Passed by reference: 1 ]]> </screen> </example> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=77526 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=77526 ------------------------------------------------------------------ Modified: en/install/windows/tools.xml By: Dason Woodhouse on 2018-04-18 21:01:27 =================================================================== --- en/install/windows/tools.xml +++ en/install/windows/tools.xml @@ -7,10 +7,12 @@ <sect2> <title>PHP Install Tools</title> <para> -If you want to setup PHP, some common PHP applications and are using IIS, the easiest way is to use Microsoft's Web Platform Installer (WebPI). + If you want to setup PHP and are using IIS, the easiest way is to use <link xlink:href="https://www.microsoft.com/web/downloads/platform.aspx">Microsoft's Web Platform Installer (WebPI)</link>. </para> -<para>XAMPP, WampServer and BitNami will setup PHP applications for use with Apache on Windows.</para> + <para><link xlink:href="https://www.apachefriends.org/index.html">XAMPP</link>, WampServer and BitNami will setup PHP applications for use with Apache on Windows.</para> + + <para>Setting up and configuring Nginx on Windows requires a bit more configuration. See the <link xlink:href="https://www.nginx.com/resources/wiki/start/topics/examples/phpfastcgionwindows/">Nginx documentation</link> for additional setup help.</para> </sect2> </sect1> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=82334 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=82334 ------------------------------------------------------------------ Modified: en/reference/reflection/reflectionfunctionabstract/getstaticvariables.xml By: anonymous on 2018-05-08 12:16:26 =================================================================== --- en/reference/reflection/reflectionfunctionabstract/getstaticvariables.xml +++ en/reference/reflection/reflectionfunctionabstract/getstaticvariables.xml @@ -31,6 +31,13 @@ <para> An <type>array</type> of static variables. </para> + + <caution> + <para> + Parameters inherited from a higher scope passed to a closure by reference will + be references in this array. Altering them may have unintended side-effects. + </para> + </caution> </refsect1> <refsect1 role="seealso"> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=83286 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=83286 ------------------------------------------------------------------ Modified: en/language/oop5/visibility.xml By: rjhdby on 2018-05-17 06:02:53 =================================================================== --- en/language/oop5/visibility.xml +++ en/language/oop5/visibility.xml @@ -8,11 +8,12 @@ <emphasis>protected</emphasis> or <emphasis>private</emphasis>. Class members declared public can be accessed everywhere. Members declared protected can be accessed - only within the class itself and by inheriting and parent - classes. Members declared as private may only be accessed by the + only within the class itself and by inheriting. + Members declared as private may only be accessed by the class that defines the member. </para> - + <note>You can access protected members of a class or object from inherited methods. + Do <emphasis>NOT</emphasis> rely on this behavior, because it can be changed at any time.</note> <sect2 xml:id="language.oop5.visibility-members"> <title>Property Visibility</title> <para> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=83547 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=83547 ------------------------------------------------------------------ Modified: en/reference/session/functions/session-name.xml By: anonymous on 2018-05-29 05:52:23 =================================================================== --- en/reference/session/functions/session-name.xml +++ en/reference/session/functions/session-name.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="utf-8"?> - + <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-name"> <refnamediv> <refname>session_name</refname> @@ -19,20 +19,21 @@ the <emphasis>old</emphasis> session name. </para> <para> - When new session <parameter>name</parameter> is - supplied, <function>session_name</function> modifies HTTP cookie - (and output contents when <literal>session.transid</literal> is - enabled). Once HTTP cookie is + When a new session <parameter>name</parameter> is + supplied, <function>session_name</function> modifies HTTP cookies + (and output content when <literal>session.transid</literal> is + enabled). Once HTTP cookies are sent, <function>session_name</function> raises error. <function>session_name</function> must be called - before <function>session_start</function> in order session to work + before <function>session_start</function> for the session to work properly. </para> <para> The session name is reset to the default value stored in <literal>session.name</literal> at request startup time. Thus, you need to call <function>session_name</function> for every request (and before - <function>session_start</function> is called). + <function>session_start</function> or <function>session_register</function> + are called). </para> </refsect1> @@ -95,35 +96,6 @@ </para> </refsect1> -<refsect1 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description;</entry> - </row> - </thead> - <tbody> - <row> - <entry>7.2.0</entry> - <entry> - <function>session_name</function> checks session status, - previously it only checked cookie status. Therefore, - older <function>session_name</function> allows to - call <function>session_name</function> - after <function>session_start</function> which may crash PHP - and may result in misbehaviors. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </refsect1> - <refsect1 role="seealso"> &reftitle.seealso; <para> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=83673 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=83673 ------------------------------------------------------------------ Modified: en/install/unix/nginx.xml By: yangbai on 2018-06-08 02:34:57 =================================================================== --- en/install/unix/nginx.xml +++ en/install/unix/nginx.xml @@ -82,7 +82,7 @@ <screen> <![CDATA[ cp php.ini-development /usr/local/php/php.ini -cp /usr/local/etc/php-fpm.conf.default /usr/local/etc/php-fpm.conf +cp /usr/local/etc/php-fpm.d/www.conf.default /usr/local/etc/php-fpm.d/www.conf cp sapi/fpm/php-fpm /usr/local/bin ]]> </screen> @@ -134,7 +134,7 @@ <informalexample xml:id="install.unix.nginx.modify.phpfpm"> <screen> <![CDATA[ -vim /usr/local/etc/php-fpm.conf +vim /usr/local/etc/php-fpm.d/www.conf ]]> </screen> </informalexample> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=83720 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=83720 ------------------------------------------------------------------ Modified: en/reference/strings/functions/ord.xml By: Rowan Collins on 2018-06-10 13:16:44 =================================================================== --- en/reference/strings/functions/ord.xml +++ en/reference/strings/functions/ord.xml @@ -3,7 +3,7 @@ <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.ord"> <refnamediv> <refname>ord</refname> - <refpurpose>Return ASCII value of character</refpurpose> + <refpurpose>Convert the first byte of a string to a value between 0 and 255</refpurpose> </refnamediv> <refsect1 role="description"> @@ -13,8 +13,11 @@ <methodparam><type>string</type><parameter>string</parameter></methodparam> </methodsynopsis> <para> - Returns the ASCII value of the first character of - <parameter>string</parameter>. + Interprets the binary value of the first byte of + <parameter>string</parameter> as an unsigned integer between 0 and 255. + </para> + <para> + If the string is in a single-byte encoding, such as ASCII, ISO-8859, or Windows 1252, this is equivalent to returning the position of a character in the character set's mapping table. However, note that this function is not aware of any string encoding, and in particular will never identify a Unicode code point in a multi-byte encoding such as UTF-8 or UTF-16. </para> <para> This function complements <function>chr</function>. @@ -40,7 +43,7 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - Returns the ASCII value as an integer. + An integer between 0 and 255. </para> </refsect1> @@ -59,7 +62,31 @@ ?> ]]> </programlisting> - </example> + </example> + </para> + <para> + <example> + <title>Examining the individual bytes of a UTF-8 string</title> + <programlisting role="php"> +<![CDATA[ +<?php +declare(encoding='UTF-8'); +$str = "🐘"; +for ( $pos=0; $pos < strlen($str); $pos ++ ) { + $byte = substr($str, $pos); + echo 'Byte ' . $pos . ' of $str has value ' . ord($byte) . PHP_EOL; +} +?> +]]> + </programlisting> + &example.outputs; + <screen> +Byte 0 of $str has value 240 +Byte 1 of $str has value 159 +Byte 2 of $str has value 144 +Byte 3 of $str has value 152 + </screen> + </example> </para> </refsect1> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=83812 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=83812 ------------------------------------------------------------------ Modified: en/reference/strings/functions/chr.xml By: Rowan Collins on 2018-06-10 13:23:56 =================================================================== --- en/reference/strings/functions/chr.xml +++ en/reference/strings/functions/chr.xml @@ -3,18 +3,21 @@ <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.chr"> <refnamediv> <refname>chr</refname> - <refpurpose>Return a specific character</refpurpose> + <refpurpose>Generate a single-byte string from a number</refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; <methodsynopsis> <type>string</type><methodname>chr</methodname> - <methodparam><type>int</type><parameter>ascii</parameter></methodparam> + <methodparam><type>int</type><parameter>bytevalue</parameter></methodparam> </methodsynopsis> <para> Returns a one-character string containing the character specified - by <parameter>ascii</parameter>. + by interpreting <parameter>bytevalue</parameter> as an unsigned integer. + </para> + <para> + This can be used to create a one-character string in a single-byte encoding such as ASCII, ISO-8859, or Windows 1252, by passing the position of a desired character in the encoding's mapping table. However, note that this function is not aware of any string encoding, and in particular cannot be passed a Unicode code point value to generate a string in a multibyte encoding like UTF-8 or UTF-16. </para> <para> This function complements <function>ord</function>. @@ -26,20 +29,20 @@ <para> <variablelist> <varlistentry> - <term><parameter>ascii</parameter></term> + <term><parameter>bytevalue</parameter></term> <listitem> <para> - The extended ASCII code. + An integer between 0 and 255. </para> <para> Values outside the valid range (0..255) will be bitwise and'ed with 255, which is equivalent to the following algorithm: <programlisting role="php"> <![CDATA[ -while ($ascii < 0) { - $ascii += 256; +while ($bytevalue < 0) { + $bytevalue += 256; } -$ascii %= 256; +$bytevalue %= 256; ]]> </programlisting> </para> @@ -52,7 +55,7 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - Returns the specified character. + A single-character string containing the specified byte. </para> </refsect1> <refsect1 role="examples"> @@ -63,6 +66,8 @@ <programlisting role="php"> <![CDATA[ <?php +// Assumes the string will be used as ASCII or an ASCII-compatible encoding + $str = "The string ends in escape: "; $str .= chr(27); /* add an escape character at the end of $str */ @@ -90,6 +95,24 @@ </screen> </example> </para> + <para> + <example> + <title>Building a UTF-8 string from individual bytes</title> + <programlisting role="php"> +<![CDATA[ +<?php +declare(encoding='UTF-8'); +$str = chr(240) . chr(159) . chr(144) . chr(152); +echo $str; +?> +]]> + </programlisting> + &example.outputs; + <screen> +🐘 + </screen> + </example> + </para> </refsect1> <refsect1 role="seealso"> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=83813 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=83813 ------------------------------------------------------------------ Modified: en/reference/mbstring/supported-encodings.xml By: anonymous on 2018-06-17 19:37:55 =================================================================== --- en/reference/mbstring/supported-encodings.xml +++ en/reference/mbstring/supported-encodings.xml @@ -72,7 +72,7 @@ <listitem><simpara>byte4be</simpara></listitem> <listitem><simpara>byte4le</simpara></listitem> <listitem><simpara>BASE64</simpara></listitem> - <listitem><simpara>HTML-ENTITIES</simpara></listitem> + <listitem><simpara>HTML-ENTITIES (alias: HTML)</simpara></listitem> <listitem><simpara>7bit</simpara></listitem> <listitem><simpara>8bit</simpara></listitem> <listitem><simpara>EUC-CN*</simpara></listitem> @@ -83,14 +83,14 @@ <listitem><simpara>CP950</simpara></listitem> <listitem><simpara>BIG-5*</simpara></listitem> <listitem><simpara>EUC-KR*</simpara></listitem> - <listitem><simpara>UHC (CP949)</simpara></listitem> + <listitem><simpara>UHC (alias: CP949)</simpara></listitem> <listitem><simpara>ISO-2022-KR</simpara></listitem> - <listitem><simpara>Windows-1251 (CP1251)</simpara></listitem> - <listitem><simpara>Windows-1252 (CP1252)</simpara></listitem> - <listitem><simpara>CP866 (IBM866)</simpara></listitem> + <listitem><simpara>Windows-1251 (alias: CP1251)</simpara></listitem> + <listitem><simpara>Windows-1252 (alias: CP1252)</simpara></listitem> + <listitem><simpara>CP866 (alias: IBM866)</simpara></listitem> <listitem><simpara>KOI8-R*</simpara></listitem> <listitem><simpara>KOI8-U*</simpara></listitem> - <listitem><simpara>ArmSCII-8 (ArmSCII8)</simpara></listitem> + <listitem><simpara>ArmSCII-8 (alias: ArmSCII8)</simpara></listitem> </itemizedlist> <para> * denotes encodings usable also in regular expressions. => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=83951 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=83951 ------------------------------------------------------------------ -- https://edit.php.net/ This email is send automatically by the Php Docbook Online Editor.