cvs: /phpdoc/chapters security.sgml /phpdoc Makefile.in chapters.ent manual.sgml preface.sgml /phpdoc/chapters install.sgml /phpdoc/language
functions.sgml

jim Mon Jul 12 20:18:44 1999 EDT Added files: /phpdoc/chapters security.sgml Modified files: /phpdoc Makefile.in chapters.ent manual.sgml preface.sgml /phpdoc/chapters install.sgml /phpdoc/language functions.sgml Log: Move Security stuff into its own chapter. Some cleanups to the Functions chapter. Index: phpdoc/Makefile.in diff -u phpdoc/Makefile.in:1.12 phpdoc/Makefile.in:1.13 --- phpdoc/Makefile.in:1.12 Mon Jul 12 20:00:15 1999 +++ phpdoc/Makefile.in Mon Jul 12 20:18:43 1999 @@ -26,7 +26,7 @@ # +----------------------------------------------------------------------+ # -# $Id: Makefile.in,v 1.12 1999/07/13 00:00:15 jim Exp $ +# $Id: Makefile.in,v 1.13 1999/07/13 00:18:43 jim Exp $ # VPATH=@srcdir@ @@ -56,6 +56,7 @@ chapters/intro.sgml \ chapters/config.sgml \ chapters/install.sgml \ + chapters/security.sgml \ features/connection-handling.sgml \ features/file-upload.sgml \ features/cookies.sgml \ Index: phpdoc/chapters.ent diff -u phpdoc/chapters.ent:1.6 phpdoc/chapters.ent:1.7 --- phpdoc/chapters.ent:1.6 Sun Jun 27 22:25:19 1999 +++ phpdoc/chapters.ent Mon Jul 12 20:18:43 1999 @@ -5,6 +5,7 @@ <!ENTITY chapter.introduction SYSTEM "chapters/intro.sgml"> <!ENTITY chapter.install SYSTEM "chapters/install.sgml"> <!ENTITY chapter.config SYSTEM "chapters/config.sgml"> +<!ENTITY chapter.security SYSTEM "chapters/security.sgml"> <!ENTITY features.http-auth SYSTEM "features/http-auth.sgml"> <!ENTITY features.cookies SYSTEM "features/cookies.sgml"> Index: phpdoc/manual.sgml diff -u phpdoc/manual.sgml:1.9 phpdoc/manual.sgml:1.10 --- phpdoc/manual.sgml:1.9 Mon Jul 12 17:29:59 1999 +++ phpdoc/manual.sgml Mon Jul 12 20:18:43 1999 @@ -25,6 +25,7 @@ &chapter.introduction; &chapter.install; &chapter.config; + &chapter.security; </part> <part id="langref"> Index: phpdoc/preface.sgml diff -u phpdoc/preface.sgml:1.2 phpdoc/preface.sgml:1.3 --- phpdoc/preface.sgml:1.2 Sun Jun 27 22:53:09 1999 +++ phpdoc/preface.sgml Mon Jul 12 20:18:43 1999 @@ -8,9 +8,6 @@ unique PHP-specific features thrown in. The goal of the language is to allow web developers to write dynamically generated pages quickly. - <!-- undefined but referenced labels: --> - <anchor id="security"> - </simpara> </abstract> Index: phpdoc/chapters/install.sgml diff -u phpdoc/chapters/install.sgml:1.6 phpdoc/chapters/install.sgml:1.7 --- phpdoc/chapters/install.sgml:1.6 Thu Jun 24 08:39:48 1999 +++ phpdoc/chapters/install.sgml Mon Jul 12 20:18:43 1999 @@ -140,7 +140,7 @@ generally go for that solution for performance reasons. However, the CGI version enables Apache users to run different PHP-enabled pages under different user-ids. Please make sure - you read through the <link linkend="config-security">Security + you read through the <link linkend="security">Security chapter</link> if you are going to run PHP as a CGI. <sect2> @@ -536,7 +536,7 @@ Enables "safe mode" by default. This imposes several restrictions on what PHP can do, such as opening only files within the document root. Read the <link - linkend="config-security">Security chapter</link> for more more + linkend="security">Security chapter</link> for more more information. CGI users should always enable secure mode. This option only sets the default, it may be enabled or disabled with the <link linkend="ini.safe-mode">safe_mode</link> directive in @@ -596,7 +596,7 @@ If this is enabled, the PHP CGI binary can safely be placed outside of the web tree and people will not be able to circumvent .htaccess security. Read the <link - linkend="config-security-cgi-shell">section in the security + linkend="security.cgi.shell">section in the security chapter</link> about this option. </sect3> @@ -641,7 +641,7 @@ user directories may be accessed by anyone. <simpara> - Read the <link linkend="config-security-cgi-force">section in + Read the <link linkend="security.cgi.force-redirect">section in the security chapter</link> about this option. </sect3> @@ -1282,18 +1282,6 @@ preferably enough code to make others able to reproduce and test your problem. - <sect1 id="install-security"> - <title>Security</title> - - <simpara> - PHP is a powerful tool. As with many other powerful tools, it is - possible to shoot yourself in the foot with it. PHP has - functionality that, if carelessly used, may cause security - problems on your system. The best way of preventing this is to - always know what you are doing. Read the <link - linkend="config-security">Security chapter</link> for more - information. - </chapter> <!-- Keep this comment at the end of the file Index: phpdoc/language/functions.sgml diff -u phpdoc/language/functions.sgml:1.1 phpdoc/language/functions.sgml:1.2 --- phpdoc/language/functions.sgml:1.1 Sun Jun 27 22:25:20 1999 +++ phpdoc/language/functions.sgml Mon Jul 12 20:18:43 1999 @@ -24,91 +24,91 @@ <simpara> Functions must be defined before they are referenced. - <sect1 id="functions.returning-values"> - <title>Returning values</title> + <sect1 id="functions.returning-values"> + <title>Returning values</title> - <para> - Values are returned by using the optional return statement. Any - type may be returned, including lists and objects. + <para> + Values are returned by using the optional return statement. Any + type may be returned, including lists and objects. - <informalexample> - <programlisting> + <informalexample> + <programlisting> function square ($num) { return $num * $num; } echo square (4); // outputs '16'. - </programlisting> - </informalexample> + </programlisting> + </informalexample> - <para> - You can't return multiple values from a function, but similar - results can be obtained by returning a list. + <para> + You can't return multiple values from a function, but similar + results can be obtained by returning a list. - <informalexample> - <programlisting> + <informalexample> + <programlisting> function small_numbers() { return array (0, 1, 2); } list ($zero, $one, $two) = small_numbers(); </programlisting> - </informalexample> + </informalexample> - <sect2 id="functions.arguments"> - <title>Function arguments</title> + <sect1 id="functions.arguments"> + <title>Function arguments</title> - <simpara> - Information may be passed to functions via the argument list, - which is a comma-delimited list of variables and/or constants. + <simpara> + Information may be passed to functions via the argument list, + which is a comma-delimited list of variables and/or constants. + + <para> + PHP supports passing arguments by value (the default), <link + linkend="functions.arguments.by-reference">passing by + reference</link>, and <link + linkend="functions.arguments.default">default argument + values</link>. Variable-length argument lists are not supported, + but a similar effect may be obtained by passing arrays. - <para> - PHP supports passing arguments by value (the default), <link - linkend="functions.arguments.by-reference">passing by - reference</link>, and <link - linkend="functions.arguments.default">default argument - values</link>. Variable-length argument lists are not supported, - but a similar effect may be obtained by passing arrays. - - <informalexample> - <programlisting> + <informalexample> + <programlisting> function takes_array($input) { echo "$input[0] + $input[1] = ", $input[0]+$input[1]; } - </programlisting> - </informalexample> + </programlisting> + </informalexample> - <sect3 id="functions.arguments.by-reference"> - <title>Making arguments be passed by reference</title> + <sect2 id="functions.arguments.by-reference"> + <title>Making arguments be passed by reference</title> - <simpara> - By default, function arguments are passed by value (so that - if you change the value of the argument within the function, - it does not get changed outside of the function). If you wish - to allow a function to modify its arguments, you must pass them - by reference. + <simpara> + By default, function arguments are passed by value (so that + if you change the value of the argument within the function, + it does not get changed outside of the function). If you wish + to allow a function to modify its arguments, you must pass them + by reference. - <para> - If you want an argument to a function to always be passed by - reference, you can prepend an ampersand (&amp;) to the argument - name in the function definition: + <para> + If you want an argument to a function to always be passed by + reference, you can prepend an ampersand (&amp;) to the argument + name in the function definition: - <informalexample> - <programlisting> + <informalexample> + <programlisting> function add_some_extra(&amp;$string) { $string .= 'and something extra.'; } - $str = 'This is a string, '; - add_some_extra($str); - echo $str; // outputs 'This is a string, and something extra.' - </programlisting> - </informalexample> - - <para> - If you wish to pass a variable by reference to a function which - does not do this by default, you may prepend an ampersand to the - argument name in the function call: +$str = 'This is a string, '; +add_some_extra($str); +echo $str; // outputs 'This is a string, and something extra.' + </programlisting> + </informalexample> + + <para> + If you wish to pass a variable by reference to a function which + does not do this by default, you may prepend an ampersand to the + argument name in the function call: - <informalexample> - <programlisting> + <informalexample> + <programlisting> function foo ($bar) { $bar .= ' and something extra.'; } @@ -117,82 +117,82 @@ echo $str; // outputs 'This is a string, ' foo (&amp;$str); echo $str; // outputs 'This is a string, and something extra.' - </programlisting> - </informalexample> + </programlisting> + </informalexample> - <sect3 id="functions.arguments.default"> - <title>Default argument values</title> + <sect2 id="functions.arguments.default"> + <title>Default argument values</title> - <para> - A function may define C++-style default values for scalar - arguments as follows: + <para> + A function may define C++-style default values for scalar + arguments as follows: - <informalexample> - <programlisting> + <informalexample> + <programlisting> function makecoffee ($type = "cappucino") { return "Making a cup of $type.\n"; } echo makecoffee (); echo makecoffee ("espresso"); - </programlisting> - </informalexample> + </programlisting> + </informalexample> - <para> - The output from the above snippet is: + <para> + The output from the above snippet is: - <screen> + <screen> Making a cup of cappucino. Making a cup of espresso. - </screen> + </screen> - <simpara> - The default value must be a constant expression, not (for - example) a variable or class member. - - <para> - Note that when using default arguments, any defaults should be - on the right side of any non-default arguments; otherwise, - things will not work as expected. Consider the following code - snippet: + <simpara> + The default value must be a constant expression, not (for + example) a variable or class member. + + <para> + Note that when using default arguments, any defaults should be + on the right side of any non-default arguments; otherwise, + things will not work as expected. Consider the following code + snippet: - <informalexample> - <programlisting> + <informalexample> + <programlisting> function makeyogurt ($type = "acidophilus", $flavour) { return "Making a bowl of $type $flavour.\n"; } echo makeyogurt ("raspberry"); // won't work as expected - </programlisting> - </informalexample> + </programlisting> + </informalexample> - <para> - The output of the above example is: + <para> + The output of the above example is: - <screen> + <screen> Warning: Missing argument 2 in call to makeyogurt() in /usr/local/etc/httpd/htdocs/php3test/functest.html on line 41 Making a bowl of raspberry . - </screen> + </screen> - <para> - Now, compare the above with this: + <para> + Now, compare the above with this: - <informalexample> - <programlisting> + <informalexample> + <programlisting> function makeyogurt ($flavour, $type = "acidophilus") { return "Making a bowl of $type $flavour.\n"; } echo makeyogurt ("raspberry"); // works as expected - </programlisting> - </informalexample> + </programlisting> + </informalexample> - <para> - The output of this example is: + <para> + The output of this example is: - <screen> + <screen> Making a bowl of acidophilus raspberry. - </screen> + </screen> <sect1 id="functions.old-syntax"> <title><literal>old_function</literal></title>