Plug in PHP 100 POWER SOLUTIONS- P13 pot

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().