Documentation.

Crash Course

Welcome to dORM's crash course. During this short tutorial, we will model a Twitter like application using dORM. A demo inspired from this course is available in demo/twittah/ and a live version is available at http://twittah.getdorm.com

First step: Designing the business model.

Twitter has 2 core components: users and twits (updates).

Users have 4 properties:

Following: users that the user is following.
Followers: users that follow the user.
Twits: all updates of the user.
Username

Twits have 2 properties:

Time: time the twit was posted
Message: content of the twit

Let's modelize this into two PHP classes:

<?php class User { Public $followers = array(); // collection of User objects Public $following = array(); // collection of User objects Public $twits = array(); // collection of Twit objects Public $username; } class Twit { Public $time; Public $message; }

Second step: Designing the database.

The database will store all data and relationships.

First, we will need a table for storing all users:

CREATE TABLE `user` (
  `user_id`   int AUTO_INCREMENT NOT NULL PRIMARY KEY,
  `username`  varchar(255)
) ENGINE = InnoDB;

Second, we will need a table for storing all twits:

CREATE TABLE `twit` (
  `twit_id`  int AUTO_INCREMENT NOT NULL PRIMARY KEY,
  `time`     int,
  `message`  varchar(255)
) ENGINE = InnoDB;

Third, we will need an associative table for storing following/followers relationships between users:

CREATE TABLE `user_relationships` (
  `follower`  int,
  `followed`  int,
  /* Foreign keys */
  CONSTRAINT `fk_follower`
    FOREIGN KEY (`follower`)
    REFERENCES `user`(`user_id`),
  CONSTRAINT `fk_followed`
    FOREIGN KEY (`followed`)
    REFERENCES `user`(`user_id`)
) ENGINE = InnoDB;

Finally, we will need an associative table for storing relationships between users and twits:

CREATE TABLE `user_2_twit` (
  `user_id`  int,
  `twit_id`  int,
  /* Foreign keys */
  CONSTRAINT `fk_user_id`
    FOREIGN KEY (`user_id`)
    REFERENCES `user`(`user_id`),
  CONSTRAINT `fk_twit_id`
    FOREIGN KEY (`twit_id`)
    REFERENCES `twit`(`twit_id`)
) ENGINE = InnoDB;

PS: notice that we used the InnoDB engine and foreign keys, because dORM can't guess foreign key relationships (at the moment).

Third step: Mapping classes to tables.

Now that we have our business model and database, all we have to do is tell dORM how to map PHP classes to database tables. This is done with a very simple XML file (config.xml) that looks like the following:

<dorm>
    <map dsn="mysql://root@localhost/dorm_crashcourse">
        <User table="user">
            <username field="username" />
            <following pivot="user_relationships" parentFkey="fk_follower" class="User" />
            <followers pivot="user_relationships" parentFkey="fk_followed" class="User" />
            <twits field="user_2_twit" class="Twit" />
        </User>
        <Twit table="twit">
            <time field="time" />
            <message field="message" />
        </Twit>
    </map>
</dorm>

Final step: Playing with dORM !

dORM is now ready to do the heavy lifting.

Inserting

Let's create three users in PHP:

<?php $bob = new User(); $bob->username = "bob"; $john = new User(); $john->username = "john"; $tim = new User(); $tim->username = "tim";

Now that we have created our users, let's put some relationships between them. Bob will follow Tim and John, John will follow Tim and Tim will follow John.

<?php $bob->following = array($tim, $john); $john->following = array($tim); $tim->following = array($john);

Now, let's load dORM and save our three users in the database.

<?php $dorm = new Dorm("path/to/config.xml"); $dorm->save($bob); $dorm->save($john); $dorm->save($tim);

If we take a look at the database, everything should be there, including the relationships.

Loading

If we want to load all three users, this is what we would do:

<?php $users = $dorm->getUserCollection();

If we want to load a user by it's user ID, we would do this:

<?php $bob = $dorm->getUser(1); // or $bob = $dorm->getUser(array("user_id" => 1));

If we want to load the users by username, we would do this:

<?php $users = $dorm->getUserCollection("username=:username", array("username" => "bob")); $bob = $users[0]; $users = $dorm->getUserCollection("username=:username", array("username" => "john")); $john = $users[0]; $users = $dorm->getUserCollection("username=:username", array("username" => "tim")); $tim = $users[0]; // if we want to load all users but Bob we could do this $users = $dorm->getUserCollection("username <> :username", array("username" => "bob")); // if we want to display everyone who is following Tim foreach ($tim->followers as $user) { echo $user->username . ","; }

Notice that dORM never loads 2 different instances of the same database row. In other words, the following should return true:

<?php if ($tim->following[0] === $john) { echo "Tim is following John and therefore, the John that we loaded previously is the same object as the John in Tim's following list"; }

Updating

Let's add Bob to Tim's following list:

<?php $tim->following[] = $bob; $dorm->save($tim);

This will update the user Tim without removing John from Tim's following list. Tim is now following John and Bob.

Deleting

If we want to delete user Bob, all we have to do is:

<?php $dorm->delete($bob);

That's about it for now ! If you want to see a demo Twitter application inspired from this crash course, you can find one in demo/twittah/ or try our live demo at twittah.getdorm.com.

dORM PHP Object Relational Mapper