Introduction to PHP User-Defined Functions

Hello again, and welcome back to Educator.com's Introduction to PHP course.0000

Today's lesson is an extremely exciting lesson--probably my favorite of the whole course--0004

because we are going to be teaching you how to create your own user-defined functions,0009

which is really going to increase your efficiency as a PHP programmer.0012

Specifically, we are going to talk about how to define your own functions, and the syntax that is involved with that.0018

We are going to talk about function parameters, which is ways to pass data to functions.0024

We have previously talked about that when calling functions using function arguments.0029

We are going to talk about return statements, which allow you to return a value from a function,0033

because, as we had learned before, functions are expressions, and they have values.0037

We are going to discuss where to define functions within your PHP code,0043

and that is going to involve a discussion of the include_once construct,0047

which is an extension of the include construct that we have talked about before.0052

And we are going to also talk about some reasons why you use functions, and why to separate code out into functions.0056

Then, we are going to make an update to our web application, version 10.0,0063

where we are going to extract some of the code from it and put it into functions,0068

so we can see our user-defined functions working firsthand in our web application.0073

And then, we are just going to quickly talk about when you do output HTML in functions, and then also coding conventions as it relates to functions.0079

Defining a function requires four parts: it requires the function keyword (and this is an example of a function declaration);0091

you provide a function identifier or a name of the function; then, in parentheses, you provide what is known as a parameter list0100

(we are going to talk more about that in a minute), and then, just like a control structure,0108

you have a statement group enclosed in parentheses, and that contains all of the code that gets executed when a function is called.0112

And this section of a function is known as the function body--the code contained in the function is known as the function body.0120

Anything contained, any PHP code that we have gone over so far, is allowed anywhere else in PHP script.0127

One thing to mention is that function identifiers or function names follow the same naming rules as we have for variables and constant identifiers.0135

Let's take a look at some examples of some basic functions, and see how they work.0146

Here, we have a sample script called functionExamples.php, and right here, this function is an example of the most simple function.0153

It is a function that, when it gets called, does nothing.0164

It has no statements in it, which is a perfectly legal function.0167

Now, as we know, when we call a function, it stops execution of the current script, goes and executes the code in the function,0170

and then returns the value to the script where it was called from; and then, the script continues to execute.0178

So here, in this case, we have defined this function; and then, I am going to go ahead and just call it.0183

And the way we do that is: just as we have been calling built-in PHP functions, we have the function name with the parentheses and a semicolon.0191

And this function does nothing, but it shouldn't cause any problems or any errors, and when we load the page, nothing should happen.0200

But this is just to demonstrate that a function can contain anything, including the lack of any code.0206

If we load functionExamples.php, nothing happens.0215

The other thing we can do is: we can create a function that just has one statement in it, but it is an empty statement.0220

And again, this is just to emphasize the fact that functions contain statements, and they contain any types of statements, including an empty statement.0233

And if we go ahead and call this function, we should receive no output, as well.0243

I'll go ahead and load the page, and nothing happens.0249

So now, we are going to get a little more interesting: we are going to have our function do something.0254

We are going to create an example function that is going to output some code by an echo statement.0259

So, we have this function called example1_2, and all we are going to do is simply echo a statement that says "inside example," and then the function name.0269

So, when we go ahead down here, below the function, and we call this function, example1_2,0284

what is going to happen is: when we reach this statement right here, it is going to call the example1_2 function.0297

It is going to run the code inside of it, which in this case is just an echo statement,0303

and it is going to echo that statement, and then continue processing the rest of the script.0306

So, we should see this line output now, when we run the script.0310

And when we reload the page, you can see, the echo statement was output that we had in the function.0316

So now, I want to talk about something called function parameters.0330

Function parameters are variables that are defined when you define a function, and they are variables that can be used within the function body.0335

They are described in between the parentheses of a function definition; and you can have as many parameters as you need.0344

When you call a function, as we have seen with built-in functions to PHP, we can supply data to functions.0351

And those are called function arguments; the data you supply is called an argument, and the argument fills the parameter variables of the function.0359

For example, when we define this function with param, we define it as having one parameter called param.0369

And what that means is that we can access this variable, param, anywhere within the function body.0377

And here, we can see that we just echo the value of param.0383

And the way that that gets said is by...when you call the function with param, you provide a function argument.0385

And what happens is: param gets set to this value.0394

So, every time this function is called, whatever value is supplied as an argument to the function--this parameter will get set to that value.0402

Now, I use the term parameter and argument, and it's sort of a technical distinction.0413

Technically, when you define a function, and you create (I'm erasing this) a parameter list, the variables that you make available0416

in the function definition are known as function parameters.0431

And when you call a function, you call a function with arguments, and those are the values that the parameters are going to get set to.0437

And sometimes, you will hear those terms used interchangeably; but essentially, they refer to kind of the same thing.0443

When you call a function, you supply arguments which set the value of the parameters specified in the function definition.0448

And you can have multiple parameters in a function, and what happens is: let's say, for example, there was another parameter here--0456

the way that it would get set (let's call it param1) is: when we call the function, we would supply a second function argument.0469

The order that the functions are supplied in specifies the order that the parameters get set in.0482

So, the first parameter gets set to the value of the first argument; the second parameter gets set to the value of the second argument.0494

Let's go take a look at some functions that use parameters.0502

So here, we have another example function that we are going to create that is going to take one parameter.0513

And all that it is going to do is echo the parameter that gets passed in.0518

For example, when we call this function, it requires one parameter, so we are going to have to supply it a value that it can output.0526

So, we are going to supply it with a string; and when we call the function...let's supply it with the string "Hello, World!" for example...0533

Now, what is going to happen is: when we call this function, this code is going to stop executing right here.0548

It is going to go up to where the function is defined; it is going to set the parameter variable,0554

this param variable, to the argument specified, which was "Hello, World!"0560

And then, it is going to run the code in the function body, which just says to output the parameter variable,0565

which is the string value that was passed in.0571

So, when we run our code, we should see it output this string "Hello, World!"0574

And if we go and take a look at that (oops, I had a typo; I forgot an e down here), you can see that it output "Hello, World!"0580

And if we include a break statement up here, this will look nicer...or actually, let's just get rid of this function call.0601

We can see that "Hello, World!" is output.0618

And the unique thing about function parameters is: they can be set to a different value every time the function gets called.0622

And that is what makes the function useful: it allows you to dynamically do things.0629

It can do one thing in one instance...for example, output one string one time it is called,0632

and then output another string when it is called a different time.0637

So, for example, we could input to this function the string "Goodbye" and then now, when we call this same function again,0640

even though it is the same function, it is going to perform a slightly different action, based on the arguments that we specified.0651

So, when we load it now, it is going to output this new string statement that we passed in.0660

Let me go ahead and comment out this line.0669

And now, what we are going to do is demonstrate, using a function that has multiple defined parameters.0672

Here we have a function with two parameters called param1 and param2.0679

What I am going to have it do is create a string that is just the concatenation of both parameters.0684

So, these parameters are both going to be strings that get passed in, and then we are going to create a string inside the function0691

that is just going to be the concatenation of those two strings, using the dot operator.0699

And we are just going to echo this concatenated string.0708

When we call this function, example2_1, we provide it with two parameters.0718

In this case, we provide it with "Hello," and then, as a second parameter, we provide it with the string " World!"0725

So now, when we call this function--when we execute this function call--it is going to take these two strings.0741

It is going to set the value of param1 in this function to Hello,; it is going to set the value of param2 equal to World!.0747

And then, the function is going to execute, and it is going to execute the concatenation of those two strings.0753

We should, again, see the string "Hello, World!" output.0761

If we go and reload the script, we can see, "Hello, World!" was output.0764

As we know from our Introduction to Functions lesson, functions are expressions.0775

What that means, that we know about expressions, is: they have a value.0780

So, functions always have a value, and they always return a value to the script that they were called from.0783

And the value of a function is known as its return value, and return values in PHP can be any type.0790

It can be an array; it can be a scalar, as we learned; it can be an object.0801

The way that you specify the return value of a function, or the value that it returns to the script it was called from, is using a return statement.0807

One thing to note, that we are going to show an example of in a second, is that you can have multiple return statements within the same function.0817

What happens is: when a function is executing, any time it reaches a return statement,0824

it automatically ends execution of the function and returns whatever value it was set to return in the return statement.0830

And even if there are statements that are still unexecuted in the function, it doesn't matter.0839

Once that return statement is reached, the function ends, and it returns back to the execution of the current script.0842

One other thing to note is that, if a return statement never occurs, or is never executed, within a function,0848

null is the value returned by default for all functions.0855

Let's go take a look at the return statement in action.0859

The first thing we are going to do is: we are going to have the return value...0870

we are going to use a return statement that is just going to return a static value.0873

So, it's going to have it return the string "Goodbye," and then we'll call the function, and this is a function with no parameters.0877

What is going to happen when we call this function in this statement right here: example3_0 is going to get called,0898

and what it is going to do is: it is going to execute the function body of example3_0.0907

And we see in the function body that all it contains is a return statement.0912

So, what this is going to do is: when this function reaches this return statement,0914

which is the only statement in the function, it is going to return the value Goodbye.0918

And that is how the return statement works: the statement starts with the return keyword, followed by a space,0923

and then whatever value you are going to return, which could be an expression;0929

it could be the output of another function, because functions have values.0934

Basically, you can return anything with value.0936

When this gets called, example3_0 is going to get executed; its value is going to be inserted here, and its value is going to be the return value Goodbye.0939

So, this is going to echo the return value Goodbye, and so the script should output Goodbye.0947

If we go ahead and reload the script, we can see that that is what happens.0955

So now, one thing that we are going to talk about that we had mentioned was that you can have multiple return statements within a single function.0966

For example, if we have a function that accepts one parameter, we can maybe conditionally return a value, based on the value of that parameter.0976

For example, we create an if statement that says, "If param equals the integer 1,0986

then we are going to execute a return statement that is going to return the string 1."1000

"Alternatively, if param equals 2, we are going to have it return the string 2."1007

So in this case, when this function gets executed, you can see that there are two return statements.1023

If param is equal to the integer value 1, it enters this if statement block, and it executes this return statement, and the function exits.1027

So, none of the remaining code gets executed.1034

If parameter equals 2, it is going to not enter this if block; it's going to enter this elseif block, and then it is going to return the value 2.1038

We could additionally add an echo statement here that says, for example, param is not equal to 1 or 2.1045

And also, what happens with a function is: if no return statement is specified,1059

the function just returns whenever it executes the last statement within the function.1063

So here, if param doesn't equal 1 or 2, this statement is going to get executed.1070

However, if it does equal 1 or 2, the function is going to return up here or right here.1074

And this echo statement won't get executed, or if param is equal to 1, none of this will get executed, as well.1080

That demonstrates a function that can have multiple return statements.1088

For example, if we call this function (and we are just going to echo its output, because it is returning string values),1093

let's put the value of 1 in; so it should enter this first section of code; it should return the value of 1.1111

And then, because it returns, the rest of it shouldn't get executed; so this echo statement should not occur.1119

When we run this code, we can see, it outputs 1.1125

Likewise, if we just change this down here to the value 2, we can see that it outputs the value 2,1130

and it never gets to this echo statement here, because again, once you reach a return statement, the function stops executing.1140

The other thing I wanted to demonstrate is: we have mentioned that, if a function doesn't have a return statement, it automatically returns the value null.1148

So, if we just have an empty function here, with a single statement that does nothing, and then we were to run the function,1158

we are going to run a comparison on the value returned by the function, to see if it is equal to null.1168

And we should find out that it is true.1173

So, if we run the comparison example3_2, what we are saying here is: we are running a comparison operation that is saying,1176

"call function example3_2, compare it to returned value (which in this case should be null,1193

because no return statement was explicitly specified); it should equal null,1197

and because it equals null, this statement should be true."1202

And with echo statements, the boolean value true gets output as the value 1.1208

That is the conversion from a boolean true to a string.1214

So, when we run this, we should see just the number 1 output; and that is confirming that this returns the value of null.1217

When we run the function, we can see that 1 is output, meaning that it did, in fact, return the value of null.1224

We have talked about how to define functions; we have talked about defining them with parameters and defining them with return statements.1236

We haven't really talked about where to define functions.1243

Typically, functions get separated into their own PHP files, known as function libraries, usually grouped according to the task they perform.1247

You might have 4 or 5 different functions, for example, that perform tasks on arrays.1255

So, you might create a function library that contains all of those functions.1261

And the function library only contains the PHP code for those functions.1265

It is just a PHP file that contains all of the function definitions.1271

And the way you access the file is by using an include statement; so if you are running a PHP script,1279

and you need to access, for example, an array function that you have defined in a function library,1284

you include that function library by an include statement, and then you will be able to have access to the function.1289

Now, one thing to note is: unlike some programming languages, in PHP, a function definition does not need to occur before it is called.1297

You can call a function and then define it later in the script,1308

or call a function and then include the function library where it is defined later on in the script, and it will still work.1311

As long as the function that you are calling is defined somewhere within a script, within the script it is being called from1318

or an include file of that script, it will work.1324

The way you typically include functions, and what we are going to use in this course (or include function libraries within your code) is1332

using a new construct that we haven't talked about, called include_once.1338

It is similar to the include construct, and what it does is: it takes the file that is specified and includes it in line, in the file where the include statement happens.1344

The one difference is that, with include_once, if you specify a file to include, and it has already been included, it won't get included again.1356

For example, if in this single PHP script we have this one statement, include_once ('functionLIB.php'),1369

which maybe is a function library, and somewhere in the script, we had another include_once function that says functionLIB.php,1376

it is not going to re-include it, because it has already been included once.1385

The reason that this is used with function libraries, as opposed to using an include statement, is:1389

if you redefine a function within the same PHP script, you get a fatal error in PHP.1394

For example, if you accidentally include the function library twice within your script,1400

using just regular include statements, you are going to get a fatal error.1405

And similar to include, include_once also has an analog, which is called require_once, which functions the same as the require statement,1410

which throws a fatal error if it can't find the file it is trying to include.1418

But it also functions like include_once in that, if you call require_once on the same file1422

multiple times in one script, it only gets included the first time.1428

Let's go take a look at a script that demonstrates this ability.1432

We have a file called includeOnce.php, and here we have another file called functionLIB.php.1438

This is a file that is just a function library; it contains a couple of different functions.1446

Here, in this case, we have a function called test, and a function that we are going to use in another example called outputHtmlHeader.1453

What happens is: let's say we want to use the test function within our script.1460

And let's get rid of this include statement--comment this out.1467

Now, when we run this file, we should get an error saying that the function is not defined,1471

because the function hasn't been included or been defined within this file.1476

So, if we go ahead and load the file up, it is going to say "Fatal error: undefined call to the function test."1480

OK, so we need to include the function library in order to have access to that function.1488

So, what we can do is use an include statement, include 'FunctionLIB.php'.1494

And this test function just simply outputs a simple statement; it says, "in test."1499

Now, when we run the file, everything should be OK; and it goes ahead and runs.1505

Now, however, let's say we accidentally, later, down here in our script, forgot that we had included that function library already,1509

and we run an include statement again, and try to call test again.1519

Well, we are going to get a fatal error here, because FunctionLIB.php is going to be included twice.1524

And because FunctionLIB.php has the definition of two functions in it, and it is called twice,1529

PHP is going to see those functions being redefined, which is a fatal error.1537

So now, when we run our script, which has these two inclusions of the same function library, we are going to get a fatal error.1541

And we can see "Fatal error," and it tells you what we would expect: you cannot re-declare test.1550

It says that test, defined in the FunctionLIB, cannot be re-declared.1556

The way to fix this problem is if we use include_once on both of these statements.1568

And if we always use include_once when including function library files, we won't have this problem.1572

It is going to include FunctionLIB.php here; it is going to call the test function;1580

and then, when we try to include it again, later on down the file, it is going to say, "Hey, I have already included this file;1585

I'm not going to include it again," and you eliminate getting that fatal error for trying to redefine the function.1589

If we save this file now, we should be able to run test twice.1597

We go ahead and load the file; we can see, we get that test was run; it says "in test" here twice.1602

Similarly, we can use...as mentioned, there is an analog require_once that does the same thing,1610

except it returns a fatal error if the file you are trying to require or include cannot be found.1623

So, we should get the same output, because it works.1630

And what that means is that this function was not included a second time.1632

Now again, the way require differs from include is that, if it can't find the specific include file1636

(for example, if I mistype the name of it), it is going to throw a fatal error.1643

So, if we run the file, it is going to say "Fatal error": require_once wasn't able to open this misspelled function library.1647

And so, that is the difference between require and include.1657

What are the reasons to use functions?1666

The main reason, or one of the major reasons, is to take advantage of code reuse.1670

What that means is: if you have a common task that you are performing over and over again,1675

you can isolate the code into one spot (into one function), and then you can just call that function over and over again, as you need it.1678

What that does is: that is going to limit your mistakes to one place.1685

The mistakes can only occur within that one function, whereas, if you had, for example, 5 lines of code that were included in the function,1690

if you include those 5 lines of code everywhere (in 5 different files, for example), that is 5 different places where a mistake can occur.1697

If you take that code out, put it in a function, and replace it with a function call,1706

then if there is an error in that code, you only have to fix it in the function file.1712

Additionally, if you want to (for example) change the functionality of something,1718

what you can do is apply the changes all in one place.1723

So again, if you use a function call (for example) to display something, and you want to change how it is displayed,1726

instead of going through each file, editing the code that displays it,1733

if you put that code within a function, you can just go ahead and apply the changes that need to be made in one spot,1737

and it goes ahead and applies it to all the other things.1743

So, this is going to increase your efficiency as a programmer; it is going to allow you to get things done faster.1745

Additionally, it is going to allow you to reduce writing the same functionality repeatedly.1751

For example, let's say you spend a couple of hours one day developing a couple of functions that you use for working with arrays.1756

Well, maybe you have another PHP project down the road, and you want to use some of those same functions.1763

Well, by including them as functions in a function library, you can reuse those in your new PHP application.1770

If you hadn't separated them out as functions (had just hard-coded them into your PHP pages),1776

when you went to your new project (for example), you wouldn't be able to just include the function library and reuse it.1781

So, separating things into functions allows you to reuse them, not only within one application, but in multiple applications.1791

The other thing that you can use functions for is to improve code readability.1798

That is by separating your HTML and PHP.1803

Typically, you want to separate (and this is something we haven't really talked about) your HTML and PHP as much as possible,1806

because it makes for cleaner-looking code, and also, when you are working on a team (for example)1814

you might have people that are HTML developers and people that are PHP developers.1819

The less you intermingle the HTML and PHP with one another, the easier it is1822

for different teammates to work together, without messing up one another's code.1831

If the HTML developer only works with HTML files with minimal PHP code, the chance of him messing up the PHP is limited.1836

Likewise, for a PHP developer, if he is only working with PHP files that have very little HTML, the chance of him formatting the HTML incorrectly is reduced.1845

So, you can use functions (for example) to remove large sections of PHP code from mixed HTML and PHP files.1854

You might have a 200-line PHP page, and maybe 25 of those lines are PHP code.1865

Well, what you can do is separate it out into a function, and then,1872

when your HTML developer goes to edit the HTML on that page, all they see is one function call.1875

They don't see the 25 lines of code that that developer has a chance to mess up.1881

Another thing that you can do is...sometimes, you just have ugly mixes of HTML and PHP code.1890

When you use echo statements, you have a lot of escaping with backslashes to output quotation marks, and so on.1897

So sometimes, if you have smaller "ugly" sections of mixed HTML and PHP code, you can separate that out into a function.1905

And what that is going to do is make your PHP page that is actually output look cleaner.1916

You are not going to have to look at the messy PHP and HTML mixed together.1924

Instead, you can have it in a function, so that ugliness only occurs in one spot.1927

The other thing that some people use is: you can essentially use a function as a way to include HTML content--to replace include files.1934

That is something you might see on different projects that you work on; you might see different developers use it.1944

For example, we have a script called functionVsInclude.php.1952

Here, we are including a function library, using the include_once statement we just learned about.1964

And the reason we are doing that is because it contains this function called htmlHeader.1969

What this htmlHeader does is outputs (for example) the header of an HTML page.1973

Maybe we want to include this at the beginning of every page.1980

So, what we could do is: in our page, we could go ahead and call outputHtmlHeader.1983

And what it is going to do is take the echo statements that are in that function, run them, and then output that.1990

Now, we could achieve the same thing by using an include statement...1998

for example, if we included this file called header.html,2003

which contains all of the same HTML that is output by this outputHtmlHeader function, and instead, we include it in here.2007

So, basically, there are two different ways of doing the same thing.2015

Some people like using functions to do that; maybe, instead of using an include statement for a header and a footer,2017

you have two functions called outputHtmlHeader and outputHtmlFooter; it is a preference thing.2024

You may see that in different spots.2032

And one thing to also note is that here, we have all of these echo statements.2034

But as we know, with PHP you can always escape to HTML mode.2038

So, we actually could replace all of these echo statements with the exact same content that we have in header.html.2042

What is going to happen is: when we run this outputHtmlHeader, it is going to execute what is in its function body.2060

And what is in the function body is an escape to HTML and an output of HTML code.2067

And then, at the end of the function, it just returns.2074

So, that is another way to output HTML, as well.2077

So now, let's talk about improving our web application.2083

We are going to move to version 10.0, and we are going to2086

take advantage of what we have learned about creating user-defined functions to clean up our code a little bit.2089

In checkout.php and contactUs.php, there are some rather complex boolean expressions used to validate the form data submitted.2097

For example, in checkout.php, we validate that a name, a street address, a city, a ZIP code, and so forth, were all provided.2108

It makes a complex boolean expression.2116

In contactUs.php, we verify that all three (name, email address, and comment) were submitted on the form.2120

We are going to separate those boolean expressions out into a function that is just going to return a boolean.2126

It is going to return true or false; and they are going to be called validation functions.2131

What that is going to do is make our code look cleaner, because,2137

instead of having these long, ugly PHP statements, we have a single function call.2140

We are also going to create a function that is just going to be used to output HTML <a> tags, or anchor tags, which are HTML links.2146

It is going to allow us to pass in (for example) a URL and the name of the link that we want,2156

and it is going to dynamically create an HTML string that uses the URL and name provided.2160

We are also going to add a constant to config.php that is going to be called LIB_DIR.2168

What that is going to do is: we are going to put these functions into function libraries, and we are going to store them in a lib directory.2174

And, just as we created an INCLUDE_DIR constant in our config file, we are going to create a LIB_DIR one2181

that is just going to be a path to where we are going to store all of our function include files.2186

What we are going to be doing is creating two library files, stored in the lib directory, one called outputLIB.php, and one called utilLIB.php.2192

That is the convention we are going to use in this course for signifying function library files.2204

You will have a descriptive name for the functions that are included in the file,2209

and then it is going be ended with the three capital letters LIB as part of the name.2214

And that is going to let you know, when you look at that file, that this is a function library.2220

This function library, outputLIB.php, is going to be used for functions that do any sort of outputting of HTML.2225

And then, utilLIB.php is going to be used for utility functions.2232

For example, that is where we are going to put our validation functions;2239

they are functions that perform utility operations you can use within your web app.2241

So, we are going to edit checkout.php and contactUs.php.2247

What we are going to do is take out the complex boolean expressions and replace them with the validation function.2252

We are going to edit config.php, so that it has this updated content, LIB_DIR.2259

And then, we are also going to update store.php to make use of the function we are going create up here2264

that is going to allow us to create HTML anchor tags.2269

Let's go take a look at the code; for example, if we look at version 9.0, if we look at checkout.php (this is version 9.0),2276

and if we scroll down to where we do the data processing, we can see that there is one section down here2296

where we are validating the shipping information that was provided by the customer.2304

And if you look, this is a particularly ugly and complex boolean expression that is validating all of the data.2308

And so, what we can do is take that out and put it in a function that returns the boolean value of that expression.2317

And then, we can replace it with a single function call, and that is going to make it look cleaner.2324

For example, we replace that boolean expression; instead, we just have a function call down here, called isValidCustomerData.2328

And the function name has a descriptive name; typically, functions that return boolean values have is prepended to them, as the first part of the name.2338