Setting Up the Fusebox 4 for PHP Core Files
Part 1
Phillip Harrington
Fuesbox 4 for PHP is unofficially available as a beta release on Sourceforge. If you're new to Fusebox 4 or new to Fusebox completely, it might be a little confusing at first. In this tutorial, and in Part 2, I will describe how to set up a basic working Fusebox core file installation. At the end of this two part tutorial you should have a decent "base" Fusebox installation, ready for copying into a new project folder so you can begin architecting new applications.
What is Fusebox you may ask? Briefly, Fusebox is part methodology, part architecture. It is first a methodology, or a way of doing things. The official Fusebox site says,
"To build a Fusebox application, a developer breaks his or her application down into actions (fuseactions) and then puts pages and scripts (fuses) together in a directory (circuit). The HTTP request will call specific actions like index.cfm?fuseaction=mycircuit.myfuseaction, and the associated fuses are executed by the circuit controller. The sequence of files executed along with some accompanying utilities and a [sic] API are enabled via the core files."
Already we have three new terms: Circuits, Fuses, and Fuseactions. A circuit is analogous to a directory. All files related to a certain function go in a directory together. Fuses are actual files with code in them. And fuseactions are a verb, telling a circuit which fuses to run.
Fusebox is part architecture, or framework, in that a set of core files exist to implement the concepts of the methodology in actual code. Originally Fusebox was implemented in ColdFusion. We will be working with the PHP port. Thankfully due to the nature of Fusebox, the things we learn here will mostly apply to use with Fusebox in ColdFusion as well.
The benefits of using the Fusebox methodology are mentioned on the official site, and I'll attest to the truth of these benefits by repeating them here. They include: increased productivity, increased code reusability, easier code maintenance and a strong community of Fusebox developers using a standardized architecture. Check out the official Fusebox site for more info.
Now that we understand what Fusebox is a little more let's get started setting up our first Fusebox Environment.
Step 1: Download the latest Core Files.
You can get the latest version of the core files from the official fusebox.org web site located at: http://downloads.fusebox.org/.
Making sure you have the latest core files is a good practice with each new application you develop. Although core files for PHP are stable enough for actual use (at the time of this writing), they are still considered to be in "beta." Infrequent bugs are still being found and squished, so making sure you have the latest copies of the core files isn't a bad idea, even after we help you get your "base" installation established.
Step 2: Extract the Core Files to a Working Directory
Using your favorite ZIP extraction tool, extract the core files you downloaded into a directory. Here I've used C:\Inetpub\htdocs\fusebox4php. I'll continue to refer to this directory in this tutorial for consistency.
Fig 2: Extracting the Core Files.
Step 3: Create the Parsed and Plugin Folders
Navigate to the directory you extracted the core files to, and create two new directories named parsed and plugins.
Fig 3: Creating the Parsed and Plugin folders.
The parsed folder is required to run Fusebox. It is an internal folder used by the core files. When a fuseaction like index.php?fuseaction=shoppingCart.addItem is accessed, Fusebox figures out where the shoppingCart circuit is, and what that circuit is supposed to do for the addItem fuseaction. Once this has been sorted out, Fusebox writes all these instructions down for itself in a file in the parsed directory. Then it simply runs the parsed file it has created. The great thing about Fusebox is that if that parsed file exists, it simply runs the parsed file, and skips several time-consuming steps. It's a little more involved really, but that's the basic concept.
The web server needs to have write access to this folder. If you are running a web server on your local machine, make sure your local web server can write to this directory. Otherwise, if you are going to be running your files on a remote web server, we will take care of the folder permissions when we upload our files (in Step 9).
The core Fusebox files are extendable via a Plugin architecture built into the core files. If you develop a plugin you would put it in the plugins directory. Several general plugins are available and more are being created everyday. We'll look at one such plugin in part two of this Tutorial. The web server does not have to write to this folder, so you do not need to modify its permissions.
Step 4: Create a fusebox.xml.php File
You will need a couple of files that are not included in the core download to get started. The first file is your fusebox.xml.php file. Despite the .php extension, the fusebox.xml.php is really an XML file that defines parameters and settings for your entire web application. We only need one for each Fusebox application. You can also name this file fusebox.xml. The Fusebox core files will look for either fusebox.xml.php or fusebox.xml and use the one it finds. Naming the file fusebox.xml.php is a handy shortcut that makes editing this file easy in your favorite PHP editor, if it doesn't happen to handle XML files.
There are pros for going with either naming convention. I personally use .xml, because when I'm debugging, it's handy to know if I've made a syntax error my XML file that renders it invalid. Quickly loading up my XML file in a browser will tell me if there's an error. Most developers tend to use the .xml.php method so that they only have to work with one kind of file. Also, there is a way of locking people out of your .php files that has been used with Fusebox in the pass. For those who are security conscious, there is a way to lock prying eyes out of either type of file. I'll explain how in Part 2 when we talk about securing your environment.
Here is a good default fusebox.xml.php file. Create this file in the "root" of your application, i.e., the folder you installed the core files in. In my case, I extracted the core files to C:\Inetpub\htdocs\fusebox4php\ so that is where I will save my fusebox.xml.php file.
<?xml version="1.0" encoding="UTF-8"?> <fusebox> <circuits> </circuits> <parameters> <parameter name="parseWithComments" value="true" /> <parameter name="fuseactionVariable" value="fuseaction" /> <parameter name="defaultFuseaction" value="" /> <parameter name="precedenceFormOrUrl" value="form" /> <parameter name="mode" value="development" /> <parameter name="scriptLanguage" value="php4" /> <parameter name="scriptFileDelimiter" value="php" /> <parameter name="maskedFileDelimiters" value="htm,cfm,cfml,php,php4,asp,aspx" /> </parameters> <globalfuseactions> <preprocess> </preprocess> <postprocess> </postprocess> </globalfuseactions> <plugins> <phase name="preProcess"> </phase> <phase name="preFuseaction"> </phase> <phase name="postFuseaction"> </phase> <phase name="fuseactionException"> </phase> <phase name="postProcess"> </phase> <phase name="processError"> </phase> </plugins> </fusebox>
Step 5: Define a Circuit in Your fusebox.xml.php File
Although the fusebox.xml.php file above is complete, it is still missing one key ingredient. Our Fusebox application needs at least one circuit. Circuits are how we group and organize related code functionality in Fusebox. Let's define a circuit now. In the <circuits> section of your fusebox.xml.php file, add a <circuit> tag, like so:
<circuits> <circuit alias="main" path="" parent="" /> </circuits>
The path is relative to where our Fusebox core files are located. In this case, our "main" circuit is in the same directory as our core files. If we wanted to put that in a different directory, we could create a directory called "main" and make our path value "main/" (note the trailing slash). We won't do that for now, but it is an option that is needed for applications with more than one circuit.
Now that we have our circuit called "main" set up, let's give our application a default fuseaction. This is in the <parameters> section. Find this line:
<parameter name="defaultFuseaction" value="" />
Make the value to be a complete fuseaction in the form of circuit.fuseaction. In our case, we only have one circuit, "main," so pick a good default fuseaction for the main circuit, and enter that. Let's call our default "home" for now. We can always change it later.
<parameter name="defaultFuseaction" value="main.home" />
We now have a decent fusebox.xml.php file.
Step 6: Create a circuit.xml.php file for the "main" Circuit.
We will do the majority of our work with Fusebox in our circuit.xml.php files. Like our fusebox.xml.php file, the circuit files can be named circuit.xml.php, or circuit.xml. Once again, this is simply a convenience for working with the files in your favorite PHP code editor.
A circuit.xml.php file starts with the <circuit> tag, and has three child tags, or sections, two of which are optional. They are:
- A prefuseaction
- One or more fuseactions
- A postfuseaction
For now, to avoid confusion, we will only focus on the fuseactions. Let's start our file with the circuit tag itself.
<circuit> </circuit>
This is a perfectly valid circuit.xml.php file.
The circuit tag has an attribute called "access" with three possible values, "public," "internal," and "private." The default value for the access attribute is "internal." Since we usually want to start adding fuseactions that we can access from a URL, let's give our circuit "public" access.
<circuit access="public"> </circuit>
If a circuit is public, all of its fuseactions can be called from a URL in the form of index.php?fuseaction=main.home, or from other circuits, or from itself. If a circuit's access is internal, its fuseactions can only be called from other circuits, or from itself. If a circuit's access is private, its fuseactions can only be called from itself, i.e. from fuseactions within the same circuit. I'll explain how a fuseaction can call another fuseaction in just a little bit.
When we wrote our fusebox.xml.php file we specified a default fuseaction of main.home. We still need to define our home fuseaction. Let's do that now with the <fuseaction> tag.
<circuit access="public"> <fuseaction name="home"> </fuseaction> </circuit>
Fig 4: Editing the circuit.xml.php file.
Step 7: Make it say "Hello, world!"
At this point, we have a working Fusebox installation, although it doesn't actually do anything. Let's add a simple fuse that says, "Hello, world!" and include it in the main.home fuseaction.
Although it's not a requirement in Fusebox, fuses (files) are generally named with a prefix indicating what the general function of the fuse is. Fuses that query databases are prefixed with "qry;" fuses that display information on the screen are prefixed with "dsp;" and fuses that perform actions such as data or file manipulation, or sending email, are prefixed with "act." Our fuse will simply display, "Hello, world!" so let's call it dspHelloWorld.php
Some developers like to use all lowercase and underscores, such as dsp_hello_world. Either way is acceptable, since the file names (or the prefixes) are not specified in the Fusebox standard. Here is our dspHelloWorld.php file:
<h2>Hello, world!</h2>
Fig 5: Editing the dspHelloWorld.php file.
It's boring, but effective. Now, let's include this file in our fuseaction. A fuseaction can do several different things, each specified by a different XML verb in our circuit file. For now we're only going to look at the <include> verb, but for reference, the fuseaction verbs are:
- include: We can include a file whose contents (if any) are output to the screen.
- set: We can set a variable
- xfa: This is used to set a special kind of variable known as an Exit Fuseaction or XFA.
- do: We can DO another fuseaction with this tag, either in the same circuit or in a different circuit. The do tag is how fuseactions are called from other circuits as mentioned above in our discussion of a circuit's access attribute.
- relocate: We can relocate to another URL.
- if: We can have a conditional section. This tag has two child tags, <true> and <false>
- loop: We can loop while a condition is met.
For more information about these tags, check out the Techspedition web site where a few sample chapters of Discovering Fusebox 4 are available for download as PDF files.
To include a file, we use the <include> tag. This tag has an attribute named template, where we specify the path to the file we want to include. In most cases this is simply the file name, since our file is usually in the same directory as the circuit file.
<circuit access="public"> <fuseaction name="home"> <include template="dspHelloWorld" /> </fuseaction> </circuit>
Fig 6: Editing the circuit.xml.php file again.
In Fusebox, it is not necessary to include the ".php" at the end of the template attribute. This is because of the scriptFileDelimiter line in our fusebox.xml.php file.
<parameter name="scriptFileDelimiter" value="php" />
Fusebox will automatically append this script file delimiter to the end of the template attribute value (if that value does not already end with the script file delimiter). This makes it easier to change languages if need be. For example, if you have to convert a Fusebox application from PHP to ColdFusion, you would simply change the value of scriptFileDelimiter in your fusebox.xml.php file, rather than digging through ten circuit.xml.php files to replace instances of ".php" in your template attributes. It's another convenience. Setting the template attribute to "dspHelloWorld.php" would have worked just as well, but let's take advantage of the shortcut and save our wrists as much as we possibly can.
Step 8: Run It!
Now, run your Fusebox application in a browser. My local server's web root is: C:\Inetpub\htdocs and I saved my files to C:\Inetpub\htdocs\fusebox4php. Therefore, I load the URL:
http://localhost/fusebox4php/
Fig 7: Viewing our work in a browser.
Voila!
Step 9: Uploading (optional)
If you need to upload to a remote server, simply FTP to your remote server.
Fig 8: Uploading our files.
One catch: if your remote web server is UNIX running Apache (and if you're developing in PHP, it probably is), you must chmod your parsed folder to 777, or change the ownership so that the web server can write to that folder. This can be done easily with most FTP clients.
Fig 9: Changing permissions on the parsed folder.
If you do not run a web server on your local machine, may I strongly recommend that you consider installing and running one. Having a local web server running saves you having to upload files to your remote server to test them out in a browser. This can speed up your development process considerably. If you're on Windows (like me), getting Apache to run as an application or even a service is not that difficult if you carefully follow instructions. Even my mom has installed a local Apache service, and she's not a web nerd at all.
Conclusion
So far we have a working installation of the Fusebox for PHP core files. We downloaded the most recent core files, extracted them, created our first fusebox.xml.php file, defined a circuit, created our first circuit.xml.php file, wrote a simple fuse file that out put data to the screen, and saw it in action by running our fuseaction in a browser. Good job!
In our next tutorial, we'll tweak out our basic Fusebox environment even more. We'll tighten down our XML files and parsed directory from prying eyes with .htaccess. We'll use the Globals plugin to set some variables that exist in all fuseactions. And finally, we will look at using something called "contentvariables" in conjunction with a circuit dedicated to layouts to create a reusable template for our web pages. I hope you're a little more comfortable with Fusebox and are excited about Part 2. See you soon!
I wrote a short article on Layouts with Content Variables to tide people over.
Part 2 is now online.
No, there was no Fig 1.
