Getting Started

This chapter gives you a quick-start guide to Harmoni. It will concentrate on the most common required services: Authentication and Database Connectivity, as well as usage of the architecture.

2.1 The Harmoni directory structure

Here is a run-down of what's in Harmoni:

harmoni/

The root Harmoni directory. Contains the "harmoni.inc.php" file which must be included by any script using Harmoni.

harmoni/docs/

The documentation directory, containing the manual, various READMEs, the PHPDoc, License, etc.

harmoni/core/

Contains all the Harmoni core class files. Feel free to muck around. Changing things may mess things up, though.

harmoni/config/

Harmoni user-configuration files. Edit these!

harmoni/changelog/

Contains the changelog in XML, TXT and HTML formats.

harmoni/oki/

Contains all the OKI OSIDs. These are interfaces you should follow when creating classes for functions underneath the OKI umbrella.

2.2 Making your application run "under" Harmoni

Get ready, this is hard. And by hard, I really mean easy. Take a look at this code:

Example


require_once("/path/to/harmoni.inc.php");

...

Break it down: the require_once(...) is pretty much it. You include that, before most everything else, in a file called index.php or default.php or whatever you want, really. Once that file is included, all of Harmoni's required classes are included and services are instantiated and configured.

Now, as much as you could claim that your program runs under Harmoni just by using this file, you might also want to take advantage of the functionality it provides.

2.3 Quick Services Introduction

This section will provide a quick introduction into how Harmoni services can be created, started, stopped and used. For information on specific services that are packaged Harmoni, there is a chapter devoted to just that. This is not it.

Services are, in essence, special PHP classes. They are meant to hover over the execution of your code and pop down whenever you request them to impart their divine knowledge upon you. An example: The ErrorHandler. Any time something bad happens, you throw an error. The error handler picks it up and waits until later to print them out (at your discretion). If the error is fatal, well, it kills your program and tells the end user everything that happened (try it - it's fun).

Harmoni provides a special class called Services which can be used statically. That means that it's available in any scope in your program, and hence your program has access to ALL services registered in ANY scope of your program. For those of you that have a little sense, you organize your code into functions, and maybe even classes and class-methods. No matter where you are, though, you can access the Services class! Amazing! Here's how:

Example


...

if (Services::serviceRunning("ErrorHandler")) {
    $errorHandler =& Services::getService("ErrorHandler");
    $count = $errorHandler->getNumberOfErrors();
    print "We have $count errors!";
}

...

More detail on Services and the more advanced functions can be found later.

NOTE

Make sure that when you work with objects under PHP4 that you use the assign by reference operator ("=&") instead of a normal assign ("="). PHP4 has an annoying way of assuming that you want a copy of an object by default. For the most part, this is pointless. If you were to get a service by copy, make changes to it, and expect those changes to be reflected later in your code when something else gets the service, you will be pleasantly surprised (and annoyed). So, any time that you are expecting an object back from a function, use =&.

2.4 Subchapter: Database Connection

This section is a subchapter. Below is its table of contents:

2.4 Database Connection

2.4.1 Simple Database Access