CRUD

CRUD stands for Create, Update, Retrieve and Delete. CRUD operations are the core of many web applications.

Working with ORM

The ORM works with bones. Most interactions with the database are accomplished using bones. Bones are used to carry data from and to the database.

Every bone has a type and an ID. The type of a bone tells you which table in the database is used to store the bone. Every type maps to a corresponding table. The ID of a bone is the primary key of the corresponding record.
You can create a new bone by dispensing one.

Create

To create a new bone (of type 'book') use:

$book = ORM::dispense( 'book' );

You can now add properties:

$book->title = 'Learn to Program';
$book->rating = 10;

You can also use array notation if you like:

$book['price'] = 29.99; //you can use array notation as well

and store the bone in the database:

$id = ORM::store( $book );

At this point, the bone will be stored in the database and all tables and columns have been created.
The bone will now have an ID, which is also returned for your convenience.

Barebone will build all the necessary structures to store your data. However custom indexes and constraints have to be added manually (after freezing your web application).

Conventions

You can dispense any type of bone you like, as long as the type name consists of lowercase alphabetical characters:

$page = ORM::dispense('page'); //valid
$page = ORM::dispense( 'Page' ); //invalid: uppercase
$page = ORM::dispense( 'cms_page' ); //invalid: _
$page = ORM::dispense( '@#!' ); //invalid

However dispense also offers some shortcuts:

$twoBooks = ORM::dispense( 'book', 2 );

list($book, $page) = ORM::dispenseAll( 'book,page' );
list($book, $pages) = ORM::dispenseAll( 'book,page*2' );

Properties of bones may contain alphanumeric characters and underscores. Camelcased properties will automatically convert to snake_case:

$book->isSoldOut = TRUE; //is_sold_out
$book->hasISBNCode = TRUE; //has_isbn_code

Retrieve

To load a bone, simply pass the type and ID of the bone you're looking for:

$book = ORM::load( 'book', $id ); //reloads our book

If the bone does not exist an empty bone with ID 0 will be returned.

Update

To update a bone in the database, add or change properties:

$book->title = 'Learn to fly';
$book->rating = 'good';
$book->published = '2015-02-15';
ORM::store( $book );

Note that we added a new property 'published', Barebone will add a new column of type 'date' for this property. Also, it will widen the 'rating' from INTEGER to VARCHAR to support text as well as numbers.

//Examples of other data types
$meeting->when = '19:00:00'; //Time
$meeting->when = '1995-12-05'; //Date
$photo->created = '1995-12-05 19:00:00'; //Date time
$meeting->place = '(1,2)'; //SPATIAL only works in postgreSQL
$price->amount = '12.37'; //FIXED POINT NUMERIC - MySQL and Postgres
$price->amount = '$25.00'; //MONEY TYPE - Postgres only

If you want a suitable data type of monetary values, use the 'XX.XX' format and you'll get a fixed precision number data field. To make use of Postgres special purpose, currency-aware money data type, prefix the value with a common currency symbol.

You can use ORM::isoDate() and ORM::isoDateTime() to generate the current date(time) if you like.

Barebone will dynamically add new columns to your database. It determines the column type to use by looking at the value you are trying to store. For instance, a short text might be stored as a VARCHAR while a large text might be stored as TEXT. Similarly, a boolean value will probably get stored as TINYINT but when you put a float in that property the column will probably be changed to FLOAT or DOUBLE (depending on your database).
Some column types behave differently, for instance if you store a valid ISO formatted date (i.e. 2015-01-01) Barebone builds a DATE column, but this column will not change. In general, Barebone tries to adapt the database to your application. If you're done developing, you can freeze the database using the freeze() function. After that, the database schema will no longer change (because it is very unlikely you want to store something other than a date in a column you filled with perfectly formatted date in the first place).
Note that Barebone will never throw away columns or 'shrink' columns (from TEXT to VARCHAR) to avoid data loss. Barebone also only manipulates column types it recognizes, so if you change a VARCHAR(255) to a VARCHAR(254) it will leave that column alone, since it no longer recognizes the type. This means that if you customize columns, Barebone leaves them alone from that point on.
If Barebone alters the database in a way you don't like, don't worry, you can always tune the schema to your liking (just use your database management tool or phpmyadmin), you can even freeze certain tables only.

Delete

To delete a bone:

ORM::trash( $book ); //for one bone
ORM::trashAll( $books ); //for multiple bones

To delete all bones of a certain type:

ORM::wipe( 'book' ); //burns all the books!

To destroy the entire database simply invoke the nuclear method (be careful!):

ORM::nuke();

Batch

To load a series of bones use:

$books = ORM::loadAll( 'book', $ids );

Reload

To quickly reload a bone:

$bone = $bone->fresh();

Finding bones

Instead of loading bones, you can also use the find() method to search for bones using certain criteria. Learn how to query bones in the ORM.