constants.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: f4f96ef8b2a95283c92ea2183fe1dedf06f3ad22 Maintainer: grzesiek Status: ready -->
<!-- $Revision$ -->
 <chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook">
  <title>Constants</title>

  <simpara>
   Stała jest identyfikatorem (nazwą) prostej wartości. Jak sama
   nazwa wskazuje, wartość ta nie może się zmienić podczas wykonywania
   skryptu (z wyjątkiem <link linkend="language.constants.magic">
   stałych magicznych</link>, które w rzeczywistości nie są stałymi).
   Wielkość liter w stałych ma znaczenie. Zgodnie z konwencją, identyfikatory
   stałych są zawsze pisane wielkimi literami.
  </simpara>

  <note>
   <para>
    Przed PHP 8.0.0, stałe zdefiniowane przy użyciu funkcji <function>define</function>
    mogły nie uwzględniać wielkości liter.
   </para>
  </note>

  <para>
   Nazwa stałej podlega tym samym zasadom, co każda etykieta w PHP. 
   Prawidłowa nazwa stałej zaczyna się od litery lub podkreślenia,
   po których następuje dowolna liczba liter, cyfr lub podkreśleń.
   Jako wyrażenie regularne, może być wyrażona w następujący sposób:
   <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
  </para>
  <para>
   Możliwe jest zdefiniowanie za pomocą <function>define</function> satłych z
   zastrzeżonymi lub nawet nieważnymi nazwami, których wartość można pobrać tylko za
   pomocą funkcji <function>constant</function>. Nie jest to jednak zalecane.
  </para>
  &tip.userlandnaming;
  <para>
<!-- TODO Move into syntax section? -->
   <example>
    <title>Prawidłowe i nieprawidłowe nazwy stałych</title>
    <programlisting role="php">
<![CDATA[
<?php

// Prawidłowe nazwy stałych
define("FOO",     "something");
define("FOO2",    "something else");
define("FOO_BAR", "something more");

// Nieprawidłowe nazwy stałych
define("2FOO",    "something");

// Jest to poprawne, ale należy tego unikać:
// PHP może pewnego dnia dostarczyć magiczną stałą
// która zepsuje skrypt
define("__FOO__", "something"); 

?>
]]>
    </programlisting>
   </example>
  </para>
  <note>
   <simpara>
    Dla naszych celów litera to a-z, A-Z i znaki ASCII
    od 128 do 255 (0x80-0xff).
   </simpara>
  </note>

  <simpara>
   Podobnie jak &link.superglobals;, zakres stałej jest globalny.
   Dostęp do stałych można uzyskać z dowolnego miejsca w skrypcie bez względu na zakres.
   Aby uzyskać więcej informacji na temat zakresu, przeczytaj sekcję podręcznika dotyczącą
   <link linkend="language.variables.scope">zakresu zmiennej</link>.
  </simpara>

  <note>
   <simpara>
    Począwszy od PHP 7.1.0, stałe klasowe mogą deklarować widoczność protected
    lub private, czyniąc je dostępnymi tylko w hierarchicznym zakresie klasy,
    w której są zdefiniowane.
   </simpara>
  </note>

  <sect1 xml:id="language.constants.syntax">
   <title>Składnia</title>
   <simpara>
    Stałe mogą być definiowane za pomocą słowa kluczowego <literal>const</literal>,
    lub za pomocą funkcji <function>define</function>.
    Podczas gdy <function>define</function> pozwala na zdefiniowanie stałej
    dla dowolnego wyrażenia, słowo kluczowe <literal>const</literal> ma
    ograniczenia opisane w następnym akapicie.
    Gdy stała zostanie zdefiniowana, nigdy nie może zostać
    zmieniona lub niezdefiniowana.
   </simpara>
   <simpara>
    Podczas używania słowa kluczowego <literal>const</literal>,
    akceptowane są tylko wyrażenia skalarne (<type>bool</type>, <type>int</type>,
    <type>float</type> i <type>string</type>) oraz stałe
    <type>array</type>s zawierające tylko wyrażenia skalarne.
    Możliwe jest zdefiniowanie stałych jako <type>resource</type>,
    ale należy tego unikać, ponieważ może to spowodować nieoczekiwane wyniki.
   </simpara>
   <simpara>
    Dostęp do wartości stałej uzyskuje się po prostu poprzez podanie jej nazwy.
    W przeciwieństwie do zmiennych, stała <emphasis>nie</emphasis> jest poprzedzona
    <literal>$</literal>.
    Możliwe jest również użycie funkcji <function>constant</function> do
    odczytania wartości stałej, jeśli nazwa stałej jest uzyskiwana dynamicznie. 
    Użyj funkcji <function>get_defined_constants</function>, aby uzyskać listę
    wszystkich zdefiniowanych stałych.
   </simpara>

   <note>
    <simpara>
     Stałe i zmienne (globalne) znajdują się w innej przestrzeni nazw. 
     Oznacza to, że na przykład &true; i 
     <varname>$TRUE</varname> są generalnie różne.
    </simpara>
   </note>

   <simpara>
    Jeśli zostanie użyta niezdefiniowana stała, zostanie zgłoszony błąd <classname>Error</classname>.
    Przed PHP 8.0.0, niezdefiniowane stałe były interpretowane jako gołe słowo
    <type>string</type>, t.j. (CONSTANT vs "CONSTANT"). 
    To rozwiązanie awaryjne jest przestarzałe od PHP 7.2.0, a błąd poziomu
    <constant>E_WARNING</constant> jest zgłaszany, gdy tak się stanie.
    Przed PHP 7.2.0, zamiast tego zgłaszany był błąd poziomu
    <link linkend="ref.errorfunc">E_NOTICE</link>.
    Zobacz także wpis w podręczniku, dlaczego 
    <link linkend="language.types.array.foo-bar">$foo[bar]</link> jest
    błędne (chyba, że <literal>bar</literal> jest stałą).
    Nie dotyczy to <link
    linkend="language.namespaces.rules">(w pełni) kwalifikowanych stałych</link>,
    które zawsze zgłoszą błąd <classname>Error</classname>, jeśli są niezdefiniowane.
   </simpara>

   <note>
    <simpara>
     Aby sprawdzić, czy stała jest ustawiona, należy użyć funkcji <function>defined</function>.
    </simpara>
   </note>

   <para>
    To są różnice między stałymi i zmiennymi:
    <itemizedlist>
     <listitem>
      <simpara>
       Stałe nie mają przed sobą znaku dolara
       (<literal>$</literal>);
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Stałe mogą być definiowane i dostępne w dowolnym miejscu bez względu na
       zasady dotyczące zakresu zmiennych;
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Stałe nie mogą być przedefiniowane lub niezdefiniowane po ich ustawieniu;
       oraz
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Stałe mogą być oceniane tylko jako wartości skalarne lub tablice.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    <example>
     <title>Defining Constants</title>
     <programlisting role="php">
<![CDATA[
<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // zwróci "Hello world."
echo Constant; // Zgłosi błąd: Niezdefiniowana stała „Constant”
               // Przed PHP 8.0.0, zwróci „Constant” i wyświetla ostrzeżenie.
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Definiowanie Stałych przy użyciu słowa kluczowego <literal>const</literal></title>
     <programlisting role="php">
<![CDATA[
<?php
// Prosta wartość skalarna
const CONSTANT = 'Hello World';

echo CONSTANT;

// Wyrażenie skalarne
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
echo ANOTHER_CONST;

const ANIMALS = array('dog', 'cat', 'bird');
echo ANIMALS[1]; // zwróci "cat"

// Tablice stałej
define('ANIMALS', array(
    'dog',
    'cat',
    'bird'
));
echo ANIMALS[1]; // zwróci "cat"
?>
]]>
     </programlisting>
    </example>
   </para>

   <note>
    <para>
     W przeciwieństwie do definiowania stałych za pomocą <function>define</function>,
     stałe zdefiniowane za pomocą słowa kluczowego <literal>const</literal> muszą być
     zadeklarowane w zakresie najwyższego poziomu, ponieważ są definiowane w czasie kompilacji.
     Oznacza to, że nie można ich zadeklarować wewnątrz funkcji, pętli, instrukcji
     <literal>if</literal> lub bloków
     <literal>try</literal>/<literal>catch</literal>.
    </para>
   </note>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><link linkend="language.oop5.constants">Stałe Klasy</link></member>
     </simplelist>
    </para>
   </sect2>
  </sect1>
  
  <sect1 xml:id="language.constants.predefined">
   <title>Predefiniowane stałe</title>

   <simpara>
    PHP udostępnia dużą liczbę <link
    linkend="reserved.constants">predefiniowanych stałych</link> dla każdego
    uruchamianego skryptu. Wiele z tych stałych jest jednak tworzonych przez
    różne rozszerzenia i będą one obecne tylko wtedy, gdy te rozszerzenia
    są dostępne, albo poprzez dynamiczne ładowanie, albo dlatego, że zostały
    skompilowane.
   </simpara>
  </sect1>

  <sect1 xml:id="language.constants.magic">
   <title>Stałe magiczne</title>
   <para>
    Istnieje kilka magicznych stałych, które zmieniają się w zależności
    od tego, gdzie są używane. Na przykład wartość stałej
    <constant>__LINE__</constant> zależy od linii, w której jest
    używana w skrypcie. Wszystkie te „magiczne” stałe są rozwiązywane w
    czasie kompilacji, w przeciwieństwie do zwykłych stałych, które są rozwiązywane w czasie wykonywania.
    Te specjalne stałe nie uwzględniają wielkości liter i są następujące:
   </para>
   <para>
    <table>
     <title>Stałe magiczne PHP</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>&Name;</entry>
        <entry>&Description;</entry>
       </row>
      </thead>
      <tbody>
       <row xml:id="constant.line">
        <entry><constant>__LINE__</constant></entry>
        <entry>
         Bieżący numer linii pliku.
        </entry>
       </row>
       <row xml:id="constant.file">
        <entry><constant>__FILE__</constant></entry>
        <entry>
         Pełna ścieżka i nazwa pliku z rozwiązanymi dowiązaniami symbolicznymi.
         W przypadku użycia wewnątrz include, zwracana jest nazwa dołączonego pliku.
        </entry>
       </row>
       <row xml:id="constant.dir">
        <entry><constant>__DIR__</constant></entry>
        <entry>
         Katalog pliku. Jeśli użyta jest wewnątrz include,
         zwracany jest katalog dołączonego pliku. Jest to równoważne
         dla <literal>dirname(__FILE__)</literal>. Nazwa katalogu
         nie zawiera końcowego ukośnika, chyba że jest to katalog główny.
        </entry>
       </row>
       <row xml:id="constant.function">
        <entry><constant>__FUNCTION__</constant></entry>
        <entry>
         Nazwa funkcji lub <literal>{domknięcie}</literal> dla funkcji anonimowych.
        </entry>
       </row>
       <row xml:id="constant.class">
        <entry><constant>__CLASS__</constant></entry>
        <entry>
         Nazwa klasy. Nazwa klasy zawiera przestrzeń nazw, w której
         została zadeklarowana (n.p. <literal>Foo\Bar</literal>).
         W przypadku użycia wewnątrz metody traita,
         <constant>__CLASS__</constant> jest nazwą klasy, w której trait jest
         używany.
        </entry>
       </row>
       <row xml:id="constant.trait">
        <entry><constant>__TRAIT__</constant></entry>
        <entry>
         Nazwa traita. Nazwa traita zawiera przestrzeń nazw, w 
         której został zadeklarowany (e.g. <literal>Foo\Bar</literal>).
        </entry>
       </row>
       <row xml:id="constant.method">
        <entry><constant>__METHOD__</constant></entry>
        <entry>
         Nazwa metody klasy.
        </entry>
       </row>
       <row xml:id="constant.property">
        <entry><constant>__PROPERTY__</constant></entry>
        <entry>
         Ważne tylko wewnątrz
         <link linkend="language.oop5.property-hooks">haku właściwości</link>.
         Jest ona równa nazwie właściwości.
        </entry>
       </row>
       <row xml:id="constant.namespace">
        <entry><constant>__NAMESPACE__</constant></entry>
        <entry>
         Nazwa bieżącej przestrzeni nazw.
        </entry>
       </row>
       <row xml:id="constant.coloncolonclass">
        <entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
        <entry>
         W pełni kwalifikowana nazwa klasy.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><link linkend="language.oop5.basic.class.class">::class</link></member>
      <member><function>get_class</function></member>
      <member><function>get_object_vars</function></member>
      <member><function>file_exists</function></member>
      <member><function>function_exists</function></member>
     </simplelist>
    </para>
   </sect2>

  </sect1>
 </chapter>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->