This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

The harmoni framework is a product of collaboration between a team of devolopers from Middlebury College and a team from the Associated Colleges of the South Technology Center.

Active Developers as of the time of this writing include:
Alex Chapin
Adam Franco
Eric Jansson
Dobromir Radichkov
Gabe Schine
Nikitas Stamatopolous

Past developers include:
Angela Roles
Zach Toups
Karlie Verkest

Harmoni is a combination of two things: A suite of PHP application services and a PHP web application framework/architecture. For more information on PHP, visit www.php.net. Harmoni supplies you with an Object Oriented PHP development environment which is completely modular. This means that any functionality can be changed and/or extended by writing only the code you need to write. First, through the use of Harmoni services, you can save yourself hours of re-inventing the wheel for functionality such as:

• Web authentication,
• File storage,
• Database access to multiple SQL database types,
• Debug data output,
• Custom error handling,
• Complex layout building and theme-able content,
• And many more...

More details about the Harmoni services can be found in later chapters.

Second, Harmoni offers a powerful programming framework that draws heavily from the services and offers a very easy way to get your program to do what is unique to it and avoid all the commonalities. With the use of the framework, you can tell Harmoni, "When a user goes to this page, I want to make sure they are authenticated, that they view everything that comes out with this theme, and that when the operation succeeds, they are forwarded to another page." You don't need to worry about how they are authenticated, what database their user information comes from (if it comes from a database at all), etc. All you need to tell Harmoni is a little about how your environment is configured. It does the rest.

The Harmoni architecture structures programs in the following way: A program is made up of multiple modules, each of which are comprised of multiple actions. Actions can be anything you like -- that's where you write your code. For example, you may have a module named "user_preferences", in which are the actions: "view", "update", "save", "change_password", "commit_password", etc. From the view action, a user could click the "Change My Password" button, which would bring them to the change_password action. This action, after asking the user for their old password and new password, could send them to commit_password, which, after verifying the user's old password, commits the changes to a database and sends them back to view. The action, if the user enters an invalid old password, could send them back to change_password with an error message. These are just examples of how you could structure your program. There are countless ways to use the architecture. It's up to you to find the best to suite your needs.

More details about the architecture/framework can be found in later chapters.

Some of you brilliant readers may have noticed the striking resemblance of "Harmoni" to the word in the English language, "Harmony". Well, congratulations to ya'll. Indeed they have very much to do with each other. In fact, we decided to drop the 'y' and add the 'i' for no reasons other than legal: someone else nabbed the real word.

As far why we chose Harmoni and not "Clambrit, the PHP application framework": we like to think of all the programs that run under Harmoni to work together seamlessly, having access to and using the same user authentication information (if useful), and on. In essence, they would run together harmoniously. See the connection? If not, stop reading, please - it will only hurt more.

OKI is an initiative started by a group of developers at MIT in Boston, MA. OKI stands for the Open Knowledge Initiative. The OKI team has attacked a problem that has plagued developers of educational systems for years: sharing content. There are thousands of brilliant programmers out there, each with their own ideas, some better and some worse, as to how to structure their data connectivity. The team has been working for several years (relative to the time of this writing) to decide what would be the best way to interface with various types of data on the internet: authentication (or AuthN), authorization (AuthZ), course management, filing, grading/assessment, etc.

A few terms that could sum up their work include: interoperability, abstraction, and I would add smart. "True" interoperability among software -- namely telling any program to "get your data from this institution instead of ours" -- is a far-fetched idea without writing enormous amounts of what could be called "cross-walk code". Even using OKI's suggested interfaces, not everything can work seamlessly with everything else. This is due largely to the countless number of programming languages in use. Also, every institution's needs differ, and how they go about solving their unique problems also differs. So you might ask, well, what's the point then? It sounds rather hopeless. In answer to that: If everyone writes their programs implementing OKI's suggested interfaces, at least where it seems to make sense, or where one goal is to share data, it will make bridging the gap between two programs millions of times easier. This way, both programs are expecting very similarly orgranized data from each other, and can easily send that data when requested. There is nothing harder than taking to programs written by two different people with two entirely different ideas of "grading" and trying to figure out where they overlap and how data can be shared. It's like acting as a translator to two people speaking foreign languages. With OKI, one could look at it more as clarifying the communication between two people speaking different dialects. Most of the communication happens without your involvement, and when things get rough, you can step in and nudge one person one direction or another.

Because we (the Harmoni people) believe OKI's initiative to be bold and great, we provide, on the lowest level, the PHP class interfaces for close to all of OKI's OSIDs (OKI Service Interface Definitions). Since OKI was originally conceptualized for use in Java(tm), adapting it to PHP is done with the differences in language in mind. We have also, since action is the best example, modelled Harmoni and many programs that run underneath it (that's right, we also write programs) strongly after OKI's OSIDs.

More on OKI can be found at http://okiproject.org/ or at http://sf.net/projects/okiproject.

Is it useful? Is it USEFUL? Who the hell is asking these questions?

On a serious note: PHPDoc is the PHP equivalent of JavaDoc. If you don't know what that is, just take a quick look at any PHP file we ship with Harmoni. You'll notice a whole bunch of stuff in the comment blocks (the stuff between '/**' and '*/' -- I shouldn't have to tell you this). Aside from helpful paragraphs of text, there are a bunch of lines that start with the '@' character. They give the PHPDoc engine more information about the code. Anyway, you only need to know this if you plan on writing your own code with PHPDoc comments (which we highly suggest you do!).

Packaged up with this manual and other documentation, you'll find a folder under "docs/phpdoc". If you browse there with your browser of choice, you'll find a whole bunch of nitty gritty documentation on Harmoni. In fact, there you'll see just about everything that makes up, well, everything. Organized into "packages" (the top-left frame) you'll see a whole bunch of classes (the bottom-left frame). Clicking on any given class will give you a page telling you what that class does, how to use it, and how it integrates into the overall picture.

You can also find the Harmoni PHPDoc online at harmoni.sourceforge.net/doc.