Quick Tour

In this Quick Tour I will show you how to use ORM and highlight some of its features.
Because your time is precious, the Quick Tour is very brief and should only take about 5 minutes to walk through...

Quick Tour in 5 minutes

ORM focuses on the developer,... you!
It does not focus primarily on performance, object orientedness, correctness or proper design.
No, the ORM purpose is to boost your productivity.
As such, Barebone is not just an ORM, it's also a development tool.

Minute 1: Create a database

Now you have to setup your database connection.
If you just want to play with Barebone you may also use:

ORM::setup();

This will create a simple, temporary SQLite database, after rebooting your system this database will be gone.

If you want to start using Barebone for real, you can connect to the MySQL database you have configured like this:

ORM::init(); // you could pass in another database name

OR you could do a full setup like this:

ORM::setup( 'mysql:host=localhost;dbname=mydatabase', 'myusername', 'mypassword' );

Minute 2: Bones

Barebone ORM makes it really easy to store stuff in the database. For instance, to store a blog post in the database you write:

$post = ORM::dispense( 'post' );
$post->title = 'My holiday';
$id = ORM::store( $post );

Now, barebone will create a table called post for you in the database and add a column called title, big enough to hold your text. The store() function will also return the primary key ID of the record, which I capture in the variable $id.

Barebone automagically creates a column for your property, in this case 'title'. Barebone determines the column type by scanning the value in the property. For instance in this case the value is a small text, so Barebone will add a column of type VARCHAR (assuming this is a MySQL/MariaDB database). Imagine you store a large text in this property later, then Barebone will change the column type to TEXT to make room for the new value. This is called fluid mode. In fluid mode, Barebone will adapt the database to meet the requirements of your app. It will never throw away columns though nor will it ever shrink the size of a column, so you don't have to worry about data loss. If you want to clean up your database by removing columns you have to do this manually. Some datatypes are immutable, for instance if you store an ISO date string in a property (2005-01-01), Barebone will create a date column for you. However in this case, the date column will not change (to TEXT for example). This is because I consider it unlikely you ever want to change a date column into something else (like a TEXT column). If you try to put an invalid date string into this column Barebone assumes it's by accident.

Just type ORM:: and then the name of the method you want to use!

To load the post you just saved, just pass the ID to the load function:

$post = ORM::load( 'post', $id );

Yep, there's your post again. To echo the title of your post:

echo $post->title;

Nothing fancy there, but did you know beans can also be treated like arrays ?

echo $post['title'];

To delete your post, pass it to the trash method:

ORM::trash( $post );

Now, the post is gone, it will no longer be available in your database.

Minute 4: Finding stuff

Finding stuff in the database is easy:

$posts = ORM::find(
    'post', ' title LIKE ?', [ 'holiday' ] );

This will search for all posts have the word 'holiday' in the title and will return an array containing all the relevant beans as a result. As you see, I don't use a fancy query builder, just good old SQL.
I like to keep things simple.

Besides using the find() functions, you can also use raw SQL queries:

$books = ORM::getAll(
    'SELECT * FROM book WHERE price < ? ',
    [ 50 ] );

Minute 5: Relations

Barebone ORM also makes it easy to manage relations. For instance, if we like to add some photos to our holiday post we do this:

$photo1 = ORM::dispense( 'photo' );
$photo1->src = '/images/add.png';

$photo2 = ORM::dispense( 'photo' );
$photo2->src = '/images/table.png';

$post->ownPhotoList[] = $photo1;
$post->ownPhotoList[] = $photo2;
ORM::store( $post );

Here, $photo1 and $photo2 are also beans (but of type 'photo').
After storing the post, these photos will be associated with the blog post.
To associate a bone you simply add it to a list. The name of the list must match the name of the related bone type.
So photo bones go in:

$post->ownPhotoList

comments go in:

$post->ownCommentList

and notes go in:

$post->ownNoteList

See? It's that simple!

To retrieve associated beans, just access the corresponding list:

$post = ORM::load( 'post', $id );
$firstPhoto = reset( $post->ownPhotoList );

In the example above, we load the blog post and then access the list. The moment we access the ownPhotoList property, the relation will be loaded automatically, this is often called lazy loading, because Barebone only loads the beans when you really need them.

To get the first element of the photo list, we simply use PHP's native reset() function...

$firstPost = reset( $post->ownPhotoList );

Although no SQL is necessary, Barebone is very SQL friendly. For instance, suppose some of your posts have quite a big photo collection associated with it and you want to limit the number of photos to a maximum of 3:

$threePhotos = $post->with( 'LIMIT 3' )->ownPhotoList;

See? Just pass a little SQL Snippet!

Final note

As you have seen, Barebone dynamically changes the structure of the database during development. This is a very nice feature, but you don't want that to happen on your production server!
So, before deploying your app, be sure to freeze the database by adding the following line just below the setup or set the freeze configuration option to true:   

ORM::freeze( TRUE );

Before you deploy, review your database schema. Barebone tries to make a good database schema for you, but you might want to improve it.
Maybe you added a column you no longer use, or you want an extra index.
Always make sure you review the final database schema before you put it on a production server!
After freezing the database, Barebone will no longer change the structure, so you have the best of both worlds. NoSQL-like flexibility during development and a reliable schema on your production server!

This was just a quick tour, showcasing some basic usage of Barebone.