BasicUsage - sycobuny/pg_model GitHub Wiki

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, usually, load() and save(). You provide load() with an associative array of your primary key columns, and it queries the database for you, like follows:

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

When there is only one column as the primary key, you can leave off the array and just pass the primary key value:

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

To make it even more succinct, you can pass either the primary keys array or the single primary key during object construction:

<?php
    $id = $_GET['id'];
    $account = new Account($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();