BasicUsage

Basic Usage

Summary

Currently PGModel assumes you have an existing database with tables that (ideally) match a certain pattern. These patterns will be pretty familiar to most ORM users. However, PGModel tries not to outguess your design.

Class Definition

The most ideal situation will require you to declare a class like follows:

<?php
    include_once('lib/pg_model/model.php');

    class Account extends Model { }

    // the following line would only be necessary if 'Account' didn't use the 'accounts' table
    // Model::associate_table('accounts', 'Account');

Accessors

This will create an Account class which maps fields from the accounts table into object accessors. Say, for instance, your accounts table has the fields id, name and balance. The following would be valid calls with just the class above:

<?php
    $account = new Account();
    echo "The ID of this account is:      " . $account->id . "\n";
    echo "The name of this account is:    " . $account->name . "\n";
    echo "The balance of this account is: " . $account->balance . "\n";

These fields will by default be blank. However, you can set them just like you'd expect:

<?php
    $account->name = 'Personal Checking';
    $account->balance = 15.00;

PGModel will load the datatypes from the database and cast them appropriately into PHP datatypes when you assign the values.

Loading and Saving

Loading from and saving to the database is accomplished through, quite simply, load() and save(). load() is currently not sensitive enough to handle multi-column primary keys. In fact, it's locked into assuming id is your primary key column. This will change in future versions. Loading is accomplished like follows:

<?php
    $id = $_GET['id'];
    $account = new Account();
    $account->load($id);

Saving to the database is aware of whether the object has been saved before. That is, if a primary key exists in the object, then it will try to do an UPDATE statement, otherwise it will try to do an INSERT statement. By maintaining a list of modified columns, UPDATE statements will only ever save changes to the values that the object has modified, preventing unintentional overwrites and minimizing conflicts. Utilizing PostgreSQL's RETURNING clause, it also refreshes the object state after saving to the latest values in the database. A call to save is fairly simple:

<?php
    $account->balance = $account->balance + 20; // birthday check from Grandma
    $account->save();

Further Reading

PGModel also supports basic associations (foreign key relationships/etc.). Check out Associations for more details on those.

There are also (constantly improving) PHPDoc comments which provide inline documentation detailing further use and the full API. Check those out using your documentation tool of choice.