How to work with PHP functions

Hi, this is Chris Shattuck with BuildaModule dot com and in this video we're going to be talking about working with functions in Drupal. So like the video that came before this where we talked about arrays, we're gearing this lesson more towards people that don't have a background in PHP development but that need to work with coding Drupal for some reason. So here's what we're going to cover.

First of all, we'll look at how to identify a function, and then we'll talk about what a function actually is and why we would use one. We'll go over some handy conventions for creating a function, some typical conventions that are used in the Drupal space in particular. We'll look at using references which is an important concept to understand when we're using hooks in Drupal.

And speaking of hooks, we'll talk about how to identify a hook function and use one. We won't go into depth in this lesson but there are some other videos on this site that do. Next, we'll take a look at creating private functions or basically functions that we don't want other modules to access.

Next, we'll look at using variables that are outside of the scope of our function or that are basically defined somewhere else in Drupal. And finally, we'll look at storing a permanent variable inside of a function so we can reuse it. Let's go ahead and get started by looking at how to identify a function.

I'm going to click this to make it bigger. When we're creating a function, we're going to start off with the function keyword followed by a space. Next is the name of the function.

In this case, it's demo underscore name. Following that are parentheses an inside of those parentheses are any parameters we want to pass to the function. So these are treated as variables within the function.

Following the ending parenthesis is a curly bracket, an opening curly bracket, and then everything between this opening curly bracket and the ending curly bracket is the code that you want to run inside of this function. In this case, what we're doing is creating a string. It starts with "Hello world, my name is," and then we're adding this variable that's being passed to the function using a concatenation operator which is just a period and then a variable.

So when we pass some text here, it should be added to the string and then the return keyword is used to then return that value to whatever is calling it. So here below is an example of how we would use this function. So we're using the echo function which will take whatever we pass to it and print it to the screen, and then we're calling the function by using the function name and then we're passing it any parameters we want to with these opening and closing parentheses.

So we're passing it the text "Chris. " So when we pass this to this function, it should say "Hello world, my name is Chris. " Let's go ahead and take a look at this function in action.

So what I've done is created an example page here and I have generated this example page through a simple custom module called demo. And you can see the code right here. It's very simple.

We're just using a hook_menu() function and we're creating a page using a function called demo_page(). So if you're curious about how to create a module show, it's really simple. We have a couple of videos on the site including one free one that will give you some details on how to do that.

So I'm not going to go into detail here, but I just wanted to show you that we have some very simple code here and that it's inside of a module called demo. Okay. Let's go back to the code and what I'm going to do is copy this code and paste it into my module.

Now, typically, we wouldn't want statements like echo statements just sitting around in our code, but this is just a demonstration. So we're going to leave it in so we can see how it works. I'm going ahead and saving the file, going back to our browser, and then I'm going to refresh the demo page.

Okay. At the very top you see "Hello world, my name is Chris. " So that's the behavior that we'd expect from an echo statement.

If we wanted to put that content inside of the page here, let's take a look at how to do that. What I'm going to do is copy the function call and what we're going to do is paste that into what's returned from the function that generates our page. I'm going to go ahead and save this and go back to our demo page and refresh it.

And now you can see that text is showing up on the page itself. All right. Now that you've seen a demo of how function works, let's go ahead and go back and take a look at what a function actually is and why we would want to use one.

Probably the simplest way to describe what a function does is that it wraps around bits of code, and by wrapping around bits of code, it then allows us to reorganize our code in a meaningful way. So if you look at a plain PHP script, it's being read from top to bottom. And if you change the order of the code, then it changes the execution order of the script.

With functions, if we have everything in our code embedded in functions, then we can rearrange those functions as we'd like without affecting the execution order because the execution of the code inside of those functions actually occurs when we call the functions. So that's kind of nice. We can reorganize things in a meaningful way.

Also, with functions we can put code inside of a function and then reuse it multiple times for various purposes. So it's a method of abstracting some sort of purpose in our code so we can use it multiple times. If you're looking at just plain PHP script, if we want to duplicate functionality, we have to copy the piece of code that's responsible for that functionality in multiples places in our code.

Then when it comes to change that code in some way, we have to change it in multiple places. With a function, we just have to change it in one place. So it makes it easier down the road for maintenance.

Also, the code inside of a function doesn't get run until the function is called. So we can just put in the function and not have to worry about it until we actually call it. And finally, functions localize code but they also localize variables which means that the variables inside of a function are only accessible to that function with a couple of exceptions that we'll cover later.

But what that means is that if there are important variables outside of our function that are being used, we don't have to worry about accidentally overriding them. For example, in Drupal there's a variable called user and it would be very common if we're dealing with users to use that as a variable name. But if we did that, it would then override that user variable.

If we have our code inside of a function, we don't have to worry about that because if we create a user variable, that's just inside of our function. We don't have to worry about it, messing with anything outside of it. That's something called scope.

So anything inside of your function is within scope; anything outside of it is outside of scope. Okay. Let's take a look at some of the conventions that we follow when creating a function inside of Drupal.

The first rule of thumb to follow when naming your function is to make it unique by prefixing it with your module name. So if we go over to this code that I had created for our demonstration earlier, you can see that all of my functions start with demo and an underscore. So this makes sure that if every module follows the same convention that there aren't going to be any conflicts in function names.

If two function names are the same, then PHP will throw an error and it won't execute the entire script. So that's the first thing we want to do. And we want to make sure that our function is in a place where it's only going to be included in our code once.

So let's say we put a function inside of an include file that gets included more than once in a page. What will happen is that the function will be defined the first time the page is loaded, and then the next time it's loaded it's going to be defined again which will put in conflict with itself and it will throw an error and it won't create the page. So we want to make sure that it gets included just once.

If you're adding functions into your module file, Drupal will handle this and you don't really need to worry about it. But it's just when you're using include files and other places for your code where you might want to keep this in mind. And finally, Drupal convention is to use all lowercase with underscores between words for function names.

So even though you can use uppercase and you don't need to use underscores, it's convention to do that in Drupal. All right. Let's go ahead and move on to looking at how to use references in functions.

The concept of reference is that sometimes we want to create a variable that just points to another variable instead of actually creating a new variable from the original variable. So if we use syntax like variable equals another variable, then that new variable is just a copy of the old variable. But when we use a reference, what happens is that the new variable doesn't actually contain any of the data from the old variable.

It just contains a pointer to that old variable. So if we change data inside of the new variable, that data will be changed in the old variable at the same time. One benefit to this is that it can simplify your code and another one is that it reduces memory load because instead of continually copying our variables, we're just using one variable with the data and that data is stored in memory but it's only stored in memory once instead of multiple times.

Let's go ahead and take a look at some examples of how this can be used. I'm going to click this to make it bigger. In this first example, we're defining a function called demo_test() and we're passing it a variable called var.

But instead of passing it a straight variable which in a typical function would copy that variable inside the scope of the function, we're using this ampersand to indicate that this is actually a pointer to the original variable. So when we make changes to this variable inside of our function, it will make those changes to the variable that's outside of our function as well. So here we have a line that assigns the variable a new value and so when this happens the variable outside will change as well.

Let's take a look at an example that's typically used in a Drupal module, the hook_form_alter() function. So you can see here we're prefacing the form_alter() function with the name of our module which will make this a unique name, and hook_form_alter() is passed three variables. The first one here is form and you can see by the ampersand here that it's pointing to a variable that's outside of our function.

If we look at what's happening in the code in here, what we're doing is adding a new input to the form variable, but we don't have to actually return anything because that form variable is being changed outside of the scope of our function. So it kind of makes things a little cleaner. We don't have to add that extra return line.

Let's take a look at this simple function example and we'll do it first without references and then we'll do it with references. You can see the difference between them. So here we're creating a function called demo_test() and we're passing it a variable.

The variable is then assigned a value of new value and then we return that variable. So if we're going to execute this function, here's what it would look like. We're taking a variable and we're assigning it the return value of what happens when we run demo_test() on a variable.

So here what we're doing is reassigning back to the original variable the value that is returned from demo_test(). So this is a good candidate for a reference because we just want to modify the original variable, and then we're running the echo statement to pr ...

Read the last half of the transcript