This page intentionally left blank CHAPTER 2 Using the Plug-ins 28 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s 28 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s H ow you choose to include the plug-ins in your own programs is entirely up to you, but two main techniques can be used. The first of these is to simply copy a plug-in from the companion web site for this book and paste it directly into your program. This is a method that is simple and easy to use when working on small projects because your program and the plug-ins it uses are all there in a single file, ready to edit as necessary. But once you start to write larger projects (and more of them), you’ll begin to find it wasteful to keep copying the plug-ins to each new program file. What’s more, whenever you tweak a plug-in, if you want the latest version, you’ll need to find the program that contains it and copy it from there. Worse than that, every time you come up with another improvement you’ll need to edit every instance of it across your code if you want all your projects to benefit from it. Obviously this is no way to run a railroad, so I recommend that from the start, if you aren’t already, you get used to saving all your plug-ins into one or more separate program files that can be included into your code with simple directives. This means you’ll only ever have a single instance of each plug-in to update, which will then be reflected in all pr ojects that include it. PHP supplies two main methods for including files: include and require. Using include As you would expect, the include command takes a filename as a parameter and includes it, like this: include "myfunctions.php"; This tells the PHP interpreter to fetch the specified file and loads its contents in as if it had been typed into the current program file. In the preceding example, myfunctions.php must reside in the current folder. If you keep your include files elsewhere, you need to provide either a relative or the full path to the file like this: include "/usr/local/apache/htdocs/includes/myfunctions.php"; That was a Unix/Linux/Mac path. In Windows, an include statement might look like this: include "c:\phpfunctions\myfunctions.php" This creates a slight problem though, because every time PHP encounters this particular include statement it will load the file in again. This takes up more memory than is necessary and is slow and inefficient. What’s more, any functions already defined will be redefined, which is not allowed, and will generate an error message. To overcome this difficulty, you can use the include_once command instead, described in the following section. include_once When you use include_once, each time PHP is asked to include a file it will check whether the file has already been loaded into memory and, if so, it will ignore the request. For this reason, I recommend you use include_once instead of include. But this still isn’t always the best solution, because include and include_once don’t care whether the file requested actually exists. If it doesn’t, the commands simply get C h a p t e r 2 : U s i n g t h e P l u g - i n s 29 C h a p t e r 2 : U s i n g t h e P l u g - i n s 29 ignored and a warning error message is displayed, while the program execution continues. Now this is fine if the file to be included contains non-essential code that is not absolutely necessary for your program to run, or if you always include a file of ready-made functions just to be sure they are available but you aren’t currently calling any of them. As soon as you do need access to one of these functions, if the include file hasn’t been loaded into memory, you’ll be presented with unsightly error messages that may only crop up on specific events relating to the current state of program flow, such as when an infrequently used function gets called up. The solution to this is the require command, discussed next. Using require When you use the require command instead of include, PHP will return an error and halt program execution if it cannot locate the requested file. This is usually preferable to using either include or include_once, because every time the program runs you will get a fatal error if the file cannot be found, rather than only in cases where a function in the include file is accessed. This enables you to correct the problem (probably a mistyped filename or incorrect path) before you release your project to the general public. But, as they say, that’s not the whole story. Just like with include, each time PHP encounters a require command it will reload the requested file into memory. This, as previously discussed, is not a good idea. So the final (and in my opinion best) solution is to use the require_once command, explored next. require_once Like its counterpart, include_once, require_once will only ever load in a single copy of a file, no matter how often that file is requested. But, unlike include, it will also generate an error if it can’t find the file requested. So there you have it, require_once provides the best of both worlds and is the ideal way to include files in your PHP programs. It is therefore the recommended method used throughout this book. Include Scope When you include a file, it is inserted exactly at the point of the include or require statement (or the include_once or require_once statement). This is intentional, so you can choose the scope of the included code. To understand this, let’s take a look at what is meant by scope. For example, in the following code snippet, the variable $fred has global scope because it is declared outside of any functions. This means that all parts of the program, whether inside or outside of functions, have access to this variable and can read and change its value. This includes functions, as long as a function is told to treat the variable as global using the global keyword: <?php // Example 1: Illustrating scope $fred = "X"; test(); echo "Test 2: [fred: $fred] [jane: $jane]<br />"; 30 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s 30 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s function test() { $jane = "X"; global $fred; // Allow access to global variable echo "Test 1: [fred: $fred] [jane: $jane]<br />"; } ?> While $fred has global scope, the variable $jane only has local scope because it is declared within the function test(), and only that function can read or change its value. The output from this code can be seen in Figure 2-1. As you would expect, Test 1, an echo statement within the function test(), shows that from inside that function both the variables $jane and $fred can have their values read— indicated by the letter X that was assigned to them. But from outside the function, Test 2 is unable to retrieve the value assigned to $jane, and so no X is displayed. In just the same way, if you include another PHP file outside of any functions (usually right at the start of a file), its variables and functions will be accessible from anywher e in that file. But if you choose to include it from within a function, then only that function can access the file’s contents. This latter case is a very special one and you are unlikely to use it yourself or encounter it often in other people’s code. So another rule to adopt when including the plug-ins from this book is to remember to include them right at the start of a file (so you can tell at a glance whether the include has been made) and not from inside any functions. Correctly Inserting PHP code When a file is included, PHP interpretation stops at the start of the included file and recommences at its end. This means that, by default, all included files will be treated as plain HTML, unless you ensure they have surrounding <?php … ?> tags, the same way your main program does. If you leave these tags out of an included PHP program, then a bunch of garbled program code will be displayed in the browser. Not only is this messy, but anyone can view this code and see how your program works (or at least is supposed to work). FIGURE 2-1 The variable $jane only has local scope and cannot be referenced outside the function test(). . saving all your plug- ins into one or more separate program files that can be included into your code with simple directives. This means you’ll only ever have a single instance of each plug- in. will then be reflected in all pr ojects that include it. PHP supplies two main methods for including files: include and require. Using include As you would expect, the include command takes a. like this: include "/usr/local/apache/htdocs/includes/myfunctions .php& quot;; That was a Unix/Linux/Mac path. In Windows, an include statement might look like this: include "c:phpfunctionsmyfunctions .php& quot; This