Funkce

Skripty mohou být dlouhé a komplikované. Nikoho asi nebaví psát je stále znovu, navíc tím značně stoupá riziko chyb. Naštěstí to není třeba: skript, který chcete použít znovu na jiném místě, můžete pojmenovat a pak opětovně volat. Taková sekce kódu se nazývá funkce.

Funkce si můžete napsat sami, existuje však také obrovské množství již hotových funkcí, které můžete využít. Z tohoto hlediska budete při práci v Drupalu používat 3 okruhy funkcí:

1. Vaše vlastní funkce.
2. „Hotové“ funkce PHP.
3. „Hotové“ funkce Drupalu - tato skupina je součástí tzv. Drupal API (Application Programming Interface).

Pozn. - Kdybychom v tomto návodu postupovali „učebnicově“, přišel by výklad funkcí, neřkuli Drupal API, na řadu mnohem později. Protože nám však jde o to, abychom PHP ukázali pokud možno na praktických příkladech Drupalu, je účelné zařadit kapitolu o funkcích co nejdříve - k zajímavým ukázkám „ze života“ budeme totiž potřebovat jak funkce PHP, tak Drupalu.

S některými funkcemi jste se již v tomto návodu setkali a také jste je použili. Byly to funkce var_dump() a var_export() pro zjištění hodnot proměnných (jsou to funkce PHP) a dále funkce dpm(), což je funkce Drupalu (poskytovaná modulem Devel).

Vlastní funkce: zpráva pro tento den

Nejdříve si vyzkoušejte velmi jednoduchý příklad na vytvoření (neboli deklarace) vlastní funkce. Bude to Zpráva pro tento den; příslušnou novou funkci nazveme daily_message. Níže uvedený kód vložte do těla vašeho testovacího bloku:

<h4>Zpráva pro tento den</h4>
<?php
function daily_message() {
  $message = 'Ať se vám dnes všechno daří!';
  return $message;
}
?>

Všimněte si syntaxe zápisu. Samotný název funkce tvoří malá písmena a podtržítka. Za názvem funkce následují kulaté závorky, kam lze umístit tzv. argumenty funkce (vysvětlíme si později, zatím nebudou třeba). Dále následují složené závorky, které uzavírají veškerý kód dané funkce.

Na výstupu vidíte pouze nadpis Zpráva pro tento den. Samotná zpráva Ať se vám dnes všechno daří! se zatím nezobrazuje, a to ze dvou důvodů:

1. Příkaz return pouze vrací výsledek, ale nic nevypisuje.

2. Funkce sice byla vytvořena, ale zatím nebyla volána (nemohla se vykonat). Proto by byl výsledek stejný, i kdybyste příkaz return ve funkci nahradili příkazem print.

Nyní zavoláme vytvořenou funkci a vypíšeme její výsledek. Celý kód bude vypadat následovně:

<h4>Zpráva pro tento den</h4>
<?php
function daily_message() {
  $message = 'Ať se vám dnes všechno daří!';
  return $message;
}
print daily_message();
?>

Výsledek:

Vyzkoušejte si, že výsledek bude stejný, i když v kódu funkci nejprve zavoláte a pak teprve deklarujete - na pořadí totiž nezáleží:

<h4>Zpráva pro tento den</h4>
<?php
print daily_message();
function daily_message() {
  $message = 'Ať se vám dnes všechno daří!';
  return $message;
}
?>

Argument funkce

Řekli jsme si, že funkce může pracovat s argumenty, které se zpracovávají zleva doprava. Argumenty umožňují přizpůsobit výstup aktuálnímu vstupu. Například Zpráva pro tento den, kterou tvoříme, by měla být závislá na aktuálním dnu. Řekněme, že chceme vytvořit upozornění pro zaměstnance firmy, která se vztahují vždy k aktuálnímu dni v týdnu. Nyní k tomu učiníme první krok: vytvoříme si proměnnou $day, která obsahuje informaci o dni v týdnu, a předáme jí funkci daily_message jako argument.

<h4>Zpráva pro tento den</h4>
<?php
function daily_message($day) {
  $message = '<p>Dnes je ' . $day . '<br />Ať se vám dnes všechno daří!</p>';
  return $message;
}
$day = 'Pondělí';
print daily_message($day);
$day = 'Úterý';
print daily_message($day);
?>

Výsledek:

Argumentů může být více. Příklad - přidáme argument $name, který bude reprezentovat název uživatelského účtu (zatím nepracujeme se skutečným uživatelským účtem, pouze si uvádíme příklad na předání argumentu):

<h4>Zpráva pro tento den</h4>
<?php
function daily_message($name, $day) {
  $message = '<p>Jste přihlášeni k účtu ' . $name . '. Dnes je ' . $day . '. <br />Ať se vám dnes všechno daří!</p>';
  return $message;
}
$day = 'Pondělí';
$name = 'Zdeněk';
print daily_message($name, $day);
 
$name = 'Zdeněk';
$day = 'Úterý';
print daily_message($name, $day);
?>

Výsledek:

Předání argumentu hodnotou vs. odkazem

Příklad, který jsme si ukázali, je takzvané předání argumentu hodnotou.

To znamená, že když napíšeme $day = 'Pondělí', ovlivníme hodnotu proměnné $day pouze ve funkci, která má $day jako svůj argument.

Zopakujme si syntaxi zápisu:

nazev_funkce($argument1, $argument2, ...)

Je třeba vědět, že existuje také druhý typ předání argumentu - odkazem.

Vyjadřuje se zápisem, kdy před argumentem ve funkci je uveden ampressand: &.

nazev_funkce(&$argument1, &$argument2, ...)

Pokud předáte hodnotu odkazem, můžete hodnotu dané proměnné ve funkci změnit, přičemž změna se projeví i mimo tuto funkci. To je velmi užitečné, ale může to být i nebezpečné, pokud neznáte (neuvědomíte si) dopady této změny.

Příklad (do kódu jsme přidali nejen ampressand pro předání argumentu odkazem, ale také tagy <strong> </strong> pro zvýraznění výstupu). Jednotlivé kroky jsou dále vysvětleny v komentářích kódu:

<h4>Zpráva pro tento den</h4>
<?php
// Přiřadíme hodnotu proměnné $name
$name = 'Zdeněk';
 
// Deklarujeme funkci daily_message, kde se argument $name předává odkazem
 
function daily_message(&$name, $day) {
  $message = '<p>Jste přihlášeni k účtu ' . '<strong>' . $name . '</strong>' . '. Dnes je ' . $day . '. <br />Ať se vám dnes všechno daří!</p>';
 
  // Zde změníme hodnotu proměnné $name
  $name = 'Martina';
  return $message;
}
$day = 'Pondělí';
print daily_message($name, $day);
 
$day = 'Úterý';
print daily_message($name, $day);
?>

Výsledek:

Všimněte si, že při prvním zavolání funkce se použije původní hodnota, kterou jsme proměnné $name přiřadili (Zdeněk). Pak však funkce při svém běhu hodnotu změní, takže při druhém volání funkce je hodnota $name jiná (Martina).

V tuto chvíli není třeba, abyste uměli předání argumentu odkazem bravurně používat. Je ale důležité, abyste se měli na pozoru, pokud se s ním setkáte. Na základě uvedeného příkladu si dovedete jistě představit situaci, kdy dojde k záměně uživatelů na webu (netýká se přímo našeho příkladu, protože nepracujeme se skutečnými uživateli). Pokud k tomu dojde nechtěně, má to samozřejmě fatální následky pro bezpečnost webu.

Pro lepší pochopení srovnejte s příkladem, kdy předáte argument hodnotou (jediný rozdíl je vypuštění ampressandu v deklaraci funkce):

<h4>Zpráva pro tento den</h4>
<?php
// Přiřadíme hodnotu proměnné $name
$name = 'Zdeněk';
// Deklarujeme funkci daily_message, kde se argument $name předává hodnotou
function daily_message($name, $day) {
  $message = '<p>Jste přihlášeni k účtu ' . '<strong>' . $name . '</strong>' . '. Dnes je ' . $day . '. <br />Ať se vám dnes všechno daří!</p>';
  //Zde změníme hodnotu proměnné $name. Protože se však argument $name předává hodnotou, tato změna se mimo danou funkci neprojeví.
  $name = 'Martina';
  return $message;
}
$day = 'Pondělí';
print daily_message($name, $day);
 
$day = 'Úterý';
print daily_message($name, $day);
?>

Výsledek:

Proměnná $name má stále hodnotu Zdeněk, bez ohledu na to, co se s ní stalo uvnitř funkce daily_message.

Výchozí hodnoty argumentů, nepovinné argumenty

Argumentům lze přiřadit výchozí hodnoty, které se použijí, pokud jim nedodáme jinou hodnotu.

Příklad zápisu:

<?php
function daily_message($name = 'Lukáš') {
  return $name;
}
 
print daily_message();
?>

Výsledek:

Z výsledku je patrné, že pokud je argumentu přiřazena nějaká výchozí hodnota, nemusí se argument při volání funkce uvádět - je to argument nepovinný. Výchozí hodnota může být i prázdná.

Pozor:
Nepovinné argumenty následují vždy za argumenty povinnými.

Správný zápis:

function daily_message($name, $day = "") {
}
 
// $name je povinný argument
// $day je nepovinný, s výchozí prázdnou hodnotou

Špatný zápis:

function daily_message($day = "", $name) {
}
 
// $day i $name jsou povinné argumenty<br><br>

Pokud bychom totiž v tomto případě volali funkci daily_message('Lukáš'), předáme řetězec Lukáš argumentu $day, načež argument $name zůstane prázdný - PHP nás upozorní, že chybí druhý argument.

Funkce PHP, manuál PHP

Funkce PHP můžete použít kdekoliv, kde používáte odpovídající verzi PHP, která danou funkci obsahuje.

Ukážeme si to na našem příkladu Zpráva pro tento den, kdy zjistíme a použijeme skutečnou hodnotu dne v týdnu. K tomu využijeme funkci PHP date().

Když si otevřete manuál PHP, můžete funkci vyhledat v poli Search. Udělejte to a získáte popis funkce a návod na její použití včetně příkladů. Do manuálu PHP byste se měli dívat vždy, když používáte funkci PHP, kterou rutinně neovládáte.

Vysvětleme si, co nám říká zápis. Pozor - toto je syntaxe definice v manuálu, nikoli zápisu kódu v PHP:

string date ( string $format [, int $timestamp = time() ] )

• Funkce vrací řetězec (string).
• Funkce má 2 argumenty:
  • Povinný argument $format, kterému je třeba přiřadit hodnotu typu řetězec, reprezentuje formát data. Níže na stránce PHP manuálu je uvedeno, které hodnoty máte použít, v závislosti na tom, jaký výstup potřebujete.
  • Argument $timestamp, který což je celé číslo (integer, v zápisu PHP int) reprezentující čas, se kterým bude funkce pracovat. Je ve tvaru časové známky unixu (počet vteřin od 1. 1. 1970). Pokud argument při volání funkce neuvedeme, funkce použije výchozí hodnotu, kterou získá z jiné funkce, totiž time(). V praxi to znamená, že pokud nezadáte čas, použije se aktuální čas. Hranaté závorky v definici vyjadřují, že tento argument při volání funkce nemusíte zadávat.

Kód příkladu Zpráva pro tento den nyní změňte následovně:

<h4>Zpráva pro tento den</h4>
<?php
$name = 'Zdeněk';
function daily_message($name, $day) {
  $message = '<p>Jste přihlášeni k účtu ' . '<strong>' . $name . '</strong>' . '. Dnes je ' . '<strong>' . $day . '</strong>' . '. <br />Ať se vám dnes všechno daří!</p>';
  return $message;
}
$day = date('l');
print daily_message($name, $day);
?>

Výsledek závisí na skutečném aktuálním dni v týdnu - pokud je například čtvrtek, dostanete výstup:

Volání funkce date() ve tvaru date('l'); vypíše textově aktuální den v týdnu.
Zatím sice v angličtině, což ale brzy změníme a použijeme k tomu pro změnu funkci Drupalu.

Funkce Drupalu, Drupal API

Pro přeložení názvu dne v týdnu do češtiny použijeme funkci Drupalu t().

Tuto funkci byste samozřejmě marně hledali v manuálu PHP - není to vestavěná funkce jazyka PHP. Najdete ji v referenční příručce Drupal API.

Na adrese http://api.drupal.org/api/drupal/includes%21bootstrap.inc/function/t/7 najdete definici funkce t(), vysvětlení a odkazy na příklady použití v Drupalu.

Nyní upravíme náš příklad. Aby mohl překlad fungovat, je třeba, abyste měli Drupal lokalizovaný do češtiny. Předpokládáme také, že máte češtinu nastavenou jako výchozí jazyk.

Kód příkladu upravte následovně:

<h4>Zpráva pro tento den</h4>
<?php
$name = 'Zdeněk';
function daily_message($name, $day) {
  $message = '<p>Jste přihlášeni k účtu ' . '<strong>' . $name . '</strong>' . '. Dnes je ' . '<strong>' . $day . '</strong>' . '. <br />Ať se vám dnes všechno daří!</p>';
  return ($message);
}
// Datum vypíšeme pomocí funkce t(), která se postará o překlad:
$day = t(date('l'));
print daily_message($name, $day);
?>

Výsledek (za předpokladu, že je právě čtvrtek):

Dostanete překlad řetězce Thursday, protože jste použili funkci pro překlad t() a protože řetězec Thursday je v Drupalu přeložený.

Může se však také stát, že potřebujete v češtině řetězec, který zatím v Drupalu přeložený není.

V tom případě obalíte funkcí t() řetězec, který potřebujete přeložit. Funkce t() zajistí, že řetězec bude k dispozici k překladu - v administraci na adrese admin/config/regional/language jej pak můžete přeložit.