Functionsکردارەکان

Imagine you build a website with ten pages. Every page must show the same greeting, work out the same total, or do the same check. You could copy the same ten lines of code into all ten pages. But then one small mistake must be fixed ten times, and sooner or later you forget one page.

وا دابنێ تۆڕگەیەک (Website) دروست دەکەیت کە دە لاپەڕەتۆڕی (Web page) تێدایە. لە هەموو لاپەڕەکاندا دەبێت هەمان سڵاو پیشان بدرێت، هەمان کۆ هەژمار بکرێت، یان هەمان پشکنین بکرێت. دەتوانیت هەمان دە دێڕ کۆد لە هەر دە لاپەڕەکەدا کۆپی بکەیت. بەڵام ئەو کاتە هەر هەڵەیەکی بچووک دەبێت دە جار چاک بکرێتەوە و زوو یان درەنگ یەکێک لە لاپەڕەکان لەبیر دەکەیت.

A function solves this. You write the code once, give it a name, and then use it as many times as you like, from any place in your page. If you find a mistake, you fix it in one place, and every page that uses the function is fixed too.

کردار ئەم کێشەیە چارەسەر دەکات. کۆدەکە تەنها یەک جار دەنووسیت، ناوێکی لێ دەنێیت، پاشان هەر چەند جار بتەوێت لە هەر شوێنێکی لاپەڕەکەتەوە بەکاری دەهێنیت. ئەگەر هەڵەیەکت تێدا دۆزییەوە، تەنها لە یەک شوێن چاکی دەکەیتەوە و هەموو ئەو لاپەڕانەی ئەو کردارە بەکاردەهێنن خۆیان چاک دەبنەوە.

The course lecture says it in one sentence: the real power of PHP comes from its functions. PHP itself comes with more than a thousand ready-made functions, and you can add as many of your own as you need.

وانەی کۆرسەکە لە یەک ڕستەدا دەیڵێت: هێزی ڕاستەقینەی PHP لە کردارەکانیدایە. PHP خۆی زیاتر لە هەزار کرداری ئامادە لەگەڵدایە و تۆش دەتوانیت هەر چەندت پێویست بێت کرداری خۆتی بۆ زیاد بکەیت.

This lecture opens the chapter Functions and Arrays. Here you learn to define, name and call your own functions, to send values in and get values back, and to fix the most common function errors. The following lectures use functions together with arrays.

ئەم وانەیە سەرەتای بەشی کردارەکان و ڕیزەکەکانە (Array). لێرەدا فێر دەبیت چۆن کردارەکانی خۆت بناسێنیت، ناویان لێ بنێیت و بانگیان بکەیت، چۆن نرخەکان بنێریتە ناویان و نرخەکان لێیان وەربگریتەوە و چۆن باوترین هەڵەکانی پەیوەست بە کردارەوە چاک بکەیتەوە. وانەکانی دواتر ئەمانە لەگەڵ ڕیزەکەکاندا بەکاردەهێنن.

A function is a named code block: a group of statements inside curly braces { }, with a name on top. The code inside does not run by itself. It runs only when you call the function by its name, and you may call it from anywhere in the page, as many times as you need.

کردار بلۆکێکی کۆدی (Code block) ناونراوە: کۆمەڵێک ڕستە (Statement) لەناو کەوانەی لوولی { }، کە ناوێکیان لەسەرە. کۆدی ناو ئەم بلۆکە خۆی بە خۆی جێبەجێ ناکرێت. تەنها کاتێک بانگی بکەیت بە ناوەکەیەوە جێبەجێ دەکرێت و دەتوانیت لە هەر شوێنێکی لاپەڕەکەوە و هەر چەند جار پێویست بێت بانگی بکەیت.

A function can take information in (through its parameters), do some work, and give a result back (its return value). Both are optional: a function may take no information at all, and it may give nothing back.

کردارێک دەتوانێت زانیاری وەربگرێت (لە ڕێگەی پارامیتەرەکانەوە)، کارێک بکات و ئەنجامێک بگەڕێنێتەوە (نرخە گەڕاوەکەی). هەردووکیان ئارەزوومەندانەن: لەوانەیە کردارێک هیچ زانیارییەک وەرنەگرێت و هیچیش نەگەڕێنێتەوە.

You call both kinds in exactly the same way: the name, then parentheses ( ) with any values inside. Here are a few built-in functions at work:

هەردوو جۆرەکە بە هەمان شێوە بانگ دەکرێن: ناوەکە، پاشان کەوانە ( ) و ئەو نرخانەی دەتەوێت بیاننێریت لەناویدا. ئەمەش چەند کرداری ئامادە لە کاتی کارکردندا:

The rest of this lecture is about user-defined functions. You will meet many more built-in functions later, for example the string functions in the Strings lecture and count() in the Arrays lecture.

بەشەکانی تری ئەم وانەیە باسی کردارە دروستکراوەکان دەکەن. دواتر زۆر کرداری ئامادەی تریش دەناسیت، بۆ نموونە کردارەکانی زنجیرەنووسە لە وانەی تایبەتی خۆیاندا و count() لە وانەی داهاتوودا.

To create a function you write a function definition. It has four parts:

بۆ دروستکردنی کردارێک، ناساندنێکی کردار دەنووسیت. چوار بەشی هەیە:

Here is the first example from the course lecture. It defines a function greet() and then calls it three times. Each call prints "Hello" once:

ئەمە یەکەم نموونەی وانەی کۆرسەکەیە. کردارێک بە ناوی greet() دەناسێنێت و پاشان سێ جار بانگی دەکات. هەر بانگکردنێک یەک جار "Hello" چاپ دەکات:

Using a function always takes two steps. First you create (define) it. Then you call it by its name. Defining alone does nothing that you can see.

بەکارهێنانی کردارێک هەمیشە دوو هەنگاوە. یەکەم، دروستی دەکەیت (دەیناسێنیت). دووەم، بە ناوەکەیەوە بانگی دەکەیت. تەنها ناساندن هیچ شتێکی بینراو ناکات.

To prove it, here is a page that defines a function but never calls it. The web browser receives an empty page:

بۆ سەلماندنی ئەمە، ئەمە لاپەڕەیەکە کە کردارێک دەناسێنێت بەڵام هەرگیز بانگی ناکات. تۆڕگەڕەکە لاپەڕەیەکی بەتاڵ وەردەگرێت:

A function name is an identifier, so it follows rules much like variable names, but without a $ in front:

ناوی کردارێک ناسێنەرێکە (Identifier)، بۆیە یاساکانی وەک ناوی گۆڕاوەکان وایە، بەڵام بەبێ $ لە پێشیەوە:

For names made of several words, two styles are common: camelCase (addFive, calculateTotal) and snake_case (your_name, calculate_total). The course material uses both. Pick one style for a project and keep to it.

بۆ ئەو ناوانەی لە چەند وشەیەک پێکهاتوون، دوو شێواز باون: camelCase (addFive، calculateTotal) و ⁦snake_case⁩ (your_name، calculate_total). کەرەستەکانی کۆرسەکە هەردووکیان بەکاردەهێنن. بۆ هەر پڕۆژەیەک یەک شێواز هەڵبژێرە و پابەندی بە.

Function names and variable names also live in separate worlds: a function x() and a variable $x can exist side by side without any clash (you will see this in the return example).

ناوی کردارەکان و ناوی گۆڕاوەکان هەروەها لە دوو جیهانی جیاوازدان: کردارێک بە ناوی x() و گۆڕاوێک بە ناوی $x دەتوانن پێکەوە هەبن بێ ئەوەی تێکبگیرێن (ئەمە لە نموونەی returnدا دەبینیت).

PHP does not care about capital letters in function names. If you define addFive(), you can call it as addfivE() or ADDFIVE(), and PHP runs the same function. In other words, function names are not case-sensitive.

PHP گوێ بە پیتی گەورە و بچووک نادات لە ناوی کردارەکاندا. ئەگەر addFive() بناسێنیت، دەتوانیت بە addfivE() یان ADDFIVE() بانگی بکەیت و PHP هەمان کردار جێبەجێ دەکات. بە واتایەکی تر، ناوی کردارەکان هەستیار بە قەبارەی پیت (Case-sensitive) نین.

Variables are different: their names are case-sensitive. $name and $Name are two separate variables:

گۆڕاوەکان جیاوازن: ناویان هەستیار بە قەبارەی پیتە. $name و $Name دوو گۆڕاوی جیاوازن:

Example 1 of Lab 4 ("Function without argument") tries to define and call a function named Print. This is the code as it appears on the lab sheet, with the <?php tags added:

نموونەی یەکەمی تاقیگەی ٤ ("کردار بەبێ ئارگیومێنت") هەوڵ دەدات کردارێک بە ناوی Print بناسێنێت و بانگی بکات. ئەمە کۆدەکەیە وەک لە پەڕەی تاقیگەکەدا هاتووە، لەگەڵ زیادکردنی <?php:

PHP stops before running anything. There are three problems:

PHP پێش جێبەجێکردنی هیچ شتێک ڕادەوەستێت. سێ کێشە هەیە:

The fix: give the function a name that is not reserved and says what it does, call it with that same name, and use straight quotes. (We also correct "with out" to "without".)

چارەسەرەکە: ناوێک بدە بە کردارەکە کە پارێزراو نەبێت و بڵێت چی دەکات، بە هەمان ناو بانگی بکە و نیشانەی گوتەی ڕاست بەکاربهێنە. (هەروەها "⁦with out⁩" دەکەینە "⁦without".⁩)

To call a function, write its name, then parentheses, then a semicolon: greet();. If the function has parameters, put the arguments inside the parentheses, separated by commas: add(20, 30);.

بۆ بانگکردنی کردارێک، ناوەکەی بنووسە، پاشان کەوانە، پاشان خاڵبۆر: greet();. ئەگەر کردارەکە پارامیتەری هەبێت، ئارگیومێنتەکان لەناو کەوانەکەدا بنووسە و بە کۆما لێکیان جیا بکەرەوە: add(20, 30);.

A call can stand alone as a statement, as above. It can also be part of a bigger expression, for example echo add(20, 30); or $total = add(20, 30);. You will see why this is useful in Return values.

بانگکردنی کردار دەتوانێت بە تەنها ڕستەیەک بێت، وەک سەرەوە. هەروەها دەتوانێت بەشێک بێت لە دەربڕینێکی (Expression) گەورەتر، بۆ نموونە echo add(20, 30); یان $total = add(20, 30);. لە نرخە گەڕاوەکاندا دەبینیت ئەمە بۆچی بەسوودە.

A function runs only when it is called, and you may call it from anywhere in the page, as often as you like. Every call runs the whole body again, from its first line.

کردار تەنها کاتێک جێبەجێ دەکرێت کە بانگ بکرێت و دەتوانیت لە هەر شوێنێکی لاپەڕەکەوە و هەر چەند جار بتەوێت بانگی بکەیت. هەر بانگکردنێک هەموو ناوەڕۆکەکە لە یەکەم دێڕییەوە دووبارە جێبەجێ دەکاتەوە.

Look at this example from the course lecture. The call myfunction(); on line 3 comes before the definition of myfunction() on line 5. It still works:

سەیری ئەم نموونەیەی وانەی کۆرسەکە بکە. بانگکردنی myfunction(); لە دێڕی ٣ پێش ناساندنی myfunction() لە دێڕی ٥ هاتووە. کەچی هەر کار دەکات:

Why does this work? Before PHP runs a file, it first reads the whole file. While reading, it notes every function that is defined at the top level of the file, that is, not inside an if block and not inside another function. So when line 3 runs, PHP already knows myfunction(). The lab program in the scope section also calls its two functions before it defines them.

بۆچی کار دەکات؟ پێش ئەوەی PHP فایلێک جێبەجێ بکات، سەرەتا هەموو فایلەکە دەخوێنێتەوە. لە کاتی خوێندنەوەدا، هەموو ئەو کردارانە تۆمار دەکات کە لە ئاستی سەرەوەی فایلەکەدا ناسێنراون، واتە نە لەناو بلۆکێکی ifدا و نە لەناو کردارێکی تردا. بۆیە کاتێک دێڕی ٣ جێبەجێ دەکرێت، PHP پێشتر myfunction() دەناسێت. بەرنامەکەی تاقیگەکەش لە بەشی globalدا هەردوو کردارەکەی پێش ناساندنیان بانگ دەکات.

If a definition sits inside an if block (or inside another function), PHP creates the function only when that block actually runs. Calling it earlier is an error:

ئەگەر ناساندنەکە لەناو بلۆکێکی ifدا بێت (یان لەناو کردارێکی تردا)، PHP تەنها ئەو کاتە کردارەکە دروست دەکات کە ئەو بلۆکە بەڕاستی جێبەجێ دەکرێت. بانگکردنی پێش ئەو کاتە هەڵەیە:

If you call a name that PHP does not know, for example because of a typing mistake, PHP stops the script with a fatal error. Nothing after that line runs:

ئەگەر ناوێک بانگ بکەیت کە PHP نایناسێت، بۆ نموونە بەهۆی هەڵەیەکی نووسینەوە، PHP دەسنووسەکە بە هەڵەیەکی کوشندە (Fatal error) ڕادەگرێت. هیچ شتێکی دوای ئەو دێڕە جێبەجێ ناکرێت:

If you forget the parentheses, PHP does not see a call at all. It thinks greet is the name of a constant, and stops with a different message:

ئەگەر کەوانەکان لەبیر بکەیت، PHP هیچ بانگکردنێک نابینێت. وا دەزانێت greet ناوی نەگۆڕێکە (Constant) و بە پەیامێکی تر ڕادەوەستێت:

Both messages tell you the line number. Read them carefully: the name in the message is exactly what PHP saw in your code. You will meet a real case of this error in Lab fix 2.

هەردوو پەیامەکە ژمارەی دێڕەکەت پێدەڵێن. بە وردی بیانخوێنەرەوە: ئەو ناوەی لە پەیامەکەدایە ڕێک ئەوەیە کە PHP لە کۆدەکەتدا بینیویەتی. نموونەیەکی ڕاستەقینەی ئەم هەڵەیە لە چاککردنی دووەمی تاقیگەدا دەبینیت.

To make a function more useful, you can send information into it. You do this with parameters. A parameter is just like a variable: it has a $ name, and inside the function you use it like any other variable. Parameters are written after the function name, inside the parentheses. You can have as many as you like; separate them with commas.

بۆ ئەوەی کردار بەسوودتر بێت، دەتوانیت زانیاری بنێریتە ناوی. ئەمە بە پارامیتەرەکان دەکەیت. پارامیتەر ڕێک وەک گۆڕاو وایە: ناوێکی بە $ـەوە هەیە و لەناو کردارەکەدا وەک هەر گۆڕاوێکی تر بەکاری دەهێنیت. پارامیتەرەکان دوای ناوی کردارەکە و لەناو کەوانەکەدا دەنووسرێن. هەر چەندێکت بوێت دەتوانیت دایان بنێیت؛ بە کۆما لێکیان جیا بکەرەوە.

The two words are easy to mix up. The course slides also mix them ("argument variables", "the function's argument may have a default value"). Here is the precise difference:

ئەم دوو وشەیە بە ئاسانی تێکەڵ دەبن. سلایدەکانی کۆرسەکەش تێکەڵیان دەکەن (⁦"argument variables⁩"، "⁦the function's argument may have a default value"⁩). ئەمە جیاوازییە وردەکەیە:

The lecture's next example has one parameter, $firstName. Each call sends a different name, so the same function prints a different line each time:

نموونەی دواتری وانەکە یەک پارامیتەری هەیە، $firstName. هەر بانگکردنێک ناوێکی جیاواز دەنێرێت، بۆیە هەمان کردار هەر جارە دێڕێکی جیاواز چاپ دەکات:

With two parameters, the function receives two values. PHP matches them by position: the first argument goes into the first parameter, the second argument into the second parameter.

بە دوو پارامیتەر، کردارەکە دوو نرخ وەردەگرێت. PHP بەپێی شوێن پێکیان دەگەیەنێت: ئارگیومێنتی یەکەم دەچێتە ناو پارامیتەری یەکەم و ئارگیومێنتی دووەم دەچێتە ناو پارامیتەری دووەم.

The course slides show the same idea with a function add(). It receives two numbers, prints them, adds them, and prints the result:

سلایدەکانی کۆرسەکە هەمان بیرۆکە بە کردارێک بە ناوی add() پیشان دەدەن. دوو ژمارە وەردەگرێت، چاپیان دەکات، کۆیان دەکاتەوە و ئەنجامەکە چاپ دەکات:

More about this in Variables inside functions. Notice also that this add() prints its result instead of giving it back; you will see why returning is often better in Echo or return?.

زیاتر لەم بارەیەوە لە گۆڕاوەکان لەناو کردارەکاندادا بخوێنەرەوە. هەروەها سەرنج بدە کە ئەم add()ـە ئەنجامەکەی چاپ دەکات لە جیاتی ئەوەی بیگەڕێنێتەوە؛ لە echo یان return؟دا دەبینیت بۆچی گەڕاندنەوە زۆرجار باشترە.

Lab 4, Example 3 ("PHP functions with multiple arguments") defines a function with two parameters. It prints the sum, the remainder (modulus, %) and the quotient (/) of two numbers. On the lab sheet it looks like this:

نموونەی سێیەمی تاقیگەی ٤ ("کردارەکان لە PHPـدا بە چەند ئارگیومێنت") کردارێک بە دوو پارامیتەر دەناسێنێت. کۆ، پاشماوە (Modulus) (%) و ئەنجامی دابەشکردنی (/) دوو ژمارە چاپ دەکات. لە پەڕەی تاقیگەکەدا بەم شێوەیەیە:

There are three problems, and PHP shows them one at a time:

سێ کێشە هەیە و PHP یەک لە دوای یەک پیشانیان دەدات:

Here is the fixed version. It calls the function by its real name, uses straight quotes, ends each line with <br>, and calls the function twice to show a remainder and a decimal result:

ئەمە وەشانی چاککراوەکەیە. کردارەکە بە ناوی ڕاستەقینەی خۆی بانگ دەکات، نیشانەی گوتەی ڕاست بەکاردەهێنێت، هەر دێڕێک بە <br> کۆتایی پێدەهێنێت و دوو جار کردارەکە بانگ دەکات بۆ ئەوەی پاشماوە و ئەنجامێکی کەرتی پیشان بدات:

For comparison, this is what the lab code prints with the right name but without the <br> tags:

بۆ بەراوردکردن، ئەمە ئەوەیە کە کۆدی تاقیگەکە بە ناوی ڕاست بەڵام بەبێ <br> چاپی دەکات:

What if the number of arguments does not match the number of parameters? PHP treats the two cases differently:

ئەگەر ژمارەی ئارگیومێنتەکان لەگەڵ ژمارەی پارامیتەرەکان یەک نەگرێتەوە چی دەبێت؟ PHP بە دوو شێوەی جیاواز مامەڵە لەگەڵ ئەم دوو حاڵەتە دەکات:

The message tells you everything: which function, how many arguments were passed (1), on which line, and how many were expected (exactly 2). If a parameter may sometimes be left out, give it a default value, as the next section shows.

پەیامەکە هەموو شتێکت پێدەڵێت: کام کردار، چەند ئارگیومێنت نێردراوە ⁦(1)⁩، لە کام دێڕدا و چەند چاوەڕوان دەکرا (ڕێک ⁦2⁩). ئەگەر پارامیتەرێک هەندێک جار نەنێردرێت، نرخێکی بنەڕەتی بدەرێ، وەک لە بەشی داهاتوودا دەبینیت.

A parameter can have a default value. You write it with = in the definition. If the caller does not send an argument for that parameter, the function uses the default value instead.

پارامیتەر دەتوانێت نرخێکی بنەڕەتیی هەبێت. لە ناساندنەکەدا بە = دەینووسیت. ئەگەر بانگکەر هیچ ئارگیومێنتێک بۆ ئەو پارامیتەرە نەنێرێت، کردارەکە لە جیاتی ئەو نرخە بنەڕەتییەکە بەکاردەهێنێت.

Only the second call, setHeight(), sends nothing, so only that call uses the default 50. The other three calls send their own value, which replaces the default.

تەنها بانگکردنی دووەم، setHeight()، هیچ نانێرێت، بۆیە تەنها ئەو بانگکردنە نرخی بنەڕەتی ⁦50⁩ بەکاردەهێنێت. سێ بانگکردنەکەی تر نرخی خۆیان دەنێرن، کە جێگەی نرخە بنەڕەتییەکە دەگرێتەوە.

A function can mix required parameters (no default) and optional ones (with a default). Put the optional ones after the required ones. If an optional parameter comes first, its default can never be used, because the caller must still fill it to reach the required one after it. PHP 8 warns you about this:

کردارێک دەتوانێت پارامیتەری پێویست (بێ نرخی بنەڕەتی) و ئارەزوومەندانە (بە نرخی بنەڕەتی) تێکەڵ بکات. ئارەزوومەندانەکان دوای پێویستەکان دابنێ. ئەگەر پارامیتەرێکی ئارەزوومەندانە یەکەم بێت، هەرگیز نرخە بنەڕەتییەکەی بەکارنایەت، چونکە بانگکەر دەبێت هەر پڕی بکاتەوە بۆ ئەوەی بگاتە پارامیتەرە پێویستەکەی دوایەوە. ⁦PHP 8⁩ لەمە ئاگادارت دەکاتەوە:

Lab 4, Example 5 ("Setting Default Values for Function Parameters") gives $param the default value NULL. On the lab sheet, a lonely { follows the two calls:

نموونەی پێنجەمی تاقیگەی ٤ ("دانانی نرخە بنەڕەتییەکان بۆ پارامیتەرەکانی کردار") نرخی بنەڕەتی NULL دەدات بە $param. لە پەڕەی تاقیگەکەدا، {ێکی تەنها دوای هەردوو بانگکردنەکە هاتووە:

Every { must have a matching }. PHP reached the end of the file (line 7) while the { from line 6 was still open, so it rejected the whole file: even the correct lines above it never run. Fix: delete the stray {. While we are here, we also move the function's closing } onto its own line. On the lab sheet it hides at the end of the print line, which is legal but easy to miss.

هەر {ێک دەبێت }ێکی هاوتای هەبێت. PHP گەیشتە کۆتایی فایلەکە (دێڕی ٧) لە کاتێکدا {ی دێڕی ٦ هێشتا کراوە بوو، بۆیە هەموو فایلەکەی ڕەت کردەوە: تەنانەت دێڕە دروستەکانی سەرەوەش هەرگیز جێبەجێ ناکرێن. چارەسەر: {ە زیادەکە بسڕەوە. لە هەمان کاتدا }ی کۆتایی کردارەکە دەبەینە سەر دێڕێکی جیا. لە پەڕەی تاقیگەکەدا لە کۆتایی دێڕی printدا شاراوەتەوە، کە دروستە بەڵام بە ئاسانی نابینرێت.

About print: it outputs one string, just like echo, and it always returns the number 1. The differences between the two are covered in Output with echo and print.

دەربارەی print: یەک زنجیرەنووسە دەردەخات، ڕێک وەک echo و هەمیشە ژمارە 1 دەگەڕێنێتەوە. جیاوازییەکانی نێوانیان لە وانەی echo و printدا باس کراون.

Often a function takes its arguments, does some computation, and returns a value. The keyword return does this. The returned value becomes the value of the call itself, right where the call stands in your code.

زۆرجار کردارێک ئارگیومێنتەکانی وەردەگرێت، هەژمارێک دەکات و نرخێک دەگەڕێنێتەوە. وشە کلیلەییەکەی return ئەم کارە دەکات. نرخە گەڕاوەکە دەبێتە نرخی خودی بانگکردنەکە، ڕێک لەو شوێنەی بانگکردنەکەی تێدایە لە کۆدەکەتدا.

Lab 4, Example 4 ("PHP Functions returning value") stores the returned value in a variable first, then prints it:

نموونەی چوارەمی تاقیگەی ٤ ("کردارەکان لە PHPـدا کە نرخێک دەگەڕێننەوە") سەرەتا نرخە گەڕاوەکە لە گۆڕاوێکدا هەڵدەگرێت، پاشان چاپی دەکات:

Because a call with return simply is a value, you can use it anywhere a value is allowed: store it, print it, calculate with it, or even pass it to another call:

چونکە بانگکردنێک کە returnی تێدایە بە سادەیی نرخێکە، دەتوانیت لە هەر شوێنێکدا بەکاری بهێنیت کە نرخ ڕێگەپێدراوە: هەڵیبگرە، چاپی بکە، هەژماری پێ بکە، یان تەنانەت بینێرە بۆ بانگکردنێکی تر:

A function with no return statement still gives something back: the special value NULL (null), which means no value:

کردارێک کە هیچ returnێکی تێدا نییە هەر شتێک دەگەڕێنێتەوە: نرخی تایبەتی NULL (بێنرخ (Null))، کە واتای هیچ نرخێک نییە دەگەیەنێت:

return does two things at the same moment: it sends a value back, and it ends the function immediately. Any code after return in the same function never runs:

return لە یەک کاتدا دوو کار دەکات: نرخێک دەنێرێتەوە و یەکسەر کۆتایی بە کردارەکە دەهێنێت. هەر کۆدێک دوای return لە هەمان کرداردا هەرگیز جێبەجێ ناکرێت:

This is useful. A function may contain several return statements, and the first one that runs wins. The lecture's howdy() example uses this to greet people in different languages:

ئەمە بەسوودە. کردارێک دەتوانێت چەند ڕستەیەکی returnی تێدا بێت و یەکەمیان کە جێبەجێ بکرێت براوەیە. نموونەی howdy()ی وانەکە ئەمە بەکاردەهێنێت بۆ سڵاوکردن بە زمانی جیاواز:

A function can deliver its result in two ways: print it with echo inside the function, or return it and let the caller decide what to do with it. In the lab session, students wrote the same function both ways. It adds two numbers, but first uses isset() to check that neither number is NULL (see Conditionals for isset() and !).

کردارێک دەتوانێت بە دوو شێوە ئەنجامەکەی بدات: لەناو کردارەکەدا بە echo چاپی بکات، یان بیگەڕێنێتەوە و بانگکەر بڕیار بدات چی لێ بکات. لە کاتی تاقیگەدا، خوێندکاران هەمان کردار بە هەردوو شێوە نووسی. دوو ژمارە کۆ دەکاتەوە، بەڵام سەرەتا بە isset() دەپشکنێت کە هیچ کام لە ژمارەکان NULL نەبێت (بۆ isset() و ! بڕوانە وانەی مەرجەکان).

Rule of thumb: let functions return their results, and do the printing outside. Then the same function can be used to print, to calculate further, or to save to a database. The slides' add() from Several parameters prints its sum; the add() in Returning a value returns it, so it can be used inside other expressions.

یاسایەکی گشتی: با کردارەکان ئەنجامەکانیان بگەڕێننەوە و چاپکردن لە دەرەوە بکە. ئەو کاتە هەمان کردار دەتوانرێت بۆ چاپکردن، بۆ هەژمارکردنی زیاتر، یان بۆ پاشەکەوتکردن لە بنکەدراوەدا بەکاربهێنرێت. add()ی سلایدەکان لە بەشی چەند پارامیتەر کۆکەی چاپ دەکات؛ add()ی بەشی return دەیگەڕێنێتەوە، بۆیە دەتوانرێت لەناو دەربڕینەکانی تردا بەکاربهێنرێت.

You now know every part of a function. This picture puts them together for one call, $total = add(20, 30);:

ئێستا هەموو بەشەکانی کردارێک دەناسیت. ئەم وێنەیە هەموویان بۆ یەک بانگکردن پێکەوە کۆ دەکاتەوە، $total = add(20, 30);:

So far, every parameter has received a copy of its argument. This is PHP's default, pass by value. Sometimes you want the function to change the caller's variable itself. Then you use pass by reference, marked with &. The picture shows the difference:

تا ئێستا، هەموو پارامیتەرێک کۆپییەکی ئارگیومێنتەکەی وەرگرتووە. ئەمە شێوە ئاساییەکەی PHPـیە: ناردن بە نرخ. هەندێک جار دەتەوێت کردارەکە خودی گۆڕاوەکەی بانگکەر بگۆڕێت. ئەو کاتە ناردن بە ئاماژە بەکاردەهێنیت، کە بە & نیشانە دەکرێت. وێنەکە جیاوازییەکە پیشان دەدات:

When you pass a variable to a function, the function receives a copy of its value. Changes inside the function do not affect the original variable outside. This is called call by value or pass by value, because the function gets the variable's value, not the variable itself.

کاتێک گۆڕاوێک دەنێریت بۆ کردارێک، کردارەکە کۆپییەکی نرخەکەی وەردەگرێت. گۆڕانکاری لەناو کردارەکەدا کار ناکاتە سەر گۆڕاوە ڕەسەنەکەی دەرەوە. پێی دەگوترێت ⁦call by value⁩ یان ناردن بە نرخ، چونکە کردارەکە نرخەکەی گۆڕاوەکە وەردەگرێت، نەک خودی گۆڕاوەکە.

Sometimes we want a function to change one of its arguments. Then put & in front of the parameter in the definition. Now the parameter is not a copy: it is a second name (a reference) for the caller's variable. Whatever the function does to it happens to the original. This is call by reference, or pass by reference.

هەندێک جار دەمانەوێت کردارێک یەکێک لە ئارگیومێنتەکانی بگۆڕێت. ئەو کاتە & لە پێش پارامیتەرەکە لە ناساندنەکەدا دابنێ. ئیتر پارامیتەرەکە کۆپی نییە: ناوێکی دووەمە (ئاماژە) بۆ گۆڕاوەکەی بانگکەر. هەر شتێک کردارەکە پێی بکات، بە ڕەسەنەکەش دەکرێت. ئەمە ⁦call by reference⁩ـە، یان ناردن بە ئاماژە.

Lab 4, Example 2 ("with argument") puts the two styles side by side: addFive() takes its parameter by value, addSix() by reference. The lab sheet shows only the two definitions, with no calls, so you cannot see the difference (and its layout is broken). Here they are with calls added:

نموونەی دووەمی تاقیگەی ٤ ⁦("with argument")⁩ هەردوو شێوەکە لە تەنیشت یەکەوە دادەنێت: addFive() پارامیتەرەکەی بە نرخ وەردەگرێت، addSix() بە ئاماژە. پەڕەی تاقیگەکە تەنها هەردوو ناساندنەکە پیشان دەدات، بێ هیچ بانگکردنێک، بۆیە جیاوازییەکە نابینیت (شێوەی دانانی کۆدەکەش لە پەڕەکەدا تێکچووە). لێرەدا بانگکردنمان بۆ زیاد کردوون:

Write & only in the function definition, never in the call. Very old PHP versions allowed triple(&$val) ("call-time pass-by-reference"); it was removed in PHP 5.4, and today it is a syntax error:

& تەنها لە ناساندنی کردارەکەدا بنووسە، هەرگیز لە بانگکردندا. وەشانە زۆر کۆنەکانی PHP ڕێگەیان بە triple(&$val) دەدا ⁦("call-time pass-by-reference")⁩؛ لە ⁦PHP 5.4⁩دا لابرا و ئەمڕۆ هەڵەیەکی داڕستنە:

A reference must point to a variable: a named place that can be changed. A literal such as 5 is not a variable; there is nothing for the function to change. So passing a literal to a by-reference parameter is a fatal error:

ئاماژە دەبێت ئاماژە بۆ گۆڕاوێک بکات: شوێنێکی ناونراو کە دەتوانرێت بگۆڕدرێت. نرخێکی ڕاستەوخۆ وەک 5 گۆڕاو نییە؛ هیچ شتێک نییە کردارەکە بیگۆڕێت. بۆیە ناردنی ژمارەیەکی ڕاستەوخۆ بۆ پارامیتەرێک کە بە ئاماژە وەردەگرێت هەڵەیەکی کوشندەیە:

Passing the result of another function is a special case. A return value is not a variable either, but PHP lets it through with a notice and works on a temporary copy:

ناردنی ئەنجامی کردارێکی تر حاڵەتێکی تایبەتە. نرخی گەڕاوەش گۆڕاو نییە، بەڵام PHP بە تێبینییەک ڕێگەی پێدەدات و لەسەر کۆپییەکی کاتی کار دەکات:

Store the result in a variable first. Then the reference has a real variable to work on, and you can see that it changed:

سەرەتا ئەنجامەکە لە گۆڕاوێکدا هەڵبگرە. ئەو کاتە ئاماژەکە گۆڕاوێکی ڕاستەقینەی هەیە بۆ کارکردن لەسەری و دەبینیت کە گۆڕاوە:

Each function name can be defined only once in a script. Defining the same name a second time is a fatal error. Because function names ignore case, a() and A() count as the same name:

هەر ناوێکی کردار تەنها یەک جار لە دەسنووسێکدا دەناسێنرێت. ناساندنی هەمان ناو بۆ جاری دووەم هەڵەیەکی کوشندەیە. چونکە ناوی کردارەکان گوێ بە قەبارەی پیت نادەن، a() و A() وەک یەک ناو دادەنرێن:

The page prints nothing at all, not even from lines before the error: PHP finds this problem while it reads the file, before it runs any line. Code editors such as VS Code underline the second definition in red even before you run the page. The same error appears if you reuse the name of a built-in function:

لاپەڕەکە هیچ شتێک چاپ ناکات، تەنانەت لە دێڕەکانی پێش هەڵەکەش: PHP ئەم کێشەیە لە کاتی خوێندنەوەی فایلەکەدا دەدۆزێتەوە، پێش ئەوەی هیچ دێڕێک جێبەجێ بکات. دەستکاریکەرەکانی دەقی (Text editor) وەک ⁦VS Code⁩ تەنانەت پێش کردنەوەی لاپەڕەکە هێڵێکی سوور بە ژێر ناساندنی دووەمدا دەکێشن. هەمان هەڵە دەردەکەوێت ئەگەر ناوی کردارێکی ئامادە دووبارە بەکاربهێنیتەوە:

Each function has its own small world of variables, called its local scope. A variable created inside a function is a local variable: it exists only while the function runs, and the rest of the page cannot see it. The parameters are local variables too.

هەر کردارێک جیهانێکی بچووکی تایبەت بە خۆی هەیە بۆ گۆڕاوەکان، کە پێی دەگوترێت مەودای ناوخۆیی. ئەو گۆڕاوەی لەناو کردارێکدا دروست دەکرێت گۆڕاوێکی ناوخۆییە: تەنها لە کاتی جێبەجێبوونی کردارەکەدا هەیە و بەشەکانی تری لاپەڕەکە نایبینن. پارامیتەرەکانیش گۆڕاوە ناوخۆییەکانن.

It also works the other way. A variable created outside all functions lives in the global scope, and it is not visible inside a function:

پێچەوانەکەشی ڕاستە. ئەو گۆڕاوەی لە دەرەوەی هەموو کردارەکاندا دروست دەکرێت لە مەودای گشتیدا (Global scope) دەژیت و لەناو کردارێکدا نابینرێت:

The clean solution is to pass the value in as an argument:

چارەسەرە پاکەکە ئەوەیە کە نرخەکە وەک ئارگیومێنت بنێریتە ناوەوە:

There is more to scope, such as static variables, the $GLOBALS array and the superglobals. All of this is explained in Constants and variable scope.

مەودا (Scope) زیاتری تێدایە، وەک گۆڕاوە ستاتیکەکان (Static variable) و ڕیزەکی $GLOBALS و سووپەرگلۆباڵەکان (Superglobal). هەموو ئەمانە لە وانەی نەگۆڕەکان و مەودادا ڕوون کراونەتەوە.

In the lab session, students wrote a program that prints the even and the odd numbers from 1 to 10 with two functions. It brings together a while loop, an if test and the modulus operator %: $count % 2 == 0 is true for even numbers and $count % 2 == 1 for odd ones. It also calls both functions before defining them, and it uses the keyword global:

لە کاتی تاقیگەدا، خوێندکاران بەرنامەیەک نووسی کە ژمارە جووتەکان و تاکەکان لە 1 تا ⁦10⁩ بە دوو کردار چاپ دەکات. خولێکی while (while loop) و تاقیکردنەوەیەکی if و کارپێکەرەکەی پاشماوە % پێکەوە کۆ دەکاتەوە: $count % 2 == 0 بۆ ژمارە جووتەکان ڕاستە و $count % 2 == 1 بۆ تاکەکان. هەروەها هەردوو کردارەکە پێش ناساندنیان بانگ دەکات و وشە کلیلەییەکەی global بەکاردەهێنێت:

global $count; tells PHP: inside this function, $count is the global variable $count, not a new local one. So displayEvenNums() changes the global variable: when it finishes, the global $count is 11. displayOddNums() does not use global; it creates its own local $count = 1, so it does not care that the global one is now 11.

global $count; بە PHP دەڵێت: لەناو ئەم کردارەدا، $count هەمان گۆڕاوی گشتی $countـە، نەک گۆڕاوێکی ناوخۆیی کە تازە دروست بکرێت. بۆیە displayEvenNums() گۆڕاوە گشتییەکە دەگۆڕێت: کاتێک تەواو دەبێت، $countی گشتی دەبێتە ⁦11⁩. displayOddNums() global بەکارناهێنێت؛ $count = 1ی ناوخۆیی بۆ خۆی دروست دەکات، بۆیە گرنگ نییە لای کە گشتییەکە ئێستا ⁦11⁩ـە.

Most function problems produce a clear message. Learn to recognise these, and you will fix them in seconds. Every message below was produced by PHP 8.

زۆربەی کێشەکانی کردارەکان پەیامێکی ڕوون دروست دەکەن. فێری ناسینەوەیان ببە و لە چەند چرکەیەکدا چاکیان دەکەیتەوە. هەموو پەیامەکانی خوارەوە ⁦PHP 8⁩ دروستی کردوون.

Lab 4 ("Function & Array") asks you to type and run its examples. Below are the lab's function tasks, the extra programs written during the lab session, and some new practice. Try each one yourself before you open the answer.

تاقیگەی ٤ ⁦("Function & Array")⁩ داوات لێدەکات نموونەکانی بنووسیت و جێبەجێیان بکەیت. لە خوارەوە ئەرکەکانی کردارەکانی تاقیگەکە، بەرنامەکانی کاتی تاقیگەکە و چەند ڕاهێنانێکی نوێ هەن. پێش کردنەوەی چارەسەرەکە، هەر یەکێکیان خۆت تاقی بکەرەوە.