cvs: phpdoc /en/appendices aliases.xml migration.xml migration4.xml phpdevel.xml reserved.constants.core.xml reserved.constants.standard.xml
resources.xml tokens.xml

nicos Wed Nov 20 08:11:20 2002 EDT Modified files: /phpdoc/en/appendices aliases.xml migration.xml migration4.xml phpdevel.xml reserved.constants.core.xml reserved.constants.standard.xml resources.xml tokens.xml Log: fixing

Index: phpdoc/en/appendices/aliases.xml diff -u phpdoc/en/appendices/aliases.xml:1.22 phpdoc/en/appendices/aliases.xml:1.23 --- phpdoc/en/appendices/aliases.xml:1.22 Mon Nov 18 13:28:48 2002 +++ phpdoc/en/appendices/aliases.xml Wed Nov 20 08:11:20 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.22 $ --> +<!-- $Revision: 1.23 $ --> <appendix id="aliases"> <title>List of Function Aliases</title> <para> @@ -14,8 +14,7 @@ <function>is_integer</function> are equally good) </para> <para> - This list is consistent with PHP 4.0.6. For an alias list that - updates daily, have a look <ulink url="&url.zend.aliaslist;">here</ulink>. + This list is consistent with PHP 4.0.6. </para> <para> <table> Index: phpdoc/en/appendices/migration.xml diff -u phpdoc/en/appendices/migration.xml:1.20 phpdoc/en/appendices/migration.xml:1.21 --- phpdoc/en/appendices/migration.xml:1.20 Wed Nov 20 07:19:11 2002 +++ phpdoc/en/appendices/migration.xml Wed Nov 20 08:11:20 2002 @@ -1,94 +1,95 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.20 $ --> +<!-- $Revision: 1.21 $ --> <appendix id="migration"> - <title>Mirgrando do PHP/FI para o PHP 3</title> + <title>Migrating from PHP/FI 2 to PHP 3</title> <section id="migration.about"> - <title>Sobre as incompatibilidades do 3.0</title> + <title>About the incompatibilities in 3.0</title> <simpara> - PHP 3.0 foi totalmente reescrito. Ele tem um parser apropriado - que &eacute; muito mais robusto e consistente que o da vers&atilde;o 2.0. 3.0 - &eacute; tamb&eacute;m significamente mais r&aacute;pido, e usa menos mem&oacute;ria. Entretanto - algumas dessas melhorias n&atilde;o seriam poss&iacute;veis sem mudan&ccedil;as na compatibilidade, - na sintaxe e na funcionalidade. + PHP 3.0 is rewritten from the ground up. It has a proper parser + that is much more robust and consistent than 2.0's. 3.0 is also + significantly faster, and uses less memory. However, some of + these improvements have not been possible without compatibility + changes, both in syntax and functionality. </simpara> <simpara> - Al&eacute;m do mais, os desenvolvedores do PHP tentaram limpar ambas - sintaxe e sem&acirc;nticas da vers&atilde;o 3.0 do PHP, e isto tamb&eacute;m traz algumas - incompatbilidades. A longo prazo, n&oacute;s acreditamos que estas mudan&ccedil;as - s&atilde;o para melhor. + In addition, PHP's developers have tried to clean up both PHP's + syntax and semantics in version 3.0, and this has also caused some + incompatibilities. In the long run, we believe that these changes + are for the better. </simpara> <simpara> - Este cap&iacute;tulo tentar&aacute; guiar voc&ecirc; com as incompatibilidades que voc&ecirc; - encontrar&aacute; quando estiver migrando do PHP/FI 2.0 para o PHP 3.0 e - ajudar&aacute; a resolver elas. Novas caracter&iacute;sticas n&atilde;o s&atilde;o mencionadas aqui - a menos que seja necess&aacute;rio. + This chapter will try to guide you through the incompatibilities + you might run into when going from PHP/FI 2.0 to PHP 3.0 and help + you resolve them. New features are not mentioned here unless + necessary. </simpara> <simpara> - Um programa que converte automaticamente seus scripts em PHP/FI 2.0 existe. - Ele pode ser encontrado no subdiret&oacute;rio <filename class="directory">convertor</filename> - da distribui&ccedil;&atilde;o do PHP 3.0. Este programa apenas capta altera&ccedil;&otilde;es de sintaxe, - portanto voc&ecirc; deve ler atentamente este cap&iacute;tulo. + A conversion program that can automatically convert your old + PHP/FI 2.0 scripts exists. It can be found in the + <filename class="directory">convertor</filename> subdirectory of the PHP 3.0 + distribution. This program only catches the syntax changes though, + so you should read this chapter carefully anyway. </simpara> </section> <section id="migration.startendtags"> - <title>Tags de Come&ccedil;o/fim</title> + <title>Start/end tags</title> <para> - A primeira coisa que voc&ecirc; provavelmente ir&aacute; reparar &eacute; que as tags de - come&ccedil;o e fim do PHP mudaram. O velho foi <literal>&lt;? &gt;</literal> - modificado para tr&ecirc;s formas poss&iacute;veis: + The first thing you probably will notice is that PHP's start and end + tags have changed. The old <literal>&lt;? &gt;</literal> form has been + replaced by three new possible forms: <example> - <title>Migrando: da velha tag come&ccedil;o/fim</title> + <title>Migration: old start/end tags</title> <programlisting role="php"> <![CDATA[ -<? echo "Este &eacute; um c&oacute;digo em PHP/FI 2.0.\n"; > +<? echo "This is PHP/FI 2.0 code.\n"; ?> ]]> </programlisting> </example> - Como na vers&atilde;o 2.0, PHP/FI tamb&eacute;m suporta esta varia&ccedil;&atilde;o: + As of version 2.0, PHP/FI also supports this variation: <example> - <title>Migrando: primeira forma das tags come&ccedil;o/fim</title> + <title>Migration: first new start/end tags</title> <programlisting role="php"> <![CDATA[ -<? echo "Este &eacute; um c&oacute;digo em PHP 3.0!\n"; ?> +<? echo "This is PHP 3.0 code!\n"; ?> ]]> </programlisting> </example> - Repare que a tag de fechamento agora consiste em um sinal de interroga&ccedil;&atilde;o e uma - tag de fechamento e n&atilde;o apenas em uma tag de fechamento. Entretanto, se - voc&ecirc; planeja usar XML no seu servidor, voc&ecirc; obeter&aacute; alguns problemas com a - nova varia&ccedil;&atilde;o, porque o PHP pode tentar executar as tags de marca&ccedil;&atilde;o dos - documentos em XML como c&oacute;digos PHP. Por causa disto, a seguinte modifica&ccedil;&atilde;o - foi adicionada: + Notice that the end tag now consists of a question mark and a + greater-than character instead of just greater-than. However, if + you plan on using XML on your server, you will get problems with + the first new variant, because PHP may try to execute the XML + markup in XML documents as PHP code. Because of this, the + following variation was introduced: <example> - <title>Migrando: segunda forma das tags come&ccedil;o/fim</title> + <title>Migration: second new start/end tags</title> <programlisting role="php"> <![CDATA[ -<?php echo "Este &eacute; um c&oacute;digo em PHP 3.0!\n"; ?> +<?php echo "This is PHP 3.0 code!\n"; ?> ]]> </programlisting> </example> - Algumas pessoas obtiveram problemas com editores que n&atilde;o entendem - todas as tags de processamento. O Microsoft Frontpage &eacute; um destes editores, - e pensando nestes editores, foi adicionado mais uma modifica&ccedil;&atilde;o que &eacute; mostrada - abaixo: + Some people have had problems with editors that don't understand + the processing instruction tags at all. Microsoft FrontPage is one + such editor, and as a workaround for these, the following variation + was introduced as well: <example> - <title>Migrando: terceira forma das tags come&ccedil;o/fim</title> + <title>Migration: third new start/end tags</title> <programlisting role="php"> <![CDATA[ <script language="php"> - echo "Este &eacute; um c&oacute;digo em PHP 3.0!\n"; + echo "This is PHP 3.0 code!\n"; </script> ]]> @@ -98,66 +99,67 @@ </section> <section id="migration.if-endif"> - <title>sintaxe if..endif</title> + <title>if..endif syntax</title> <para> - A maneira 'alternativa' de escrever as instru&ccedil;&otilde;es if/elseif/else , usando if(); - elseif(); else; endif; n&atilde;o puderam ser eficientemente implementadas sem adicionar - uma quantidade grande de complexidade ao parser 3.0. Por causa disso, a sintaxe foi - alterada para: + The `alternative' way to write if/elseif/else statements, using if(); + elseif(); else; endif; cannot be efficiently implemented without + adding a large amount of complexity to the 3.0 parser. Because of + this, the syntax has been changed: <example> - <title>Migrando: velha sintaxe if..endif</title> + <title>Migration: old if..endif syntax</title> <programlisting role="php"> <![CDATA[ if ($foo); - echo "sim\n"; + echo "yep\n"; elseif ($bar); - echo "quase\n"; + echo "almost\n"; else; - echo "n&atilde;o\n"; + echo "nope\n"; endif; ]]> </programlisting> </example> <example> - <title>Migrando: nova sintaxe if..endif</title> + <title>Migration: new if..endif syntax</title> <programlisting role="php"> <![CDATA[ if ($foo): - echo "sim\n"; + echo "yep\n"; elseif ($bar): - echo "quase\n"; + echo "almost\n"; else: - echo "n&atilde;o\n"; + echo "nope\n"; endif; ]]> </programlisting> </example> - Repare que todos os pontos-e-v&iacute;rgulas foram trocados por dois-pontos em todas - as instru&ccedil;&otilde;es, exceto na instru&ccedil;&atilde;o de fechamento (endif). + Notice that the semicolons have been replaced by colons in all + statements but the one terminating the expression (endif). </para> </section> <section id="migration-while"> - <title>sintaxe while</title> + <title>while syntax</title> <para> - Assim como o if...endif, a sintaxe do while...endwhile foi alterada: + Just like with if..endif, the syntax of while..endwhile has changed + as well: <example> - <title>Migrando: a velha sintaxe do while..endwhile</title> + <title>Migration: old while..endwhile syntax</title> <programlisting role="php"> <![CDATA[ -while ($mais_a_vir); +while ($more_to_come); ... endwhile; ]]> </programlisting> </example> <example> - <title>Migrando: nova sintaxe do while..endwhile</title> + <title>Migration: new while..endwhile syntax</title> <programlisting role="php"> <![CDATA[ -while ($mais_a_vir): +while ($more_to_come): ... endwhile; ]]> @@ -166,22 +168,22 @@ </para> <warning> <simpara> - Se voc&ecirc; usar a velha sintaxe do while...endwhile no PHP 3.0, - voc&ecirc; ir&aacute; obter um loop que nunca-termina. + If you use the old while..endwhile syntax in PHP 3.0, + you will get a never-ending loop. </simpara> </warning> </section> <section id="migration.expr"> - <title>Tipos de Express&otilde;es</title> + <title>Expression types</title> <simpara> - O PHP/FI 2.0 usa o lado esquerdo das express&otilde;es para determinar qual o tipo - de resultado que deve retornar. O PHP 3.0 examina ambos os lados quando - determina os tipos de resultados, e isto pode fazer com que scripts da vers&atilde;o - 2.0 comportem-se inesperadamente. + PHP/FI 2.0 used the left side of expressions to determine what type + the result should be. PHP 3.0 takes both sides into account when + determining result types, and this may cause 2.0 scripts to behave + unexpectedly in 3.0. </simpara> <para> - Considere este exemplo: + Consider this example: <informalexample> <programlisting role="php"> <![CDATA[ @@ -197,17 +199,20 @@ </programlisting> </informalexample> - No PHP/FI 2.0, isto mostraria ambos os &iacute;ndices de $a. No PHP 3.0, - isto n&atilde;o mostraria nada. A raz&atilde;o &eacute; que no PHP 2.0, &eacute; porque os argumentos - da esquerda eram do tipo string, ent&atilde;o uma compara&ccedil;&atilde;o de string foi feita, - e certamente <literal>""</literal> n&atilde;o &eacute; igual &agrave; <literal>"0"</literal>, e o - la&ccedil;o &eacute; completado. No PHP 3.0, quando uma string &eacute; comparada com um inteiro, uma - compara&ccedil;&atilde;o de inteiro &eacute; feita (a string &eacute; convertida para inteiro). Isto resultado em uma - compara&ccedil;&atilde;o em que <literal>atoi("")</literal> &eacute; <literal>0</literal>, e <literal>variablelist</literal> - tamb&eacute;m &eacute; <literal>0</literal>, deste que <literal>0==0</literal>, o loop n&atilde;o executa mais de uma vez. + In PHP/FI 2.0, this would display both of $a's indices. In PHP + 3.0, it wouldn't display anything. The reason is that in PHP 2.0, + because the left argument's type was string, a string comparison + was made, and indeed <literal>""</literal> does not equal + <literal>"0"</literal>, and the loop went through. In PHP 3.0, + when a string is compared with an integer, an integer comparison is + made (the string is converted to an integer). This results in + comparing <literal>atoi("")</literal> which is + <literal>0</literal>, and <literal>variablelist</literal> which is + also <literal>0</literal>, and since <literal>0==0</literal>, the + loop doesn't go through even once. </para> <para> - A corre&ccedil;&atilde;o para iso &eacute; simples. Troque aquele while por: + The fix for this is simple. Replace the while statement with: <informalexample> <programlisting role="php"> <![CDATA[ @@ -219,57 +224,60 @@ </section> <section id="migration.errors"> - <title>Mensagens de erro foram alteradas</title> + <title>Error messages have changed</title> <simpara> - No PHP 3.0 as mensagens de erro geralmente s&atilde;o mais exatadas do que as do PHP 2.0, - mas voc&ecirc; n&atilde;o ver&aacute; mais o fragmento de c&oacute;digo que cont&eacute;m o erro. Voc&ecirc; ser&aacute; notificado - com o nome do arquivo e o n&uacute;mero da linha onde ocorreu o erro. + PHP 3.0's error messages are usually more accurate than 2.0's were, + but you no longer get to see the code fragment causing the error. + You will be supplied with a file name and a line number for the + error, though. </simpara> </section> <section id="migration.booleval"> <title>Short-circuited boolean evaluation</title> <simpara> - No PHP 3.0 a avalia&ccedil;&atilde;o booleana &eacute; short-circuited. Isto significa que - uma express&atilde;o como esta <literal>(1 || teste_me())</literal>, da fun&ccedil;&atilde;o - <function>teste_me</function> n&atilde;o seria executada porque nada pode mudar - o resultado da express&atilde;o ap&oacute;s <literal>1</literal>. + In PHP 3.0 boolean evaluation is short-circuited. This means that + in an expression like <literal>(1 || test_me())</literal>, the + function <function>test_me</function> would not be executed since + nothing can change the result of the expression after the + <literal>1</literal>. </simpara> <simpara> - Esta &eacute; uma pequena incompatibilidade, mas poder&aacute; causar side-effects - inesperados. + This is a minor compatibility issue, but may cause unexpected + side-effects. </simpara> </section> <section id="migration.truefalse"> - <title>Fun&ccedil;&otilde;es &true;/&false; retornam valores</title> + <title>Function &true;/&false; return values</title> <simpara> - A maioria das fun&ccedil;&otilde;es foram reescritas sendo assim, retornam &true; - quando obt&eacute;m sucesso e &false; quando falham, ao contr&aacute;rio de 0 e -1 no - PHP/FI 2.0, respectivamente. O novo comportamento permite um c&oacute;digo mais - l&oacute;gico, como <literal>$fp = fopen("/seu/arquivo") or fail("merda!");</literal>. - Porque o PHP/FI 2.0 n&atilde;o tem regras claras quanto ao que a fun&ccedil;&atilde;o dever&aacute; retornar - caso falhe, muitos scripts provavelmente dever&atilde;o ser checados manualmente ap&oacute;s usar - o conversor de 2.0 para 3.0. + Most internal functions have been rewritten so they return &true; + when successful and &false; when failing, as opposed to 0 and -1 in + PHP/FI 2.0, respectively. The new behaviour allows for more + logical code, like <literal>$fp = fopen("/your/file") or + fail("darn!");</literal>. Because PHP/FI 2.0 had no clear rules + for what functions should return when they failed, most such + scripts will probably have to be checked manually after using the + 2.0 to 3.0 convertor. </simpara> <para> <example> - <title>Migrando do 2.0: retornando valores, c&oacute;digo antigo</title> + <title>Migration from 2.0: return values, old code</title> <programlisting role="php"> <![CDATA[ -$fp = fopen($arquivo, "r"); +$fp = fopen($file, "r"); if ($fp == -1); - echo("N&atilde;o foi poss&iacute;vel abrir $arquivo para leitura<br>\n"); + echo("Could not open $file for reading<br>\n"); endif; ]]> </programlisting> </example> <example> - <title>Migrando do 2.0: retornando valores, novo c&oacute;digo</title> + <title>Migration from 2.0: return values, new code</title> <programlisting role="php"> <![CDATA[ -$fp = @fopen($arquivo, "r") or print("N&atilde;o foi poss&iacute;vel abrir $arquivo para leitura<br>\n"); +$fp = @fopen($file, "r") or print("Could not open $file for reading<br>\n"); ]]> </programlisting> </example> @@ -277,60 +285,65 @@ </section> <section id="migration-other"> - <title>Outras incompatibilidades</title> + <title>Other incompatibilities</title> <itemizedlist> <listitem><simpara> - O m&oacute;dulo do PHP 3.0 para o Apache n&atilde;o suporta vers&otilde;es anteriores &agrave; 1.2. - Apache 1.2 ou atual &eacute; requerido. + The PHP 3.0 Apache module no longer supports Apache versions + prior to 1.2. Apache 1.2 or later is required. </simpara></listitem> <listitem><simpara> - <function>echo</function> n&atilde;o suporta mais strings formatadas. - Use a fun&ccedil;&atilde;o <function>printf</function> para isto. + <function>echo</function> no longer supports a format string. + Use the <function>printf</function> function instead. </simpara></listitem> <listitem><simpara> - No PHP/FI 2.0, uma execu&ccedil;&atilde;o "side-effect" faz com que <literal>$foo[0]</literal> - tenha o mesmo efeito que <literal>$foo</literal>. No PHP 3.0 isto n&atilde;o &eacute; verdadeiro. + In PHP/FI 2.0, an implementation side-effect caused + <literal>$foo[0]</literal> to have the same effect as + <literal>$foo</literal>. This is not true for PHP 3.0. </simpara></listitem> <listitem> <simpara> - Ler arrays com <literal>$array[]</literal> n&atilde;o &eacute; mais - suportado + Reading arrays with <literal>$array[]</literal> is no longer + supported </simpara> <simpara> - Isto &eacute;, voc&ecirc; n&atilde;o pode atravessar um array fazendo um loop que cont&eacute;m <literal>$data = $array[]</literal>. - Ao inv&eacute;s disso use <function>current</function> e <function>next</function>. + That is, you cannot traverse an array by having a loop that does + <literal>$data = $array[]</literal>. Use <function>current</function> + and <function>next</function> instead. </simpara> <simpara> - Tamb&eacute;m, <literal>$array1[] = $array2</literal> n&atilde;o adiciona - valores de <literal>$array2</literal> &agrave; <literal>$array1</literal>, - mas adiciona <literal>$array2</literal> como a &uacute;ltima entrada de - <literal>$array1</literal>. Veja tamb&eacute;m o suporte ao array multidimensional. + Also, <literal>$array1[] = $array2</literal> does not + append the values of <literal>$array2</literal> to + <literal>$array1</literal>, but appends + <literal>$array2</literal> as the last entry of + <literal>$array1</literal>. See also multidimensional array + support. </simpara> </listitem> <listitem> <simpara> - <literal>"+"</literal> n&atilde;o &eacute; mais considerado como um concatenador de - strings, ao inv&eacute;s disso &eacute; usado para converter argumentos para n&uacute;meros - e executar adi&ccedil;&otilde;es n&uacute;mericas. Use <literal>"."</literal> para concatenar. + <literal>"+"</literal> is no longer overloaded as a + concatenation operator for strings, instead it converts it's + arguments to numbers and performs numeric addition. Use + <literal>"."</literal> instead. </simpara> </listitem> </itemizedlist> <example> - <title>Migrando do 2.0: concatena&ccedil;&atilde;o de strings</title> + <title>Migration from 2.0: concatenation for strings</title> <programlisting role="php"> <![CDATA[ echo "1" + "1"; ]]> </programlisting> <para> - No PHP 2.0 isto retornaria echo 11, no PHP 3.0 isto - retornar&aacute; echo 2. Ao inv&eacute;s disso use: + In PHP 2.0 this would echo 11, in PHP 3.0 it would + echo 2. Instead use: <programlisting role="php"> <![CDATA[ echo "1"."1"; @@ -345,7 +358,7 @@ </programlisting> </para> <para> - Isto ir&aacute; retornar echo 2 em ambas vers&otilde;es do PHP 2.0 e 3.0. + This would echo 2 in both PHP 2.0 and 3.0. <programlisting role="php"> <![CDATA[ $a = 1; @@ -353,7 +366,7 @@ echo $a.$b; ]]> </programlisting> - Isto retornar&aacute; echo 11 no PHP 3.0. + This will echo 11 in PHP 3.0. </para> </example> </section> Index: phpdoc/en/appendices/migration4.xml diff -u phpdoc/en/appendices/migration4.xml:1.26 phpdoc/en/appendices/migration4.xml:1.27 --- phpdoc/en/appendices/migration4.xml:1.26 Wed Nov 20 07:19:11 2002 +++ phpdoc/en/appendices/migration4.xml Wed Nov 20 08:11:20 2002 @@ -1,43 +1,43 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.26 $ --> +<!-- $Revision: 1.27 $ --> <appendix id="migration4"> - <title>Migrando do PHP 3 para o PHP 4</title> + <title>Migrating from PHP 3 to PHP 4</title> <section id='migration4.changes'> - <title>O que mudou no PHP 4</title> + <title>What has changed in PHP 4</title> <para> - O PHP 4 e a integra&ccedil;&atilde;o com o engine Zend melhoraram incrivelmente a - performance e potencialidades do PHP, mas foi tomado o cuidado - de deixar o c&oacute;digo existente o m&aacute;ximo poss&iacute;vel. Sendo assim, migrar seu - c&oacute;digo do PHP 3 para PHP 4 &eacute; muito mais f&aacute;cil do que migrar do PHP/FI 2 para PHP 3. - Muitos c&oacute;digos existentes do PHP 3 podem rodar sem altera&ccedil;&otilde;es, mas voc&ecirc; dever&aacute; - ficar atento as diferenta&ccedil;as e ter o cuidado de testar seu c&oacute;digo antes de trocar as - vers&otilde;es nos sistemas de produ&ccedil;&otilde;es. O material abaixo dever&aacute; dar &agrave; - voc&ecirc; algumas instru&ccedil;&otilde;es sobre o que procurar. + PHP 4 and the integrated Zend engine have greatly improved PHP's + performance and capabilities, but great care has been taken to + break as little existing code as possible. So migrating your code + from PHP 3 to 4 should be much easier than migrating from + PHP/FI 2 to PHP 3. A lot of existing PHP 3 code should be + ready to run without changes, but you should still know about the + few differences and take care to test your code before switching + versions in production environments. The following should give you + some hints about what to look for. </para> </section> <section id="migration4.php4.with.php3"> - <title>Rodando PHP 3 e PHP 4 simultaneamente</title> + <title>Running PHP 3 and PHP 4 concurrently</title> <simpara> - Os sistemas operacionais atuais fornecem a habilidade de de - executar "versioning" e "scoping". Estas caracter&iacute;sticas - tornam poss&iacute;vel deixar-mos o PHP 3 e PHP 4 rodando simultaneamente - como m&oacute;dulos em um s&oacute; servidor Apache. + Recent operating systems provide the ability to perform + versioning and scoping. This features make it possible to let + PHP 3 and PHP 4 run as concurrent modules in one Apache server. </simpara> <simpara> - Esta op&ccedil;&atilde;o &eacute; suportada nas seguintes plataformas: + This feature is known to work on the following platforms: </simpara> <itemizedlist> - <listitem><simpara>Linux com os recentes binutils (binutils 2.9.1.0.25 testado) </simpara></listitem> - <listitem><simpara>Solaris 2.5 ou superior</simpara></listitem> - <listitem><simpara>FreeBSD (3.2, 4.0 testado)</simpara></listitem> + <listitem><simpara>Linux with recent binutils (binutils 2.9.1.0.25 tested) </simpara></listitem> + <listitem><simpara>Solaris 2.5 or better</simpara></listitem> + <listitem><simpara>FreeBSD (3.2, 4.0 tested)</simpara></listitem> </itemizedlist> <para> - Para habilitar isto, configure seu PHP 3 e PHP 4 usando o APXS - (--with-apxs) e linkar as extens&otilde;es necess&aacute;rias (--enable-versioning). - Por outro lado, isto tamb&eacute;m se aplica para todas as instala&ccedil;&otilde;es padr&otilde;es. - Por exemplo: + To enable it, configure PHP3 and PHP4 to use APXS + (--with-apxs) and the necessary link extensions + (--enable-versioning). Otherwise, all standard installations + instructions apply. For example: <informalexample> <programlisting role="configure"> <![CDATA[ @@ -53,15 +53,15 @@ </section> <section id="migration4.configuration"> - <title>Migrando os arquivos de configura&ccedil;&atilde;o</title> + <title>Migrating Configuration Files</title> <para> - O arquivo de configura&ccedil;&atilde;o global, <filename>php3.ini</filename>, - foi alterado para ete nome &php.ini;. + The global configuration file, <filename>php3.ini</filename>, + has changed its name to &php.ini;. </para> <para> - Para o arquivo de configura&ccedil;&atilde;o do Apache, h&aacute; algumas pequenas - mudan&ccedil;as. Os tipos de MIME reconhecidos pelo m&oacute;dulo do PHP foram - alterados. + For the Apache configuration file, there are slightly more + changes. The MIME types recognized by the PHP module have + changed. <informalexample> <programlisting role="apache"> <![CDATA[ @@ -72,9 +72,9 @@ </informalexample> </para> <para> - Você pode fazer seu arquivo de configuração trabalhar com ambas as - versões do PHP (dependendo de qual compilação está no servidor), - usando a seguinte sintaxe: + You can make your configuration files work with both versions + of PHP (depending on which one is currently compiled into the + server), using the following syntax: <informalexample> <programlisting> <![CDATA[ @@ -88,11 +88,11 @@ </informalexample> </para> <simpara> - Al&eacute;m disso, os nomes das diretiva do PHP para o Apache foram alteradas. + In addition, the PHP directive names for Apache have changed. </simpara> <para> - Come&ccedil;ando com o PHP 4.0, h&aacute; quatro diretivas para o Apache relacionadas - ao PHP: + Starting with PHP 4.0, there are only four Apache directives + that relate to PHP: <informalexample> <programlisting role="apache"> <![CDATA[ @@ -105,23 +105,17 @@ </informalexample> </para> <simpara> - H&aacute; duas diferen&ccedil;as entre os valores do Admin e do n&atilde;o admin: + There are two differences between the Admin values and the non admin values: </simpara> <itemizedlist> - <listitem><simpara>Os valores Admin (ou os flags) s&oacute; aparecem no server-wide dos arquivos de configura&ccedil;&atilde;o - do apache (e.g., httpd.conf).</simpara></listitem> - <listitem><simpara>Os valores padr&otilde;es (ou os flags) n&atilde;o podem controlar determinadas diretivas do PHP, - por exemplo - safe mode (se voc&ecirc; pude-se cancelar as configura&ccedil;&otilde;es do modo seguro em arquivos .htacces, - isto desativaria o modo-seguro). Em contraste, os valores Admin podem modificar qualquer diretiva do PHP.</simpara></listitem>. + <listitem><simpara>Admin values (or flags) can only appear in the server-wide apache configuration files (e.g., httpd.conf).</simpara></listitem> + <listitem><simpara>Standard values (or flags) cannot control certain PHP directives, for example - safe mode (if you could override safe mode settings in .htaccess files, it would defeat safe-mode's purpose). In contrast, Admin values can modify the value of any PHP directive.</simpara></listitem> </itemizedlist> <simpara> - Para tornar o processo de transi&ccedil;&atilde;o mais f&aacute;cil, o PHP 4 vem com scripts que convertem automaticamente - suas configura&ccedil;&otilde;es do Apache e arquivos .htacces para trabalharem com ambos PHP 3 e PHP 4. Estes scripts - N&Atilde;O convertem as linhas do tipo MIME! Voc&ecirc; ter&aacute; que converter manualmente. + To make the transition process easier, PHP 4 is bundled with scripts that automatically convert your Apache configuration and .htaccess files to work with both PHP 3 and PHP 4. These scripts do NOT convert the mime type lines! You have to convert these yourself. </simpara> <para> - Para converter seus arquivos de configura&ccedil;&atilde;o do Apache, rode o script apconf-conv.sh (distpon&iacute;vel no - diret&oacute;rio /scripts/apache). Exemplo: + To convert your Apache configuration files, run the apconf-conv.sh script (available in the scripts/apache/ directory). For example: <informalexample> <programlisting role="shell"> <![CDATA[ @@ -131,11 +125,10 @@ </informalexample> </para> <simpara> - Seu arquivo de configura&ccedil;&atilde;o original ser&aacute; salve como httpd.conf.orig. + Your original configuration file will be saved in httpd.conf.orig. </simpara> <para> - Para converter seus arquivos .htaccess, rode o script aphtaccess-conv.sh (dispon&iacute;vel no - diret&oacute;rio scripts/apache), exemplo: + To convert your .htaccess files, run the aphtaccess-conv.sh script (available in the scripts/apache/ directory as well): <informalexample> <programlisting role="shell"> <![CDATA[ @@ -145,316 +138,315 @@ </informalexample> </para> <simpara> - Como j&aacute; foi dito, seus antigos arquivos .htacces ser&atilde;o salvos com o prefixo .orig. + Likewise, your old .htaccess files will be saved with an .orig prefix. </simpara> <simpara> - A convers&atilde;o dos scripts requer que o awk esteja instalado. + The conversion scripts require awk to be installed. </simpara> </section> <section id='migration4.parser'> - <title>Comportamento da Análise</title> + <title>Parser behavior</title> <para> - A execução e a análise são agora duas etapas completamente separadas, - nenhuma execução de código de arquivo será acontecerá até que tudo seja - completado e analisado completamente. + Parsing and execution are now two completely separated steps, no + execution of a files code will happen until the complete file and + everything it requires has completely and successfully been + parsed. </para> <para> - Uma das novas exig&ecirc;ncias introduzidas com este split &eacute; que - arquivos requeridos e inclu&iacute;dos agora tem que estar sintaticamente - completos. Voc&ecirc; n&atilde;o pode mais espalhar os em diferentes partes os - controles de estrutura ou espalahar os controles atrav&eacute;s de arquivos. - Voc&ecirc; n&atilde;o pode come&ccedil;ar um la&ccedil;o <literal>for</literal> ou <literal>while</literal>, - um bloco de instru&ccedil;&otilde;es <literal>if</literal> ou <literal>switch</literal> come&ccedil;ando - em um arquivo e terminar o loop, <literal>else</literal>, <literal>endif</literal>, - <literal>case</literal> ou <literal>break</literal> em um arquivo diferente. + One of the new requirements introduced with this split is that + required and included files now have to be syntactically + complete. You can no longer spread the different controlling parts + of a control structure across file boundaries. That is you cannot + start a <literal>for</literal> or <literal>while</literal> loop, + an <literal>if</literal> statement or a <literal>switch</literal> + block in one file and have the end of loop, + <literal>else</literal>, <literal>endif</literal>, + <literal>case</literal> or <literal>break</literal> statements in + a different file. </para> <para> - Ainda &eacute; permitido incluir c&oacute;digos adicionaisdentro dos la&ccedil;os ou - estruturas de controle, somente os controles chaves e os correspondentes - <literal>(....)</literal> tem que estar compilados na mesma unidade - (arquivo ou <function>eval</function>ed string). + It still perfectly legal to include additional code within loops + or other control structures, only the controlling keywords and + corresponding curly braces <literal>{...}</literal> have to be + within the same compile unit (file or <function>eval</function>ed + string). </para> <para> - Isto n&atilde;o deve prejudicar muito considerando que um c&oacute;digo como este - &eacute; considerado mal feito de qualquer maneira. + This should not harm to much as spreading code like this should be + considered as very bad style anyway. </para> <para> - Outra coisa que n&atilde;o &eacute; mais poss&iacute;vel, e que &eacute; raramente visto em um c&oacute;digo - PHP 3 &eacute; o retorno de valores de um requerido arquivo. Retornar valores - de um arquivo inclu&iacute;do ainda &eacute; poss&iacute;vel. + Another thing no longer possible, though rarely seen in PHP 3 + code is returning values from a required file. Returning a value + from an included file is still possible. </para> </section> <section id='migration4.error-reporting'> - <title>Relatório de erros</title> + <title>Error reporting</title> <section id='migration4.error-reporting.config'> - <title>Mudan&ccedil;as na Configura&ccedil;&atilde;o</title> + <title>Configuration changes</title> <para> - O relat&oacute;rio de erro do PHP 3 foi ajustado para um simples - valor n&uacute;mero formado pela soma de n&uacute;meros relacionados aos - diferentes n&iacute;veis de erro. Valores usuais onde 15 para relatar - todos os erros e mensagens ou 7 para relatar qualquer coisa mas - simples observa&ccedil;&atilde;o ao mal estilo e coisas como esta. - </para> - <para> - PHP 4 cont&eacute;m um maior n&iacute;vel de erros e avisos e vem com uma - configura&ccedil;&atilde;o do parser que agora permite que constantes simb&oacute;licas - sejam usadas para para ajustar ao comportamente pretendido. - </para> - <para> - O n&iacute;vel do relat&oacute;rio de erro agora pode ser configurado explicitamente - removendo os n&iacute;veis de advert&ecirc;ncia que voc&ecirc; n&atilde;o quer gerar nas suas - mensagens de erro x-oring da constante simb&oacute;lica <literal>E_ALL</literal>. - Parece complicado? Bem, vamos dizer que voc&ecirc; quer todas as advert&ecirc;ncias - categorizadas na constante simb&oacute;lica <literal>E_NOTICE</literal>. Ent&atilde;o voc&ecirc; - dever&aacute; colocar o seguinte em seu &php.ini;: <literal>error_reporting = - E_ALL &amp; - ( E_NOTICE )</literal>. Se voc&ecirc; quiser suprir as - advert&ecirc;ncias voc&ecirc; deve adicionar a constante apropriada dentro do - par&ecirc;ntese usando o operador '|': - <literal>erro_reporting = E_ALL &amp; ~ ( E_NOTICE | E_WARNING )</literal>. + With PHP 3 the error reporting level was set as a simple + numeric value formed by summing up the numbers related to + different error levels. Usual values where 15 for reporting all + errors and warnings or 7 for reporting everything but simple + notice messages reporting bad style and things like that. + </para> + <para> + PHP 4 has a larger set of error and warning levels and comes with a + configuration parser that now allows for symbolic constants to be used + for setting the intended behavior. + </para> + <para> + Error reporting level should now be configured by explicitly + taking away the warning levels you do not want to generate error + messages by x-oring them from the symbolic constant + <literal>E_ALL</literal>. Sounds complicated? Well, lets say you + want the error reporting system to report all but the simple + style warnings that are categorized by the symbolic constant + <literal>E_NOTICE</literal>. Then you'll put the following into + your &php.ini;: <literal>error_reporting = + E_ALL &amp; ~ ( E_NOTICE )</literal>. If you want to suppress + warnings too you add up the appropriate constant within the + braces using the binary or operator '|': + <literal>error_reporting= E_ALL &amp; ~ ( E_NOTICE | E_WARNING + )</literal>. </para> <warning> <para> - Ao atualizar c&oacute;digos ou servidores do PHP 3 para PHP 4 voc&ecirc; - deve checar as configura&ccedil;&otilde;es e chamadas ao <function>error_reporting</function> - ou voc&ecirc; deve desabilitar os novos tipos de relat&oacute;rio de erro, - especialmente E_COMPILE_ERROR. Isto pode ocasionar a limpeza de - documents sem nenhuma resposta do que ocorreu ou onde procurar - pelo problema. + When upgrading code or servers from PHP 3 to PHP 4 you should + check these settings and calls to + <function>error_reporting</function> or you might disable + reporting the new error types, especially E_COMPILE_ERROR. This + may lead to empty documents without any feedback of what happened + or where to look for the problem. </para> </warning> <warning> <para> - Usando valores menores que 7 ou 15 para ajustar o relat&oacute;rio - de erro n&atilde;o &eacute; uma boa id&eacute;ia porque pode suprir algumas das - classes de erros adicionadas no parser de erros. Isto pode causar - um comportamento estranho com os scripts e tamb&eacute;m n&atilde;o ir&aacute; - mostrar nenhuma mensagem de erro em nenhum lugar. + Using the old values 7 and 15 for setting up error reporting is + a very bad idea as this suppresses some of the newly added error + classes including parse errors. This may lead to very strange + behavior as scripts might no longer work without error messages + showing up anywhere. </para> <para> - No passa isto causou muitas inconveni&ecirc;ncias porque as - pessoas relatavam problemas nos scripts e na verdade - n&atilde;o eram capazes de consertar erros comuns, como a falta de - um '}' requerido em um arquivo que era passado e que o - parser n&atilde;o era capaz de reportar um erro que era apenas - um erro de uma falta de configura&ccedil;&atilde;o no sistema. + This has lead to a lot of unreproducible bug reports in the + past where people reported script engine problems they were not + capable to track down while the &true; case was usually some + missing '}' in a required file that the parser was not able to + report due to a misconfigured error reporting system. </para> <para> - Ent&atilde;o checar a sua configura&ccedil;&atilde;o do relat&oacute;rio de erros - deve ser a primeira coisa a fazer quando os seus scripts - causam erros silenciosos. O engine da Zend pode ser - considerado maduro o bastante nos dias atuais para n&atilde;o - causar estes tipos de erros estranhos. + So checking your error reporting setup should be the first thing + to do whenever your scripts silently die. The Zend engine can + be considered mature enough nowadays to not cause this kind of + strange behavior. </para> </warning> </section> <section id='migration4.error-reporting.additions'> - <title>Mensagens de advert&ecirc;ncia adicionais</title> + <title>Additional warning messages</title> <para> - Muitos c&oacute;digos PHP 3 existentes usam uma linguagem de estrutura - que pode ser considerado um c&oacute;digo mal formatado, o que pode - tornar as coisas f&aacute;ceis agora, pode facilmente ser quebrado - por mudan&ccedil;as em outros lugares. PHP 4 exibe muitas mensagens - de advert&ecirc;ncia em situa&ccedil;&otilde;es onde o PHP 3 n&atilde;o o fazia. O jeito - f&aacute;cil de consertar isto &eacute; setar para off as mensagens E_NOTICE, - mas geralmente &eacute; sempre bom consertar o c&oacute;digo. - </para> - <para> - O caso mais comum que agora ir&aacute; produzir mensagens de advert&ecirc;ncia - &eacute; o uso de constantes de strings n&atilde;o quotadas como &iacute;ndices de array. - Ambos PHP 3 e PHP 4 tentar&atilde;o interpretarar isto como se fosse strings - se nenhuma palavra ou constante for conhecida pelo nome, mas sempre que - uma constante por esse nome for definida em qualquer lugar do c&oacute;digo - ela pode causar erros no script. Isto pode se tornar um risco de - seguran&ccedil;a se um invasor redefinir as strings constantes &agrave; um - caminho que faz o seu script dar as permiss&otilde;es corretas que ele - n&atilde;o deveria ter. Ent&atilde;o o PHP 4 agora avisa voc&ecirc; sempre que - voc&ecirc; usar strings constantes n&atilde;o quotadas por exemplo no - <literal>$_SERVER[REQUEST_METHOD]</literal>. Altere isto para - <literal>$_SERVER['REQUEST_METHOD']</literal> que far&aacute; - com que o parser fique feliz e melhorar&aacute; extremamente o - estilo e seguran&ccedil;a do seu c&oacute;digo. + A lot of existing PHP 3 code uses language constructs that + should be considered as very bad style as this code, while doing + the intended thing now, could easily be broken by changes in + other places. PHP 4 will output a lot of notice messages in + such situations where PHP 3 didn't. The easy fix is to just + turn off E_NOTICE messages, but it is usually a good idea to fix + the code instead. + </para> + <para> + The most common case that will now produce notice messages is the + use of unquoted string constants as array indices. Both PHP 3 + and 4 will fall back to interpret these as strings if no + keyword or constant is known by that name, but whenever a + constant by that name had been defined anywhere else in the code + it might break your script. This can even become a security risk + if some intruder manages to redefine string constants in a way + that makes your script give him access rights he wasn't intended + to have. So PHP 4 will now warn you whenever you use unquoted + string constants as for example in + <literal>$_SERVER[REQUEST_METHOD]</literal>. Changing it + to <literal>$_SERVER['REQUEST_METHOD']</literal> will + make the parser happy and greatly improve the style and security + of your code. </para> <para> - Outra coisa que o PHP 4 agora lhe informa &eacute; sobre o uso - de vari&aacute;veis ou elementos de array n&atilde;o inicializados. + Another thing PHP 4 will now tell you about is the use of + uninitialized variables or array elements. </para> </section> </section> <section id='migration4.initializers'> - <title>Inicializadores</title> + <title>Initializers</title> <para> - Os inicializadores de vari&aacute;veis est&aacute;ticas e membros de classes - aceitam somente valores escalares enquanto no PHP 3 eles aceitavam - qualquer express&atilde;o v&aacute;lida. Isto &eacute;, mais uma vez, devido ao corte entre - a execu&ccedil;&atilde;o e o parsing como nenhum c&oacute;digo executado quando o parser - v&ecirc; o inicializador. + Static variable and class member initializers only accept scalar + values while in PHP 3 they accepted any valid expression. This + is, once again, due to the split between parsing and execution as + no code has yet been executed when the parser sees the + initializer. </para> <para> - Para classes voc&ecirc; deve usar construtores para inicializar - membros ao inv&eacute;s de vari&aacute;veis. Para vari&aacute;veis est&aacute;ticas - pode-se usar qualquer coisa mas raramente uma simples - vari&aacute;vel est&aacute;tira faz algum sentido. + For classes you should use constructors to initialize member + variables instead. For static variables anything but a simple + static value rarely makes sense anyway. </para> </section> <section id='migration4.empty'> <title><literal>empty("0")</literal></title> <para> - Talvez a mudan&ccedil;a mais controversa no comportamento aconteceu na fun&ccedil;&atilde;o - <function>empty</function>. Uma string que cont&eacute;m somente caracteres - ' 0 ' (zero) agora &eacute; considerada vazia enquanto no PHP 3 ela n&atilde;o era. + The perhaps most controversial change in behavior has happened to the + behavior of the <function>empty</function>. A String containing + only the character '0' (zero) is now considered empty while it + wasn't in PHP 3. </para> <para> - Estes novos comportamentos fazem sentido em aplicativos web, com todos - aqueles campos retornando strings mesmo se entradas n&uacute;mericas s&atilde;o requisitadas, - e com as capacidades do PHP automaticamente converter os tipos. Mas - por outro lado isto pode gerar problemas no seu c&oacute;digo de uma - maneira totalmente pertubadora, conduzindo ao um estranho comportamento - que &eacute; duro de consertar se voc&ecirc; n&atilde;o souber o que voc&ecirc; procura. + This new behavior makes sense in web applications, with all input + fields returning strings even if numeric input is requested, and + with PHP's capabilities of automatic type conversion. But on the + other had it might break your code in a rather subtle way, + leading to misbehavior that is hard to track down if you do not + know about what to look for. </para> </section> <section id='migration4.missing'> - <title>Fun&ccedil;&otilde;es abandonadas</title> + <title>Missing functions</title> <para> - Enquanto o PHP 4 vem com uma s&eacute;rie de novas caracter&iacute;sticas, - fun&ccedil;&otilde;es e extens&otilde;es, voc&ecirc; talvez encontre algumas fun&ccedil;&otilde;es da - vers&atilde;o 3 que n&atilde;o existem mais. Um pequeno n&uacute;mero de fun&ccedil;&otilde;es - do n&uacute;cleo desapareceu porque elas n&atilde;o funcionavam com o novo - sistema de execu&ccedil;&atilde;o e parsing introduzido na vers&atilde;o 4 com a - Zend engine. Outras fun&ccedil;&otilde;es e mesmo extens&otilde;es se tornaram - obsoletas para as novas fun&ccedil;&otilde;es e extens&otilde;es que servem a - mesma tarefa melhor e/ou de uma maneira geral. Algumas fun&ccedil;&otilde;es - simplesmente n&atilde;o foram portadas ainda e finalmente algumas - fun&ccedil;&otilde;es ou extens&otilde;es podem ter sido retiradas por conflitos - de licen&ccedil;a. + While PHP 4 comes with a lot of new features, functions and + extensions, you may still find some functions from version 3 + missing. A small number of core functions has vanished because + they do not work with the new scheme of splitting parsing and + execution as introduced into 4 with the Zend engine. Other + functions and even complete extensions have become obsolete as + newer functions and extensions serve the same task better and/or + in a more general way. Some functions just simply haven't been + ported yet and finally some functions or extensions may be missing + due to license conflicts. </para> <section id='migration4.missing.concept'> - <title>Funções abandonadas devido à mudanças conceptuais</title> + <title>Functions missing due to conceptual changes</title> <para> - Como o PHP 4 agora separa o parsing da execu&ccedil;&atilde;o n&atilde;o &eacute; mais poss&iacute;vel - alterar o comportamento do parser (agora embutido na Zend engine) - na hora da execu&ccedil;&atilde;o quando o parsing j&aacute; aconteceu. Ent&atilde;o a fun&ccedil;&atilde;o - <function>short_tags</function> n&atilde;o existe mais. Voc&ecirc; ainda - pode mudar o comportamento dos parsers setando o valor - propriedade no arquivo &php.ini. + As PHP 4 now separates parsing from execution it is no longer + possible to change the behavior of the parser (now embedded in + the Zend engine) at runtime as parsing already happened by + then. So the function <function>short_tags</function> no longer + exists. You can still change the parsers behavior by setting + appropriate values in the &php.ini; file. </para> <para> - Outra caracter&iacute;sticas do PHP 3 que n&atilde;o faz parte do PHP 4 &eacute; - a rela&ccedil;&atilde;o embutida de eliminar erros. Existem add-ons de terceiros - para a Zend engine que adicionam um funcionamento similar. + Another feature of PHP 3 that is not a part of PHP 4 is the bundled + debugging interface. There are third-party add-ons for the Zend engine + which add similar functionality. </para> </section> <section id='migration4.deprecate'> - <title>Depcritamento de fun&ccedil;&otilde;es e extens&otilde;es</title> + <title>Deprecate functions and extensions</title> <para> - As extens&otilde;es dos banco de dados Adabas e Solid n&atilde;o existem mais. - Ao in&eacute;s delas foi unificado o ODBC. + The Adabas and Solid database extensions are no more. Long live + the unified ODBC extension instead. </para> </section> <section id='migration4.unset'> - <title>Mudan&ccedil;a de status para <function>unset</function></title> + <title>Changed status for <function>unset</function></title> <para> - <function>unset</function>, embora ainda dispon&iacute;vel, &eacute; - implementado como um construtor de linguagem melhor que uma fun&ccedil;&atilde;o. + <function>unset</function>, although still available, is + implemented as a language construct rather than a function. </para> <para> - Isto n&atilde;o tem nenhumas conseq&uuml;&ecirc;ncias no comportamento < de function>unset, mas testar para "unset" usando < function>function_exists retornar&aacute; o &false; porque com outras constru&ccedil;&otilde;es da l&iacute;ngua que olham como fun&ccedil;&otilde;es tais como < function>echo. - Isto n&atilde;o interfere em nada no comportamento do - <function>unset</function>, mas testar "unset" usando - <function>function_exists</function> retornar&aacute; &false; - porque com outros construtores de linguagens que observam - func&ccedil;&otilde;es tais como o <function>echo</function>. + This does not have any consequences on the behavior of + <function>unset</function>, but testing for "unset" using + <function>function_exists</function> will return &false; as it would with + other language constructs that look like functions such as + <function>echo</function>. </para> <para> - Uma otura mudan&ccedil;a mais pr&aacute;tica &eacute; que n&atilde;o &eacute; mais poss&iacute;vel chamar - <function>unset</function> indiretamente, isso &eacute;, <literal>$func="unset"; $func($algumavar)</literal> - n&atilde;o ir&aacute; mais funcionar. + Another more practical change is that it is no longer possible to + call <function>unset</function> indirectly, that is + <literal>$func="unset"; $func($somevar)</literal> won't work + anymore. </para> </section> </section> <section id='migration4.extensions'> - <title>Extens&otilde;es PHP 3</title> + <title>PHP 3 extension</title> <para> - Extens&otilde;es escritas para o PHP 3 n&atilde;o ir&atilde;o funcionar com o PHP 4, - nem como bin&aacute;rias nem no c&oacute;digo fonte. N&atilde;o &eacute; dif&iacute;cil portar estas - extens&otilde;es para o PHP 4 se vc&ecirc; tiver acesso aos fontes originais. - Uma descri&ccedil;&atilde;o detalhada do processo de porta&ccedil;&atilde;o n&atilde;o faz parte deste - texto. + Extensions written for PHP 3 will not work with PHP 4, neither as binaries + nor at the source level. It is not difficult to port extensions to PHP 4 + if you have access to the original source. A detailed description of the + actual porting process is not part of this text. </para> </section> <section id='migration4.strings'> - <title>Substitui&ccedil;&atilde;o de vari&aacute;veis nas strings</title> + <title>Variable substitution in strings</title> <para> - O PHP 4 adiciona um novo mecanimos para a substitui&ccedil;&atilde;o - de vari&aacute;veis em strings. Agora voc&ecirc; finalmente pode acessar - as vari&aacute;veis de um objeto membro e seus elementos de um - array multidimensional dentro de strings. + PHP 4 adds a new mechanism to variable substitution in + strings. You can now finally access object member variables and + elements from multidimensional arrays within strings. </para> <para> - Para fazer isso voc&ecirc; tem que incluir nas suas vari&aacute;veis chaves - com o s&iacute;mbolo da moeda imediatamente ap&oacute;s a chave de abertura: + To do so you have to enclose your variables with curly braces with + the dollar sign immediately following the opening brace: <literal>{$...}</literal> </para> <para> - Para embutir o valor de um objeto membro de uma vari&aacute;vel - dentro de uma string simplesmente escreva <literal>"texto {$obj-&gt;membro} texto"</literal> - enquanto no PHP 3 voc&ecirc; tinha que usar uma coisa como esta - <literal>"texto ".$obj-&gt;membro." texto"</literal>. + To embed the value of an object member variable into a string you + simply write <literal>"text {$obj-&gt;member} text"</literal> while + in PHP 3 you had to use something like <literal>"text + ".$obj-&gt;member." text"</literal>. </para> <para> - Isto gera um c&oacute;digo mais leg&iacute;vel, mas pode gerar problemas - em scripts existentes escritos para o PHP 3. Mas - voc&ecirc; pode facilmente char este tipo de problema procurando - por uma combina&ccedil;&atilde;o de caracteres <literal>{$</literal> - no seu c&oacute;digo e substituindo eles por - <literal>\{$</literal> usando sua ferramenta de - procura-e-substitui&ccedil;&atilde;o favorita. - </para> + This should lead to more readable code, while it may break + existing scripts written for PHP 3. But you can easily check for + this kind of problem by checking for the character combination + <literal>{$</literal> in your code and by replacing it with + <literal>\{$</literal> with your favorite search-and-replace + tool. + </para> </section> <section id='migration4.cookies'> <title>Cookies</title> <para> - O PHP 3 tinha um mau h&aacute;bito de configurar os cookies na ordem - reversa das chamadas <function>setcookie</function> no seu c&oacute;digo. - O PHP 4 inibiu este mau h&aacute;bito e cria as linhas de cabe&ccedil;alhos - dos cookies exatamente na mesma ordem que voc&ecirc; definie no - seu c&oacute;digo. + PHP 3 had the bad habit of setting cookies in the reverse order + of the <function>setcookie</function> calls in your code. PHP 4 + breaks with this habit and creates the cookie header lines in + exactly the same order as you set the cookies in the code. </para> <para> - Isto pode gerar problemas no seu c&oacute;digo existente, mas o velho - comportamente era t&atilde;o estranho de se entender que mereceu - uma mudan&ccedil;a para previnir futuros problemas. + This might break some existing code, but the old behaviour was so + strange to understand that it deserved a change to prevent further + problems in the future. </para> </section> <section id='migration4.variables'> - <title>Manipula&ccedil;&atilde;o de vari&aacute;veis globais</title> + <title>Handling of global variables</title> <para> - A manipula&ccedil;&atilde;o de vari&aacute;veis globais tinha o foco de ser - f&aacute;cil no PHP 3 e vers&otilde;es posteriores &agrave; PHP 4, mas este - foco mudou por medidas de seguran&ccedil;a. Enquanto em um - script PHP 3 o exemplo a seguir funciona normalmente, - no PHP 4 tem que se usar unset($GLOBALS["id"]);. Isto - &eacute; apenas uma introdu&ccedil;&atilde;o da manipula&ccedil;&atilde;o de vari&aacute;veis globais. - Voc&ecirc; dever&aacute; sempre usar $GLOBALS, com as novas vers&otilde;es - do PHP 4 voc&ecirc; &eacute; for&ccedil;ado a fazer isto na maioria dos casos. - Leia mais sobre este assunto em <link linkend="references.global">. + While handling of global variables had the focus on to be easy in + PHP 3 and early versions of PHP 4, the focus has changed to be more + secure. While in PHP 3 the following example worked fine, in PHP 4 it + has to be unset($GLOBALS["id"]);. This is only one issue of global + variable handling. You should always have used $GLOBALS, with + newer versions of PHP 4 you are forced to do so in most cases. + Read more on this subject in the <link linkend="references.global"> + <literal>global</literal> references section</link>. </para> <example> - <title>Migra&ccedil;&atilde;o das vari&aacute;veis globais</title> + <title>Migration of global variables</title> <programlisting role="php"> <![CDATA[ <?php Index: phpdoc/en/appendices/phpdevel.xml diff -u phpdoc/en/appendices/phpdevel.xml:1.21 phpdoc/en/appendices/phpdevel.xml:1.22 --- phpdoc/en/appendices/phpdevel.xml:1.21 Wed Nov 20 07:19:11 2002 +++ phpdoc/en/appendices/phpdevel.xml Wed Nov 20 08:11:20 2002 @@ -1,16 +1,16 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.21 $ --> +<!-- $Revision: 1.22 $ --> <appendix id="phpdevel"> - <title>Estentendo o PHP</title> + <title>Extending PHP</title> <simpara></simpara> <sect1 id="phpdevel-addfunc"> - <title>Adicionando fun&ccedil;&otilde;es ao PHP</title> + <title>Adding functions to PHP</title> <sect2 id="phpdevel-addfunc-prototype"> - <title>Fun&ccedil;&atilde;o Prototype</title> + <title>Function Prototype</title> <para> - Todas as fun&ccedil;&otilde;es separecem com esta: + All functions look like this: <programlisting role="c"> <![CDATA[ void php3_foo(INTERNAL_FUNCTION_PARAMETERS) { @@ -18,18 +18,16 @@ } ]]> </programlisting> - Mesmo se sua fun&ccedil;&atilde;o n&atilde;o pegar nenhum argumento, &eacute; assim - que ela &eacute; chamada. - </para></sect2> + Even if your function doesn't take any arguments, this is how it is + called.</para></sect2> <sect2 id="phpdevel-addfunc-args"> - <title>Argumentos das fun&ccedil;&otilde;es</title> + <title>Function Arguments</title> <para> - Os argumentos s&atilde;o sempre do tipo pval. Este tipo cont&eacute;m a uni&atilde;o - que cont&eacute;m o tipo atual do argumento. Ent&atilde;o, se sua fun&ccedil;&atilde;o - pegar dois argumentos, voc&ecirc; faria algo como a seguir no topo - da sua fun&ccedil;&atilde;o: - </para> + Arguments are always of type pval. This type contains a union + which has the actual type of the argument. So, if your function + takes two arguments, you would do something like the following at + the top of your function:</para> <para> <example> @@ -43,39 +41,36 @@ ]]> </programlisting> </example> - NOTA: Argumentos podem ser passados pelo valor ou pela refer&ecirc;ncia. - Em ambos os casos voc&ecirc; ir&aacute; precisar passar &amp;(pval *) para - o getParameters. Se voc&ecirc; quer checar se n'th foi - enviado por refer&ecirc;ncia ou n&atilde;o, voc&ecirc; pode usar a seguinte fun&ccedil;&atilde;o. - ParameterPassedByReference(ht,n). Isto ir&aacute; retornar 1 ou 0. - - </para> - <simpara> - Quando voc&ecirc; muda qualquer argumento passado por refer&ecirc;ncia, - se eles foram emitidos por refer&ecirc;ncia ou pelo valor, voc&ecirc; - pode come&ccedil;ar a partir do par&acirc;metro chamado pela pval_destructor, - ou se for um ARRAY que voc&ecirc; quer adicionar, voc&ecirc; pode usar - fun&ccedil;&otilde;es similares &agrave;s do arquivo internal_functions.h que - manipula o return_value como um ARRAY.</simpara> - - <simpara> - Tamb&eacute;m se voc&ecirc; mudar um par&acirc;metro para IS_STRING tenha - certeza de primeiro atribuir a string e o tamanho dela ao - estrdup()'ed, e somente mais tarde alterar o tipo para - IS_STRING. Se voc&ecirc; quiser alterar a string de um par&acirc;metro - que j&aacute; &eacute; IS_STRING ou IS_ARRAY voc&ecirc; deve rodar o pval_destructor - primeiro.</simpara></sect2> + NOTE: Arguments can be passed either by value or by reference. In + both cases you will need to pass &amp;(pval *) to getParameters. If + you want to check if the n'th parameter was sent to you by + reference or not, you can use the function, + ParameterPassedByReference(ht,n). It will return either 1 or 0.</para> + + <simpara> + When you change any of the passed parameters, whether they are + sent by reference or by value, you can either start over with the + parameter by calling pval_destructor on it, or if it's an ARRAY + you want to add to, you can use functions similar to the ones in + internal_functions.h which manipulate return_value as an ARRAY.</simpara> + + <simpara> + Also if you change a parameter to IS_STRING make sure you first + assign the new estrdup()'ed string and the string length, and only + later change the type to IS_STRING. If you change the string of a + parameter which already IS_STRING or IS_ARRAY you should run + pval_destructor on it first.</simpara></sect2> <sect2 id="phpdevel-addfunc-varargs"> - <title>Argumentos das Vari&aacute;veis de Fun&ccedil;&otilde;es</title> + <title>Variable Function Arguments</title> <para> - Uma fun&ccedil;&atilde;o pode pegar um n&uacute;mero de vari&aacute;veis e argumentos. Se sua - fun&ccedil;&atilde;o precisa pegar 2 ou 3 argumentos, use as instru&ccedil;&otilde;es a seguir:</para> + A function can take a variable number of arguments. If your function can + take either 2 or 3 arguments, use the following:</para> <para> <example> - <title>Argumentos das Vari&aacute;veis de Fun&ccedil;&otilde;es</title> + <title>Variable function arguments</title> <programlisting role="c"> <![CDATA[ pval *arg1, *arg2, *arg3; @@ -90,13 +85,13 @@ </example></para></sect2> <sect2 id="phpdevel-addfunc-using-args"> - <title>Usando os Argumentos das Fun&ccedil;&otilde;es</title> + <title>Using the Function Arguments</title> <para> - O tipo de cada argumento é armazenado no campo do tipo pval. - Este tipo pode ser qualquer um dos seguintes: + The type of each argument is stored in the pval type field. This + type can be any of the following: <table> - <title>Tipos Internos do PHP</title> + <title>PHP Internal Types</title> <tgroup cols="2"> <tbody> <row> @@ -109,7 +104,7 @@ </row> <row> <entry>IS_LONG</entry> - <entry>Inteiro longo</entry> + <entry>Long integer</entry> </row> <row> <entry>IS_ARRAY</entry> @@ -117,7 +112,7 @@ </row> <row> <entry>IS_EMPTY</entry> - <entry>Nenhum(a)</entry> + <entry>None</entry> </row> <row> <entry>IS_USER_FUNCTION</entry> @@ -125,7 +120,7 @@ </row> <row> <entry>IS_INTERNAL_FUNCTION</entry> - <entry>?? (se alguma dessas n&atilde;o puder ser passada para uma fun&ccedil;&atilde;o - delete)</entry> + <entry>?? (if some of these cannot be passed to a function - delete)</entry> </row> <row> <entry>IS_CLASS</entry> @@ -140,10 +135,10 @@ </table></para> <para> - Se voc&ecirc; pegar um argumento de um tipo e quiser usar ele - como outro tipo, ou se voc&ecirc; somente quer for&ccedil;ar o argumento - a ser de um certo tipo, voc&ecirc; pode usar as seguintes fun&ccedil;&otilde;es - para convers&atilde;o: + If you get an argument of one type and would like to use it as + another, or if you just want to force the argument to be of a + certain type, you can use one of the following conversion + functions: <programlisting role="c"> <![CDATA[ @@ -156,10 +151,10 @@ </programlisting></para> <simpara> - Estas fun&ccedil;&otilde;es fazem convers&otilde;es in-place. Elas n&atilde;o retornam nada.</simpara> + These function all do in-place conversion. They do not return anything.</simpara> <para> - O argumento atual &eacute; armazenado na uni&atilde;o; os membros s&atilde;o: + The actual argument is stored in a union; the members are: <itemizedlist> <listitem><simpara>IS_STRING: arg1-&gt;value.str.val</simpara></listitem> <listitem><simpara>IS_LONG: arg1-&gt;value.lval</simpara></listitem> @@ -167,47 +162,45 @@ </itemizedlist></para></sect2> <sect2 id="phpdevel-addfunc-memmgmt"> - <title>Gerenciamento de Mem&oacute;ria nas Fun&ccedil;&otilde;es</title> + <title>Memory Management in Functions</title> <simpara> - Toda mem&oacute;rai necess&aacute;ria para uma fun&ccedil;&atilde;o deve ser alocada no - emalloc() ou estrdup(). Estes eventos de mem&oacute;ria s&atilde;o abstratos - e se parecem com as fun&ccedil;&otilde;es normais como a malloc() e strdup(). - A mem&oacute;ria deve ser liberada com efree().</simpara> - - <simpara> - H&aacute; dois tipos de mem&oacute;ria neste programa: a mem&oacute;ria que &eacute; - retornada para o parser em uma vari&aacute;vel, e a mem&oacute;ria que &eacute; - temporariamente armazenada na sua fun&ccedil;&atilde;o interna. Quando - voc&ecirc; atribui uma string a uma vari&aacute;vel que &eacute; retornada ao - parser voc&ecirc; preicsa ter certeza de primeiro alocar a mem&oacute;ria - com o emalloc() ou estrdup(). Esta mem&oacute;ria n&atilde;o DEVE ser - liberada por voc&ecirc;, a menos que uma mesma fun&ccedil;&atilde;o sobreescreva - a fun&ccedil;&atilde;o original (esta pr&aacute;tica de programa&ccedil;&atilde;o - n&atilde;o &eacute; muito boa).</simpara> - - <simpara> - Para toda mem&oacute;ria tempor&aacute;ria/permanente que voc&ecirc; necessitar - usar em suas fun&ccedil;&otilde;es voc&ecirc; deve usar as tr&ecirc;s fun&ccedil;&otilde;es - emalloc(), estrdup(), e efree(). Elas comportam-se EXATAMENTE - como suas fun&ccedil;&otilde;es contrapartes. Para qualquer uso da emalloc() ou estrdup() - voc&ecirc; deve usar efree() em algum ponto ou outro, a menos que ela - precise ficar at&eacute; o fim do programa; se n&atilde;o, haver&aacute; um escape de mem&oacute;ria. - O significado de "as fun&ccedil;&otilde;es comportam-se exatamente como suas contrapartes" - &eacute;: se voc&ecirc; usa efree() em algo que n&atilde;o era emalloc()'ed ou estrdup()'ed - voc&ecirc; deve come&ccedil;ar uma falha na segmenta&ccedil;&atilde;o. Ent&atilde;o por favor tome cuidado e - libere toda sua mem&oacute;ria desperdi&ccedil;ada.</simpara> - - <simpara> - Se voc&ecirc; compilar com "-DDEBUG", o PHP ir&aacute; imprimir uma lsita - de toda mem&oacute;ria que foi alocada e usada com o emalloc() e estrdup() - mas nunca foi liberda com o efree() quando ele acabar de rodar um - script especificado.</simpara></sect2> + Any memory needed by a function should be allocated with either + emalloc() or estrdup(). These are memory handling abstraction + functions that look and smell like the normal malloc() and + strdup() functions. Memory should be freed with efree().</simpara> + + <simpara> + There are two kinds of memory in this program: memory which is + returned to the parser in a variable, and memory which you need for + temporary storage in your internal function. When you assign a + string to a variable which is returned to the parser you need to + make sure you first allocate the memory with either emalloc() or + estrdup(). This memory should NEVER be freed by you, unless you + later in the same function overwrite your original assignment + (this kind of programming practice is not good though).</simpara> + + <simpara> + For any temporary/permanent memory you need in your + functions/library you should use the three emalloc(), estrdup(), + and efree() functions. They behave EXACTLY like their counterpart + functions. Anything you emalloc() or estrdup() you have to efree() + at some point or another, unless it's supposed to stick around + until the end of the program; otherwise, there will be a memory + leak. The meaning of "the functions behave exactly like their + counterparts" is: if you efree() something which was not + emalloc()'ed nor estrdup()'ed you might get a segmentation + fault. So please take care and free all of your wasted memory.</simpara> + + <simpara> + If you compile with "-DDEBUG", PHP will print out a list of all + memory that was allocated using emalloc() and estrdup() but never + freed with efree() when it is done running the specified script.</simpara></sect2> <sect2 id="phpdevel-addfunc-symtab"> - <title>Setando Vari&aacute;veis na Tabela de S&iacute;mbolos</title> + <title>Setting Variables in the Symbol Table</title> <para> - Um n&uacute;mero de macros est&aacute; dispon&iacute;vel para tornar f&aacute;cil o trabalho - de setar uma vari&aacute;vel na tabela de s&iacute;mbolos: + A number of macros are available which make it easier to set a + variable in the symbol table: <itemizedlist> <listitem><simpara>SET_VAR_STRING(name,value)</simpara></listitem> @@ -218,30 +211,29 @@ <warning> <para> - Tenha cuidado com a SET_VAR_STRING. Parte do valor deve ser - malloc'ed manualmente porque o c&oacute;digo do gerenciador de mem&oacute;ria - ir&aacute; tentar lbierar este ponteiro mais tarde. N&atilde;o passe - mem&oacute;ria est&aacute;tica alocada na SET_VAR_STRING. + Be careful with SET_VAR_STRING. The value part must be malloc'ed + manually because the memory management code will try to free this + pointer later. Do not pass statically allocated memory into a + SET_VAR_STRING. </para> </warning> <simpara> - A tabela de s&iacute;mbolos no PHP &eacute; implementada como uma tabela de misutra. - A toda hora, &amp;symbol_table &eacute; apontado para o 'principal' - s&iacute;mbolo da tabela, e active_symbol_table aponta para o - s&iacute;mbolo corrente da tabela (isto pode ser identificado no - in&iacute;cio, ou diferente, se voc&ecirc; estiver dentro da fun&ccedil;&atilde;o).</simpara> + Symbol tables in PHP are implemented as hash tables. At any + given time, &amp;symbol_table is a pointer to the 'main' symbol + table, and active_symbol_table points to the currently active + symbol table (these may be identical like in startup, or + different, if you're inside a function).</simpara> <para> - O exemplo a seguir usa o 'active_symbol_table'. Voc&ecirc; - deve substituir isto por &amp;symbol_table se voc&ecirc; - quer especificamente trabalhar com a tabela de s&iacute;mbolos - 'principal'. Tamb&eacute;m, as mesmas fun&ccedil;&otilde;es se apliquem &agrave; - arrays, como explicado a seguir.</para> + The following examples use 'active_symbol_table'. You should + replace it with &amp;symbol_table if you specifically want to work + with the 'main' symbol table. Also, the same functions may be + applied to arrays, as explained below.</para> <para> <example> - <title>Checando se $foo existe na tabela de s&iacute;mbolos</title> + <title>Checking whether $foo exists in a symbol table</title> <programlisting role="c"> <![CDATA[ if (hash_exists(active_symbol_table,"foo",sizeof("foo"))) { exists... } @@ -251,7 +243,7 @@ </example> <example> - <title>Procurando o tamanho de uma vari&aacute;vel em uma tabela de s&iacute;mbolos</title> + <title>Finding a variable's size in a symbol table</title> <programlisting role="c"> <![CDATA[ hash_find(active_symbol_table,"foo",sizeof("foo"),&pvalue); @@ -260,27 +252,24 @@ </programlisting> </example> - Os arrays no PHP s&atilde;o executadas usando as mesmas hashtables - que as tabelas de s&iacute;mbolos. Isto significa que as duas - fun&ccedil;&otilde;es abaixo tamb&eacute;m podem ser usadas para checar - vari&aacute;veis dentro de arrays.</para> + Arrays in PHP are implemented using the same hashtables as + symbol tables. This means the two above functions can also be + used to check variables inside arrays.</para> <simpara> - Se voc&ecirc; quiser definir um novo array numa tabela de s&iacute;mbolos, - voc&ecirc; deve fazer o seguinte. - </simpara> + If you want to define a new array in a symbol table, you should do + the following.</simpara> <simpara> - Primeiro, voc&ecirc; talvez queria checar se j&aacute; n&atilde;o existe um array - e abort&aacute;-lo se houver, usando o hash_exists() ou hash_find(). - </simpara> + First, you may want to check whether it exists and abort + appropriately, using hash_exists() or hash_find().</simpara> <simpara> - Ap&oacute;s, inicialize o array:</simpara> + Next, initialize the array:</simpara> <para> <example> - <title>Inicializando um novo array</title> + <title>Initializing a new array</title> <programlisting role="c"> <![CDATA[ pval arr; @@ -291,15 +280,15 @@ </programlisting> </example> - Este c&oacute;digo declara um novo array, chamado $foo, na tabela - de s&iacute;mbolos ativa. Este array est&aacute; vazio.</para> + This code declares a new array, named $foo, in the active symbol + table. This array is empty.</para> <simpara> - Aqui est&aacute; o c&oacute;digo apra adicionar novas entrads &agrave; ele:</simpara> + Here's how to add new entries to it:</simpara> <para> <example> - <title>Adicionando novas entradas ao array</title> + <title>Adding entries to a new array</title> <programlisting role="c"> <![CDATA[ pval entry; @@ -320,21 +309,21 @@ ]]> </programlisting> </example> - - Se voc&ecirc; quiser modificar o valor que foi inserido ao hash, voc&ecirc; - deve primeiro peg&aacute;-lo do hash. Para previnir overhead, voc&ecirc; pode - suprir a pval ** da fun&ccedil;&atilde;o adicionar do hash, e isto ir&aacute; - atualizar com o endere&ccedil;o pval * do elemento inserido dentro - do hash. Se o valor for &null; (como em todos os exemplos abaixo) - - aquele par&acirc;metro &eacute; ignorado.</para> + + If you'd like to modify a value that you inserted to a hash, you + must first retrieve it from the hash. To prevent that overhead, + you can supply a pval ** to the hash add function, and it'll be + updated with the pval * address of the inserted element inside the + hash. If that value is &null; (like in all of the above examples) - + that parameter is ignored.</para> <simpara> - hash_next_index_insert() usa mais ou menos a mesma l&oacute;gica que - "$foo[] = bar;" do PHP 2.0.</simpara> + hash_next_index_insert() uses more or less the same logic as + "$foo[] = bar;" in PHP 2.0.</simpara> <simpara> - Se voc&ecirc; est&aacute; construindo um array que retorna de uma fun&ccedil;&atilde;o, - voc&ecirc; pode inicializar o array como no exemplo abaixo:</simpara> + If you are building an array to return from a function, you can + initialize the array just like above by doing:</simpara> <programlisting role="c"> <![CDATA[ @@ -343,7 +332,7 @@ </programlisting> <simpara> - ...e ent&atilde;o adicionar valores com as fun&ccedil;&otilde;es do helper:</simpara> + ...and then adding values with the helper functions:</simpara> <programlisting role="c"> <![CDATA[ @@ -354,9 +343,8 @@ </programlisting> <para> - Claro, se a adi&ccedil;&atilde;o n&atilde;o terminou corretamente depois da - inicializa&ccedil;&atilde;o do array, voc&ecirc; provavelmente dever&aacute; - procurar pelo array primeiro: + Of course, if the adding isn't done right after the array + initialization, you'd probably have to look for the array first: <programlisting role="c"> <![CDATA[ @@ -368,22 +356,22 @@ </programlisting></para> <simpara> - Note que o hash_find recebe o ponteiro para um ponteiro pval, e - n&atilde;o um ponteiro pval.</simpara> + Note that hash_find receives a pointer to a pval pointer, and not + a pval pointer.</simpara> <simpara> - Assim como qualquer fun&ccedil;&atilde;o hash retorna SUCESSO ou FALHA (exceto - para o hash_exists(), que retorna um valor booleano verdadeiro).</simpara></sect2> + Just about any hash function returns SUCCESS or FAILURE (except + for hash_exists(), which returns a boolean truth value).</simpara></sect2> <sect2 id="phpdevel-addfunc-retsimple"> - <title>Retornando valores simples</title> + <title>Returning simple values</title> <simpara> - Um n&uacute;mero de macros est&atilde;o dispon&iacute;veis para fazer o retorno de - valores de uma fun&ccedil;&atilde;o ser muito mais f&aacute;cil.</simpara> + A number of macros are available to make returning values from a + function easier.</simpara> <para> - A macro RETURN_* ajusta todos os valores de retorno e do retorno - da fun&ccedil;&atilde;o: + The RETURN_* macros all set the return value and return from the + function: <itemizedlist> <listitem><simpara>RETURN</simpara></listitem> <listitem><simpara>RETURN_FALSE</simpara></listitem> @@ -406,34 +394,33 @@ </itemizedlist></para> <simpara> - As macros de string abaixo ser&atilde;o todas estrdup() passadas para - 's' argumento, ent&atilde;o voc&ecirc; pode seguramente liberar o argumento - ap&oacute;s chamar a macro, ou alternativamente usar uma mem&oacute;ria - est&aacute;tica alocada.</simpara> + The string macros above will all estrdup() the passed 's' + argument, so you can safely free the argument after calling the + macro, or alternatively use statically allocated memory.</simpara> <simpara> - Se sua fun&ccedil;&atilde;o retornar respostas booleanas de sucesso/erro, - sempre use RETURN_TRUE e RETURN_FALSE respectivamente.</simpara></sect2> + If your function returns boolean success/error responses, always + use RETURN_TRUE and RETURN_FALSE respectively.</simpara></sect2> <sect2 id="phpdevel-addfunc-retcomplex"> - <title>Retornando valores complexos</title> + <title>Returning complex values</title> <simpara> - Sua fun&ccedil;&atilde;o pode tamb&eacute;m retornar um tipo de dado complexo assim - como um objeto ou um array.</simpara> + Your function can also return a complex data type such as an + object or an array.</simpara> <para> - Retornando um objeto: + Returning an object: <orderedlist numeration="arabic"> - <listitem><simpara>Chamar o object_init(return_value).</simpara></listitem> - <listitem><para>Preencher isto com valores. A fun&ccedil;&atilde;o - dispon&iacute;vel para este prop&oacute;sito &eacute; listada a seguir.</para></listitem> - <listitem><para>Possivelmente, registrar a fun&ccedil;&atilde;o para este objeto. - A fim de obter os valores do objeto, a fun&ccedil;&atilde;o - teria que buscar "this" do active_symbol_table. Este - tipo dever&aacute; ser IS_OBJECT, e &eacute; basicamente uma tabela - hash regular (i.e., voc&ecirc; pode usar fun&ccedil;&otilde;es hash nos .value.ht). - O registrador atual da fun&ccedil;&atilde;o pode ser usado fazendo: + <listitem><simpara>Call object_init(return_value).</simpara></listitem> + <listitem><para>Fill it up with values. The functions available + for this purpose are listed below.</para></listitem> + <listitem><para> Possibly, register functions for this object. + In order to obtain values from the object, the function would + have to fetch "this" from the active_symbol_table. Its type + should be IS_OBJECT, and it's basically a regular hash table + (i.e., you can use regular hash functions on .value.ht). The + actual registration of the function can be done using: <programlisting role="c"> <![CDATA[ add_method( return_value, function_name, function_ptr ); @@ -443,7 +430,7 @@ </orderedlist></para> <para> - As fun&ccedil;&otilde;es usadas para povoar um objeto: + The functions used to populate an object are: <itemizedlist> <listitem><simpara>add_property_long( return_value, property_name, l ) - Add a property named 'property_name', of @@ -457,16 +444,16 @@ </itemizedlist></para> <para> - Retornando um array: + Returning an array: <orderedlist numeration="arabic"> - <listitem><simpara>Chamar array_init(return_value).</simpara></listitem> - <listitem><simpara>Preencher isto com valores. A fun&ccedil;&atilde;o dispon&iacute;vel - para este prop&oacute;sito &eacute; listada a seguir.</simpara></listitem> + <listitem><simpara>Call array_init(return_value).</simpara></listitem> + <listitem><simpara>Fill it up with values. The functions available + for this purpose are listed below.</simpara></listitem> </orderedlist></para> <para> - As fun&ccedil;&otilde;es usadas para povoar um array s&atilde;o: + The functions used to populate an array are: <itemizedlist> <listitem><simpara>add_assoc_long(return_value,key,l) - add associative entry with key 'key' and long value 'l'</simpara></listitem> @@ -489,13 +476,13 @@ </itemizedlist></para></sect2> <sect2 id="phpdevel-addfunc-reslist"> - <title>Usando a lista de recursos</title> + <title>Using the resource list</title> <simpara> - O PHP tem uma maneira padr&atilde;o de trator os v&aacute;rios tipos de - recursos. Isto substitui todos os local linked lists do PHP 2.0.</simpara> + PHP has a standard way of dealing with various types of + resources. This replaces all of the local linked lists in PHP 2.0.</simpara> <para> - Fun&ccedil;&otilde;es dispon&iacute;veis: + Available functions: <itemizedlist> <listitem><simpara>php3_list_insert(ptr, type) - returns the 'id' @@ -507,16 +494,16 @@ updates 'type' to the resource's type</simpara></listitem> </itemizedlist> - Tipicamente, estas fun&ccedil;&otilde;es s&atilde;o usadas para drivers SQL mas - elas podem ser usadas para qualquer otura coisa; para instanciar, - manusear arquivos de descritores.</para> + Typically, these functions are used for SQL drivers but they can + be used for anything else; for instance, maintaining file + descriptors.</para> <simpara> - Um c&oacute;digo t&iacute;pico &eacute; listado a seguir:</simpara> + Typical list code would look like this:</simpara> <para> <example> - <title>Adicionando novos recursos</title> + <title>Adding a new resource</title> <programlisting role="c"> <![CDATA[ RESOURCE *resource; @@ -530,7 +517,7 @@ </example> <example> - <title>Usando um recurso existente</title> + <title>Using an existing resource</title> <programlisting role="c"> <![CDATA[ pval *resource_id; @@ -549,7 +536,7 @@ </example> <example> - <title>Deletando um recurso existente</title> + <title>Deleting an existing resource</title> <programlisting role="c"> <![CDATA[ pval *resource_id; @@ -561,21 +548,21 @@ ]]> </programlisting> </example> - - O tipo de recurso deve ser registrado no php3_list.h, no enum - list_entry_type. Al&eacute;m disso, um deve adicionar c&oacute;digo para - qualquer novo tipo de recurso definido, em list.c's list_entry_destructor() - (mesmo se voc&ecirc; n&atilde;o tem nada para adicionar ao shutdown, voc&ecirc; - deve adicionar um caso em branco).</para></sect2> + + The resource types should be registered in php3_list.h, in enum + list_entry_type. In addition, one should add shutdown code for + any new resource type defined, in list.c's list_entry_destructor() + (even if you don't have anything to do on shutdown, you must add + an empty case).</para></sect2> <sect2 id="phpdevel-addfunc-prestable"> - <title>Usando o recurso persistente da tabela</title> + <title>Using the persistent resource table</title> <para> - O PHP tem uma maneira padr&atilde;o de armazenar recursos persistentes (i.e., - recursos que s&atilde;o mantidos dentre os hits). O primeiro m&oacute;dulo &agrave; usar - esta caracter&iacute;stica foi o m&oacute;dulo MySQL, e mSQL seguindo-os, ent&atilde;o - um pode pegar uma impress&atilde;o geral de como um recurso persistente - deve ser usado lendo mysql.c. As fun&ccedil;&otilde;es devem se parecem com as abaixo: + PHP has a standard way of storing persistent resources (i.e., + resources that are kept in between hits). The first module to use + this feature was the MySQL module, and mSQL followed it, so one + can get the general impression of how a persistent resource should + be used by reading mysql.c. The functions you should look at are: <simplelist> <member>php3_mysql_do_connect</member> @@ -584,31 +571,33 @@ </simplelist></para> <para> - A id&eacute;ia geral dos m&oacute;dulos persistentes &eacute; esta: + The general idea of persistence modules is this: <orderedlist numeration="arabic"> - <listitem><simpara>Codifique todos os seus m&oacute;dulos para trabalhar - com um recurso regular mecionados na se&ccedil;&atilde;o (9).</simpara></listitem> - <listitem><simpara>Codifique fun&ccedil;&otilde;es extras de conex&atilde;o para checar - se o recurso j&aacute; existe na lista de recursos persistentes. Se j&aacute; - existir, registre ela na lista de recursos regular como um ponteiro - para a lista de recursos persistentes (porque o 1., o resto do c&oacute;digo - dever&aacute; funcionar imediatamente). Se ela n&atilde;o existe, ent&atilde;o crie ela, adicione-a - a lista de recursos persistentes E adicione um ponteiro para ela vindo da - lista de recursos regular, mas na pr&oacute;xima conex&atilde;o, o recurso - ser&aacute; encontrado na lsita de recursos persitentes e ser&aacute; usado - sem ter que recri&aacute;-lo. Voc&ecirc; deve registrar estes recursos - com um tipo diferente (e.g. LE_MYSQL_LINK para link - n&atilde;o-persistente e LE_MYSQL_PLINK para um link persistente).</simpara></listitem> + <listitem><simpara>Code all of your module to work with the + regular resource list mentioned in section (9).</simpara></listitem> + <listitem><simpara>Code extra connect functions that check if the + resource already exists in the persistent resource list. If it + does, register it as in the regular resource list as a pointer to + the persistent resource list (because of 1., the rest of the code + should work immediately). If it doesn't, then create it, add it + to the persistent resource list AND add a pointer to it from the + regular resource list, so all of the code would work since it's + in the regular resource list, but on the next connect, the + resource would be found in the persistent resource list and be + used without having to recreate it. You should register these + resources with a different type (e.g. LE_MYSQL_LINK for + non-persistent link and LE_MYSQL_PLINK for a persistent link).</simpara></listitem> </orderedlist></para> <simpara> - Se voc&ecirc; ler o mysql.c, voc&ecirc; ir&aacute; notar que exceto pela fun&ccedil;&atilde;o - complexa de conex&atilde;o, nada no resto do m&oacute;dulo tem que ser mudado.</simpara> + If you read mysql.c, you'll notice that except for the more + complex connect function, nothing in the rest of the module has to + be changed.</simpara> <simpara> - A mesma rela&ccedil;&atilde;o existe para a lista de recursos regular e - para a lista de recursos persistentes, somente a 'list' &eacute; - substitu&iacute;da com 'plist':</simpara> + The very same interface exists for the regular resource list and + the persistent resource list, only 'list' is replaced with + 'plist':</simpara> <itemizedlist> <listitem><simpara>php3_plist_insert(ptr, type) - returns the 'id' @@ -621,295 +610,284 @@ </itemizedlist> <simpara> - Entretanto, &eacute; mais prov&aacute;vel que estas fun&ccedil;&otilde;es provariam ser - in&uacute;tils a n&atilde;o quando voc&ecirc; tenta implementar um m&oacute;dulo persistente. - Tipicamente, um seria usada de fato para a lista de recursos - persistentes que realmente seria uma tabela hash. Para instanciar, - nos m&oacute;dulos de conex&atilde;o MySQL/mSQL, quando existe uma chamada - pconnect() (conex&atilde;o persistente), a fun&ccedil;&atilde;o constr&oacute;i uma string fora - do host/usr/passwd que s&atilde;o passadas para a fun&ccedil;&atilde;o, e mistura o link - SQL com esta string como uma chave. Na pr&oacute;xima vez que algu&eacute;m - chamar a pconnect() com os mesmos host/user/passwd, a mesma chave - dever&aacute; ser gerada, e a fun&ccedil;&atilde;o encontraria o link SQL na - lista persistente.</simpara> - - <simpara> - At&eacute; que seja feita documenta&ccedil;&atilde;o adicional, voc&ecirc; deve olhar no - mysql.c ou msql.c para ver como deve usar as habilidades da - plist's tabela de hash.</simpara> - - <simpara> - Uma coisa importante a notar: recursos que v&atilde;o para para a lista - de recursos persistentes *N&Atilde;O" devem ser alocados no gerenciador - de mem&oacute;ria do PHP, i.e., N&Atilde;O devem ser criados com emalloc(), strdup(), etc. - O motivo para isto &eacute; simples - ao fim da requisi&ccedil;&atilde;o (fim do hit), - cada peda&ccedil;o de mem&oacute;ria que foi alocada usando o gerenciador - de mem&oacute;ria do PHP &eacute; deletado. Desde que a lista persistente - n&atilde;o &eacute; supostamente para ser deletada ao fim da requisi&ccedil;&atilde;o, - n&atilde;o se deve usar o gerenciador de mem&oacute;ria do PHP - para alocar recursos que v&atilde;o para ela.</simpara> - - <simpara> - Quando voc&ecirc; registra um recurso que vai ficar na lista persistente, - voc&ecirc; deve adicionar desconstrutores em ambas as listas persistente - e n&atilde;o-persistente. O desconstrutor na lista n&atilde;o-persistente - n&atilde;o deve fazer nada. J&aacute; o que est&aacute; na lista persistente - deve liberar corretamente qualquer recurso obtido por este - tipo (e.g. mem&oacute;ria, SQL links, etc). Assim como os recursos da lista - n&atilde;o-persistente, voc&ecirc; *DEVE* adicionar desconstrutores para - qualquer recurso, mesmo os que n&atilde;o requerem desconstrutores - e este desconstrutor ficaria vazio. Lembre-se, desde que - emalloc() e seus amigos n&atilde;o est&atilde;o sendo usados em conjunto - com a lista persistente, voc&ecirc; n&atilde;o deve usar o efree().</simpara></sect2> + However, it's more than likely that these functions would prove to + be useless for you when trying to implement a persistent module. + Typically, one would want to use the fact that the persistent + resource list is really a hash table. For instance, in the + MySQL/mSQL modules, when there's a pconnect() call (persistent + connect), the function builds a string out of the host/user/passwd + that were passed to the function, and hashes the SQL link with + this string as a key. The next time someone calls a pconnect() + with the same host/user/passwd, the same key would be generated, + and the function would find the SQL link in the persistent list.</simpara> + + <simpara> + Until further documented, you should look at mysql.c or msql.c to + see how one should use the plist's hash table abilities.</simpara> + + <simpara> + One important thing to note: resources going into the persistent + resource list must *NOT* be allocated with PHP's memory manager, + i.e., they should NOT be created with emalloc(), estrdup(), etc. + Rather, one should use the regular malloc(), strdup(), etc. The + reason for this is simple - at the end of the request (end of the + hit), every memory chunk that was allocated using PHP's memory + manager is deleted. Since the persistent list isn't supposed to + be erased at the end of a request, one mustn't use PHP's memory + manager for allocating resources that go to it.</simpara> + + <simpara> + When you register a resource that's going to be in the persistent + list, you should add destructors to it both in the non-persistent + list and in the persistent list. The destructor in the + non-persistent list destructor shouldn't do anything. The one in + the persistent list destructor should properly free any resources + obtained by that type (e.g. memory, SQL links, etc). Just like + with the non-persistent resources, you *MUST* add destructors for + every resource, even it requires no destruction and the + destructor would be empty. Remember, since emalloc() and friends + aren't to be used in conjunction with the persistent list, you + mustn't use efree() here either.</simpara></sect2> <sect2 id="phpdevel-addfunc-addcfg"> - <title>Adicionar diretivas de configura&ccedil;&atilde;o runtime</title> + <title>Adding runtime configuration directives</title> <para> - Muitas caracter&iacute;sticas do PHP podem ser configuradas em modo runtime. - Estas diretivas de configura&ccedil;&otilde;es podem aparecer no arquivo de - configura&ccedil;&atilde;o php3.ini, ou no caso na vers&atilde;o do m&oacute;dul para o Apache - nos arquivos .conf do Apache. A vantagem de t&ecirc;-las nos arquivos - .conf do Apache &eacute; que elas podem ser configuradas em apenas - um diret&oacute;rio. Isto significa que um diret&oacute;rio pode ter um certo - safemodeexecdir por exemplo, enquanto em outro diret&oacute;rio - pode ter um outro tipo de safemodeexecdir. Estas configura&ccedil;&otilde;es - s&atilde;o especiamente acess&iacute;veis quando um servidor suporta - m&uacute;ltiplos hosts virtuais.</para> + Many of the features of PHP can be configured at runtime. These + configuration directives can appear in either the designated + php3.ini file, or in the case of the Apache module version in the + Apache .conf files. The advantage of having them in the Apache + .conf files is that they can be configured on a per-directory + basis. This means that one directory may have a certain + safemodeexecdir for example, while another directory may have + another. This configuration granularity is especially handy when + a server supports multiple virtual hosts.</para> <para> - Os requisitos para adicionar uma diretiva: + The steps required to add a new directive: <orderedlist> - <listitem><simpara>Adicione a diretiva php3_ini_structure struct em mod_php3.h.</simpara></listitem> + <listitem><simpara>Add directive to php3_ini_structure struct in mod_php3.h.</simpara></listitem> - <listitem><simpara>No main.c, edite a fun&ccedil;&atilde;o php3_module_startup - e adicione a chamada apropriada cfg_get_string() ou - cfg_get_long().</simpara></listitem> - - <listitem><simpara>Adicione a diretiva, restri&ccedil;&otilde;es e coment&aacute;rios - &agrave; estrutura de php3_commands em mod_php3.c. Anote as partes - restritras. RSRC_CONF s&atilde;o diretivas que somente est&atilde;o presentes - nos arquivos .conf do Apache. Qualquer - diretiva OR_OPTIONS pode estar presente em qualquer lugar, - incluindo os arquivos .htaccess.</simpara></listitem> - - <listitem><simpara>Em php3takelhandler() ou php3flaghandler() - adicione a entrada apropriada para sua diretiva.</simpara></listitem> - - <listitem><simpara>Na se&ccedil;&atilde;o de configura&ccedil;&atilde;o da fun&ccedil;&atilde;o - _php3_info() em functions/info.c voc&ecirc; precisa adicionar - sua nova diretiva.</simpara></listitem> - - <listitem><simpara>E por &uacute;ltimo, voc&ecirc; naturalmente tem que - usar sua nova diretiva em algum lugar. Ela ser&aacute; - endere&ccedil;ada como php3_ini.directive.</simpara></listitem> + <listitem><simpara>In main.c, edit the php3_module_startup + function and add the appropriate cfg_get_string() or + cfg_get_long() call.</simpara></listitem> + + <listitem><simpara>Add the directive, restrictions and a comment + to the php3_commands structure in mod_php3.c. Note the + restrictions part. RSRC_CONF are directives that can only be + present in the actual Apache .conf files. Any OR_OPTIONS + directives can be present anywhere, include normal .htaccess + files.</simpara></listitem> + + <listitem><simpara>In either php3take1handler() or + php3flaghandler() add the appropriate entry for your directive.</simpara></listitem> + + <listitem><simpara>In the configuration section of the + _php3_info() function in functions/info.c you need to add your + new directive.</simpara></listitem> + + <listitem><simpara>And last, you of course have to use your new + directive somewhere. It will be addressable as + php3_ini.directive.</simpara></listitem> </orderedlist></para></sect2></sect1> <sect1 id="calling-user-functions"> - <title>Chamando Fun&ccedil;&otilde;es do Usu&aacute;rio</title> + <title>Calling User Functions</title> <simpara> - Para chamar fun&ccedil;&otilde;es do usu&aacute;rio de uma fun&ccedil;&atilde;o interna, voc&ecirc; - deve usar a fun&ccedil;&atilde;o <function>call_user_function</function>. + To call user functions from an internal function, you should use + the <function>call_user_function</function> function. </simpara> <simpara> - <function>call_user_function</function> retorna SUCESSO no sucesso, - e FALHA no caso de a fun&ccedil;&atilde;o n&atilde;o ter sido encontrada. - Voc&ecirc; deve checar este valor de retorno! Se ela retornar SUCESSO, - voc&ecirc; &eacute; respons&aacute;vel por destruir a retval pval por voc&ecirc; mesmo - (ou retornar ela como um valor de retorno da sua fun&ccedil;&atilde;o). - Se ela retornar FALHA, o valor da retval &eacute; indefinido, - e voc&ecirc; n&atilde;o deve mexe nisto. + <function>call_user_function</function> returns SUCCESS on success, + and FAILURE in case the function cannot be found. You should check + that return value! If it returns SUCCESS, you are responsible for + destroying the retval pval yourself (or return it as the return value + of your function). If it returns FAILURE, the value of retval is + undefined, and you mustn't touch it. </simpara> <simpara> - Todas as fun&ccedil;&otilde;es internas que chama fun&ccedil;&otilde;es - de usu&aacute;rio <emphasis>devem</emphasis> ser reentrantes. - Entre outras coisas, isto significa que ela n&atilde;o deve - usar vari&aacute;veis globais ou est&aacute;ticas. + All internal functions that call user functions + <emphasis>must</emphasis> be reentrant. Among other things, this + means they must not use globals or static variables. </simpara> <simpara> - <function>call_user_function</function> usa seis argumentos: + <function>call_user_function</function> takes six arguments: </simpara> <sect2 id="calling-user-functions.function-table"> <title>HashTable *function_table</title> <simpara> - Esta &eacute; a tabela hash onde a fun&ccedil;&atilde;o deve ser procurada. + This is the hash table in which the function is to be looked up. </simpara></sect2> <sect2 id="calling-user-functions.object"> <title>pval *object</title> <simpara> - Este &eacute; o ponteiro para um objeto em que a fun&ccedil;&atilde;o &eacute; invocada. - Ele dever &null; se a fun&ccedil;&atilde;o global &eacute; chamada. E se ele - n&atilde;o &eacute; &null; (i.e. este ponteio &eacute; um objeto), o argumento - function_table &eacute; ignorado, ao inv&eacute;s de pegar o hash do objeto. - O objeto *talvez* seja modificado pela fun&ccedil;&atilde;o que &eacute; invocada - nele (esta fun&ccedil;&atilde;o talvez tenha acesso a ele via $this). - Se por alguma raz&atilde;o voc&ecirc; n&atilde;o quer que isto aconte&ccedil;a, - envie uma c&oacute;pia do objeto ao inv&eacute;s dele. + This is a pointer to an object on which the function is invoked. + This should be &null; if a global function is called. If it's not + &null; (i.e. it points to an object), the function_table argument is + ignored, and instead taken from the object's hash. The object *may* + be modified by the function that is invoked on it (that function + will have access to it via $this). If for some reason you don't + want that to happen, send a copy of the object instead. </simpara></sect2> <sect2 id="calling-user-functions.function-name"> <title>pval *function_name</title> <simpara> - O nome da fun&ccedil;&atilde;o &agrave; ser chamada. Deve ser um pval do tipo - IS_STRING com function_name.str.val e function_name.str.len - enviando os valores apropriados. A function_name &eacute; modificada - por call_user_function() - que &eacute; convertido para letra min&uacute;scula. - Se voc&ecirc; precisa preservar caso, envie uma c&oacute;pia do - nome da fun&ccedil;&atilde;o ao inv&eacute;s dela. + The name of the function to call. Must be a pval of type + IS_STRING with function_name.str.val and function_name.str.len + set to the appropriate values. The function_name is modified by + call_user_function() - it's converted to lowercase. If you need to + preserve the case, send a copy of the function name instead. </simpara></sect2> <sect2 id="calling-user-functions.retval"> <title>pval *retval</title> <simpara> - Um ponteiro para uma estrutura do pval, onde o valor - retornada do a fun&ccedil;&atilde;o invocada &eacute; salvo. A estrutura deve - previamente alocada - <function>call_user_function</function> - N&Atilde;O aloque por voc&ecirc; mesmo. + A pointer to a pval structure, into which the return value of + the invoked function is saved. The structure must be previously + allocated - <function>call_user_function</function> does NOT allocate + it by itself. </simpara></sect2> <sect2 id="calling-user-functions.param-count"> <title>int param_count</title> <simpara> - O n&uacute;mero de par&acirc;metros passados &agrave; fun&ccedil;&atilde;o. + The number of parameters being passed to the function. </simpara></sect2> <sect2 id="calling-user-functions.params"> <title>pval *params[]</title> <simpara> - Um array de ponteiros para valores que v&atilde;o ser passados - como argumentos para a fun&ccedil;&atilde;o, o primeiro argumento come&ccedil;a no - offset 0, o segundo no offset 1, etc. O array &eacute; um array - de ponteiros para pval's; Os ponteiros s&atilde;o - enviados como-s&atilde;o para a fun&ccedil;&atilde;o, isto significa que se a fun&ccedil;&atilde;o - &eacute; modificada por seus argumentos, os valores originais s&atilde;o - alterados (passando por refer&ecirc;ncia). - Se voc&ecirc; n&atilde;o quer este comportamento, passe uma c&oacute;pia ao - inv&eacute;s do original. + An array of pointers to values that will be passed as arguments to the + function, the first argument being in offset 0, the second in offset + 1, etc. The array is an array of pointers to pval's; The pointers + are sent as-is to the function, which means if the function modifies + its arguments, the original values are changed (passing by reference). + If you don't want that behavior, pass a copy instead. </simpara></sect2></sect1> <sect1 id="phpdevel-errors"> - <title>Relatando erros</title> + <title>Reporting Errors</title> <simpara> - Para relatar erros de uma fun&ccedil;&atilde;o interna, voc&ecirc; deve chamar a - fun&ccedil;&atilde;o <function>php3_error</function>. Ela pega ao menos - dois par&acirc;metros -- o primeiro &eacute; o n&iacute;vel do erro, o segundo - &eacute; a string formatada para a mensagem de erro (como em uma - chamada padr&atilde;o <function>printf</function>), e os argumentos - seguintes s&atilde;o os par&acirc;metros para a string formatada. Os n&iacute;veis - de erro s&atilde;o: + To report errors from an internal function, you should call the + <function>php3_error</function> function. This takes at least two + parameters -- the first is the level of the error, the second is + the format string for the error message (as in a standard + <function>printf</function> call), and any following arguments + are the parameters for the format string. The error levels are: </simpara> <sect2 id="internal.e-notice"> <title>E_NOTICE</title> <simpara> - Avisos n&atilde;o s&atilde;o mostrados por padr&atilde;o, e indicam que o script - encontrou algo que poderia indicar um erro, mas que pode - tamb&eacute;m ter acontecido na execu&ccedil;&atilde;o do script. Por exemplo, - tentando acessar um valor de uma vari&aacute;vel que n&atilde;o foi setada, - ou chamando <function>stat</function> em um arquivo que n&atilde;o existe. + Notices are not printed by default, and indicate that the script + encountered something that could indicate an error, but could also + happen in the normal course of running a script. For example, + trying to access the value of a variable which has not been set, + or calling <function>stat</function> on a file that doesn't exist. </simpara> </sect2> <sect2 id="internal.e-warning"> <title>E_WARNING</title> <simpara> - Os avisos s&atilde;o mostrados por padr&atilde;o, mas n&atilde;o interrompem a - execu&ccedil;&atilde;o do script. Eles indicam um problema que deve ter - acontecido antes do script ser chamado. Por exemplo, - chamando <function>ereg</function> com uma express&atilde;o regular inv&aacute;lida. + Warnings are printed by default, but do not interrupt script + execution. These indicate a problem that should have been trapped + by the script before the call was made. For example, calling + <function>ereg</function> with an invalid regular expression. </simpara> </sect2> <sect2 id="internal.e-error"> <title>E_ERROR</title> <simpara> - Os erros tamb&eacute;m s&atilde;o mostrados por padr&atilde;o, e a execu&ccedil;&atilde;o do script &eacute; - interrompida ap&oacute;s a fun&ccedil;&atilde;o retornar. Ele indica erros que podem - n&atilde;o ser recuperados, como um problema de aloca&ccedil;&atilde;o de mem&oacute;ria. + Errors are also printed by default, and execution of the script is + halted after the function returns. These indicate errors that can + not be recovered from, such as a memory allocation problem. </simpara> </sect2> <sect2 id="internal.e-parse"> <title>E_PARSE</title> <simpara> - Erros do Parse deveriam unicamente ser gerados somente pelo parser. O c&oacute;digo &eacute; - listado aqui somente para a causa de integridade. + Parse errors should only be generated by the parser. The code is + listed here only for the sake of completeness. </simpara> </sect2> <sect2 id="internal.e-core-error"> <title>E_CORE_ERROR</title> <simpara> - Este &eacute; como um E_ERROR, exceto que ele &eacute; gerado pelo n&uacute;cleo - do PHP. Fun&ccedil;&otilde;es n&atilde;o devem gerar este tipo de erro. + This is like an E_ERROR, except it is generated by the core + of PHP. Functions should not generate this type of error. </simpara> </sect2> <sect2 id="internal.e-core-warning"> <title>E_CORE_WARNING</title> <simpara> - Este &eacute; como um E_WARNING, exceto que ele &eacute; gerado pelo n&uacute;cleo - do PHP. Fun&ccedil;&otilde;es n&atilde;o devem gerar este tipo de erro. + This is like an E_WARNING, except it is generated by the core + of PHP. Functions should not generate this type of error. </simpara> </sect2> <sect2 id="internal.e-compile-error"> <title>E_COMPILE_ERROR</title> <simpara> - Este &eacute; como um E_ERROR, exceto que ele &eacute; gerado pelo Zend Scripting - Engine. Fun&ccedil;&otilde;es n&atilde;o devem gerar este tipo de erro. + This is like an E_ERROR, except it is generated by the Zend Scripting + Engine. Functions should not generate this type of error. </simpara> </sect2> <sect2 id="internal.e-compile-warning"> <title>E_COMPILE_WARNING</title> <simpara> - Este &eacute; como um E_WARNING, exceto que ele &eacute; gerado pelo Zend Scripting - Engine. Fun&ccedil;&otilde;es n&atilde;o devem gerar este tipo de erro. + This is like an E_WARNING, except it is generated by the Zend Scripting + Engine. Functions should not generate this type of error. </simpara> </sect2> <sect2 id="internal.e-user-error"> <title>E_USER_ERROR</title> <simpara> - Este &eacute; como um E_ERROR, exceto que ele &eacute; gerado no c&oacute;digo PHP - usando a fun&ccedil;&atilde;o PHP <function>trigger_error</function>. - Fun&ccedil;&otilde;es n&atilde;o devem gerar este tipo de erro. + This is like an E_ERROR, except it is generated in PHP code by using + the PHP function <function>trigger_error</function>. Functions should + not generate this type of error. </simpara> </sect2> <sect2 id="internal.e-user-warning"> <title>E_USER_WARNING</title> <simpara> - Este &eacute; como um E_WARNING, exceto que ele &eacute; gerado no c&oacute;digo PHP - usando a fun&ccedil;&atilde;o PHP <function>trigger_error</function>. - Fun&ccedil;&otilde;es n&atilde;o devem gerar este tipo de erro. + This is like an E_WARNING, except it is generated by using the PHP + function <function>trigger_error</function>. Functions should not + generate this type of error. </simpara> </sect2> <sect2 id="internal.e-user-notice"> <title>E_USER_NOTICE</title> <simpara> - Este &eacute; como um E_NOTICE, exceto que ele &eacute; gerado no c&oacute;digo PHP - usando a fun&ccedil;&atilde;o PHP <function>trigger_error</function>. - Fun&ccedil;&otilde;es n&atilde;o devem gerar este tipo de erro. + This is like an E_NOTICE, except it is generated by using the PHP + function <function>trigger_error</function>. Functions should not + generate this type of error. </simpara> </sect2> <sect2 id="internal.e-all"> <title>E_ALL</title> <simpara> - Todos acima. Usando este n&iacute;vel de error_reporting voc&ecirc; - ver&aacute; todos os tipos de erros. + All of the above. Using this error_reporting level will show + all error types. </simpara> </sect2> Index: phpdoc/en/appendices/reserved.constants.core.xml diff -u phpdoc/en/appendices/reserved.constants.core.xml:1.3 phpdoc/en/appendices/reserved.constants.core.xml:1.4 --- phpdoc/en/appendices/reserved.constants.core.xml:1.3 Wed Nov 20 07:19:11 2002 +++ phpdoc/en/appendices/reserved.constants.core.xml Wed Nov 20 08:11:20 2002 @@ -1,15 +1,15 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <refentry id="reserved.constants.core"> <refnamediv> - <refname>Constantes Pr&eacute;-definidas do N&uacute;cleo</refname> - <refpurpose>Constantes definidas no n&uacute;cleo do PHP, Zend, e m&oacute;dulos SAPI</refpurpose> + <refname>Core Predefined Constants</refname> + <refpurpose>Constants defined in the PHP core, Zend, and SAPI modules</refpurpose> </refnamediv> <refsect1> - <title>Descri&ccedil;&atilde;o</title> + <title>Description</title> <simpara> - Estas constantes s&atilde;o definidas pelo n&uacute;cleo do PHP. Isto - inclui o PHP, a Zend engine, e os m&oacute;dulos SAPI. + These constants are defined by the PHP core. This includes PHP, + the Zend engine, and SAPI modules. </simpara> <variablelist> <varlistentry> Index: phpdoc/en/appendices/reserved.constants.standard.xml diff -u phpdoc/en/appendices/reserved.constants.standard.xml:1.5 phpdoc/en/appendices/reserved.constants.standard.xml:1.6 --- phpdoc/en/appendices/reserved.constants.standard.xml:1.5 Wed Nov 20 07:19:11 2002 +++ phpdoc/en/appendices/reserved.constants.standard.xml Wed Nov 20 08:11:20 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <!-- DOCNOTE: some constants listed here are also there at reference/info/constants.xml. Further decision is needed @@ -8,13 +8,13 @@ deleted from here to have a consistent standard constants list. --> <refentry id="reserved.constants.standard"> <refnamediv> - <refname>Constantes Padr&otilde;es Pr&eacute;-definidas</refname> - <refpurpose>Constantes definidas no PHP por padr&atilde;o</refpurpose> + <refname>Standard Predefined Constants</refname> + <refpurpose>Constants defined in PHP by default</refpurpose> </refnamediv> <refsect1> - <title>Descri&ccedil;&atilde;o</title> + <title>Description</title> <simpara> - Estas constantes s&atilde;o definidas por padr&atilde;o no PHP. + These constants are defined in PHP by default. </simpara> <variablelist> <varlistentry> Index: phpdoc/en/appendices/resources.xml diff -u phpdoc/en/appendices/resources.xml:1.28 phpdoc/en/appendices/resources.xml:1.29 --- phpdoc/en/appendices/resources.xml:1.28 Wed Nov 20 07:19:11 2002 +++ phpdoc/en/appendices/resources.xml Wed Nov 20 08:11:20 2002 @@ -1,23 +1,23 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.28 $ --> +<!-- $Revision: 1.29 $ --> <appendix id="resource"> - <title>Lsita de Tipos de Recursos</title> + <title>List of Resource Types</title> <para> - A seguir h&aacute; uma lista de fun&ccedil;&otilde;es que criam, usam e destr&oacute;em - recursos do PHP. A fun&ccedil;&atilde;o <function>is_resource</function> podem - ser usadas para determinar se a vari&aacute;vel &eacute; um recurso e - o <function>get_resource_type</function> ir&aacute; retornar o tipo - de recurso que est&aacute; sendo usado. + The following is a list of functions which create, use or destroy + PHP resources. The function <function>is_resource</function> can be + used to determine if a variable is a resource and + <function>get_resource_type</function> will return the type of + resource it is. <table> - <title>Tipos de Recursos</title> + <title>Resource Types</title> <tgroup cols="5"> <thead> <row> - <entry>Nome do Tipo de Recurso</entry> - <entry>Criado por</entry> - <entry>Usado por</entry> - <entry>Destro&iacute;do por</entry> - <entry>Defini&ccedil;&atilde;o</entry> + <entry>Resource Type Name</entry> + <entry>Created By</entry> + <entry>Used By</entry> + <entry>Destroyed By</entry> + <entry>Definition</entry> </row> </thead> <tbody> Index: phpdoc/en/appendices/tokens.xml diff -u phpdoc/en/appendices/tokens.xml:1.8 phpdoc/en/appendices/tokens.xml:1.9 --- phpdoc/en/appendices/tokens.xml:1.8 Wed Nov 20 07:19:11 2002 +++ phpdoc/en/appendices/tokens.xml Wed Nov 20 08:11:20 2002 @@ -1,18 +1,17 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> +<!-- $Revision: 1.9 $ --> <appendix id="tokens"> - <title>Lista dos Símbolos od Parse</title> + <title>List of Parser Tokens</title> <para> - V&aacute;rias partes da linguagem PHP s&atilde;o representadas internamente por - tipos como T_SR. Como estas sa&iacute;das de identificadores do PHP nos - erros do parse, como <literal>"Parse error: unexpected T_SR, expecting ',' or ';' in - script.php on line 10."</literal> + Various parts of the PHP language are represented internally by types like + T_SR. PHP outputs identifiers like this one in parse errors, like + <literal>"Parse error: unexpected T_SR, expecting ',' or ';' in script.php on line 10."</literal> </para> <para> - Você supostamente já deve sar o que T_SR significa. Para quem - não sabe, aqui vai uma tabela de seus identificadores, sintaxe-PHP - e as referências apropriadas colocadas no manual. + You're supposed to know what T_SR means. For everybody who doesn't + know that, here is a table with those identifiers, PHP-syntax and + references to the appropriate places in the manual. </para> <table> <title>Tokens</title>