Sync outdated files with EN (#10)

Co-authored-by: Maciej Sobaczewski <[email protected]>
php · Jun 26, 2024 · 27242e0 · 27242e0
1 parent f5fb1df
commit 27242e0
Show file tree

Hide file tree

Showing 14 changed files with 570 additions and 158 deletions.
diff --git a/reference/misc/functions/constant.xml b/reference/misc/functions/constant.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 8669246db504c414a0c0224c359929435ea922be Maintainer: sobak Status: ready -->
+<!-- EN-Revision: 6c3091b54b66181db5f81ef5afe1d2e8b6efdeac Maintainer: sobak Status: ready -->
 <!-- $Revision$ -->
+<!-- CREDITS: grzesiek -->
 <refentry xml:id="function.constant" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>constant</refname>
@@ -11,11 +12,11 @@
   &reftitle.description;
   <methodsynopsis>
    <type>mixed</type><methodname>constant</methodname>
-   <methodparam><type>string</type><parameter>nazwa</parameter></methodparam>
+   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   </methodsynopsis>
   <simpara>
    Zwraca wartość stałej określonej przez argument
-   <parameter>nazwa</parameter>.
+   <parameter>name</parameter>.
   </simpara>
   <simpara>
    <function>constant</function> jest przydatna jeżeli potrzebujesz
@@ -24,7 +25,8 @@
   </simpara>
   <simpara>
    Ta funkcja działa także ze <link
-   linkend="language.oop5.constants">stałymi klas</link>.
+   linkend="language.oop5.constants">stałymi klasy</link> i <link
+   linkend="language.types.enumerations">wyliczeniami</link>.
   </simpara>
  </refsect1>
 
@@ -33,7 +35,7 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>nazwa</parameter></term>
+     <term><parameter>name</parameter></term>
      <listitem>
       <para>
        Nazwa stałej.
@@ -47,24 +49,47 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Zwraca wartość stałej lub &null; jeżeli stała nie została
-   zdefiniowana.
+   Zwraca wartość stałej.
   </para>
  </refsect1>
 
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   Błąd o poziomie <constant>E_WARNING</constant> jest emitowany jeżeli
-   stała nie jest zdefiniowana.
+   Jeśli stała nie jest zdefiniowana, generowany jest wyjątek <classname>Error</classname>.
+   Przed PHP 8.0.0 w takim przypadku generowany był błąd poziomu <constant>E_WARNING</constant>.
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>8.0.0</entry>
+      <entry>
+       Jeśli stała nie jest zdefiniowana, <function>constant</function> zgłasza teraz
+       wyjątek <classname>Error</classname>; wcześniej generowany był <constant>E_WARNING</constant>
+       i zwracany był &null;.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
    <example>
-    <title>Przykład użycia <function>constant</function></title>
+    <title>Użycie <function>constant</function> ze Stałymi</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -88,6 +113,28 @@ $const = 'test';
 var_dump(constant('bar::'. $const)); // string(7) "foobar!"
 var_dump(constant('foo::'. $const)); // string(7) "foobar!"
 
+?>
+]]>
+    </programlisting>
+   </example>
+   <example>
+    <title>Użycie <function>constant</function> z enumami (od PHP 8.1.0)</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+enum Suit
+{
+    case Hearts;
+    case Diamonds;
+    case Clubs;
+    case Spades;
+}
+
+$case = 'Hearts';
+
+var_dump(constant('Suit::'. $case)); // enum(Suit::Hearts)
+
 ?>
 ]]>
     </programlisting>
@@ -101,6 +148,7 @@ var_dump(constant('foo::'. $const)); // string(7) "foobar!"
    <simplelist>
     <member><function>define</function></member>
     <member><function>defined</function></member>
+    <member><function>get_defined_constants</function></member>
     <member>Sekcja poświęcona <link linkend="language.constants">stałym</link></member>
    </simplelist>
   </para>

diff --git a/reference/misc/functions/define.xml b/reference/misc/functions/define.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: ef362e88b393422e1962c48c825aa1c6e65b380b Maintainer: sobak Status: ready -->
+<!-- EN-Revision: cdc9d28d334bbc08386fecf8aade66080004a9dd Maintainer: sobak Status: ready -->
 <!-- $Revision$ -->
+<!-- CREDITS: grzesiek -->
 <refentry xml:id="function.define" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>define</refname>
@@ -11,9 +12,9 @@
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>define</methodname>
-   <methodparam><type>string</type><parameter>nazwa</parameter></methodparam>
-   <methodparam><type>mixed</type><parameter>wartość</parameter></methodparam>
-   <methodparam choice="opt"><type>bool</type><parameter>wielkość_znaków</parameter><initializer>false</initializer></methodparam>
+   <methodparam><type>string</type><parameter>constant_name</parameter></methodparam>
+   <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>case_insensitive</parameter><initializer>&false;</initializer></methodparam>
   </methodsynopsis>
   <para>
    Tworzy nazwaną stałą w czasie wykonywania skryptu.
@@ -25,19 +26,26 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>nazwa</parameter></term>
+     <term><parameter>constant_name</parameter></term>
      <listitem>
       <para>
        Nazwa stałej.
       </para>
+      <note>
+       <para>
+        Możliwe jest <function>zdefiniowanie</function> stałych o zastrzeżonych
+        lub nawet nieprawidłowych nazwach, których wartość można (tylko) pobrać
+        za pomocą funkcji <function>constant</function>. Nie jest to jednak zalecane.
+       </para>
+      </note>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>wartość</parameter></term>
+     <term><parameter>value</parameter></term>
      <listitem>
       <para>
-       Wartość stałej. W PHP <parameter>wartość</parameter> musi być typu skalarnego
-       (<type>integer</type>, <type>float</type>, <type>string</type>, <type>boolean</type> lub &null;).
+       Wartość stałej. W PHP <parameter>value</parameter> musi być typu skalarnego
+       (<type>int</type>, <type>float</type>, <type>string</type>, <type>bool</type> lub &null;).
        W PHP 7 dozwolone są także tablice (typ <type>array</type>).
       </para>
 	  <warning>
@@ -49,14 +57,21 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>wielkość_znaków</parameter></term>
+     <term><parameter>case_insensitive</parameter></term>
      <listitem>
       <para>
        Jeżeli ustawione na &true;, stała będzie zdefiniowana bez zwracania uwagi
        na wielkosć znaków. Domyślne ustawienie bierze pod uwagę wielkość znaków; stałe 
        <literal>CONSTANT</literal> i <literal>Constant</literal> reprezentują
        różne wartości.
       </para>
+      <warning>
+       <simpara>
+        Definiowanie stałych niewrażliwych na wielkość liter jest przestarzałe od PHP 7.3.0.
+        Od PHP 8.0.0 tylko &false; jest akceptowalną wartością, przekazanie &true;
+        spowoduje wyświetlenie ostrzeżenia.
+       </simpara>
+      </warning>
       <note>
        <para>
         Stałe nieczułe na wielkość znaków są przechowywane jako zapisane małymi literami.
@@ -87,6 +102,19 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>8.0.0</entry>
+       <entry>
+        Przekazanie &true; do parametru <parameter>case_insensitive</parameter> emituje teraz
+        <constant>E_WARNING</constant>. Przekazanie &false; jest nadal dozwolone.
+       </entry>
+      </row>
+      <row>
+       <entry>7.3.0</entry>
+       <entry>
+        Parametr <parameter>case_insensitive</parameter> został zdeprecjonowany i zostanie usunięty w wersji 8.0.0.
+       </entry>
+      </row>
       <row>
        <entry>7.0.0</entry>
        <entry>
@@ -128,6 +156,37 @@ echo ZWIERZETA[1]; // wyświetli "kot"
     </programlisting>
    </example>
   </para>
+  <para>
+   <example>
+    <title>Stałe z nazwami zastrzeżonymi</title>
+    <para>
+     Ten przykład ilustruje <emphasis>możliwość</emphasis> zdefiniowania
+     stałej o tej samej nazwie, co
+     <link linkend="language.constants.predefined">stała magiczna</link>.
+     Ponieważ wynikające z tego zachowanie jest oczywiście mylące, 
+     nie zaleca się robienia tego w praktyce.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(defined('__LINE__'));
+var_dump(define('__LINE__', 'test'));
+var_dump(constant('__LINE__'));
+var_dump(__LINE__);
+?>
+]]>
+    </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+bool(false)
+bool(true)
+string(4) "test"
+int(5)
+]]>
+   </screen>
+   </example>
+  </para>
  </refsect1>
 
  <refsect1 role="seealso">
@@ -142,7 +201,6 @@ echo ZWIERZETA[1]; // wyświetli "kot"
  </refsect1>
 
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml

diff --git a/reference/misc/functions/defined.xml b/reference/misc/functions/defined.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: sobak Status: ready -->
+<!-- EN-Revision: 36e1d917ef7be36e8b4ff5193b456390061f2e21 Maintainer: sobak Status: ready -->
 <!-- $Revision$ -->
+<!-- CREDITS: grzesiek -->
 <refentry xml:id="function.defined" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>defined</refname>
@@ -11,10 +12,16 @@
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>defined</methodname>
-   <methodparam><type>string</type><parameter>nazwa</parameter></methodparam>
+   <methodparam><type>string</type><parameter>constant_name</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Sprawdza czy stała o podanej nazwie istnieje i jest zdefiniowana.
+   Sprawdza, czy stała o nazwie podanej jako parametr <parameter>constant_name</parameter>
+   jest zdefiniowana.
+  </para>
+  <para>
+   Ta funkcja działa również ze <link
+   linkend="language.oop5.constants">stałymi klas</link> i <link
+   linkend="language.types.enumerations">elementami enum</link>.
   </para>
   <note>
    <para>
@@ -31,7 +38,7 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>nazwa</parameter></term>
+     <term><parameter>constant_name</parameter></term>
      <listitem>
       <para>
        Nazwa stałej
@@ -45,7 +52,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Zwraca &true; jeżeli stała nazwana przez argument <parameter>nazwa</parameter>
+   Zwraca &true; jeżeli stała nazwana przez argument <parameter>constant_name</parameter>
    została zdefiniowana lub &false; w przeciwnym wypadku.
   </para>
  </refsect1>
@@ -58,11 +65,45 @@
     <programlisting role="php">
 <![CDATA[
 <?php
+
 /* Zwróć uwagę na apostrofy, to ważne. Ten przykład sprawdza
  * czy string 'TEST' jest nazwą stałej TEST */
 if (defined('TEST')) {
     echo TEST;
 }
+
+
+interface bar {
+    const test = 'foobar!';
+}
+
+class foo {
+    const test = 'foobar!';
+}
+
+var_dump(defined('bar::test')); // bool(true)
+var_dump(defined('foo::test')); // bool(true)
+
+?>
+]]>
+    </programlisting>
+   </example>
+   <example>
+    <title>Sprawdzanie przypadków Enum (od PHP 8.1.0)</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+enum Suit
+{
+    case Hearts;
+    case Diamonds;
+    case Clubs;
+    case Spades;
+}
+
+var_dump(defined('Suit::Hearts')); // bool(true)
+
 ?>
 ]]>
     </programlisting>
@@ -84,7 +125,6 @@ if (defined('TEST')) {
  </refsect1>
 
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml