1.1.1. Getting Started

Warning:

Atlas 3 ("Cassini") is still in alpha so it should be considered unstable, though it is ready for experimental and exploratory use. If you need a stable release, please try Atlas 2 ("Boggs").

1.1.1.1. Installation

This package is installable and autoloadable via Composer as atlas/orm. Add the following lines to your composer.json file, then call composer update.

{
    "require": {
        "atlas/orm": "~3.0"
    },
    "require-dev": {
        "atlas/cli": "~2.0"
    }
}

(The atlas/cli package provides the atlas-skeleton command-line tool to help create data-source classes for the mapper system.)

1.1.1.2. Instantiating Atlas

First, you will need to create the prerequsite data-source classes using Atlas.Cli 2.x.

Then, you can create an Atlas instance by using its static new() method and passing your PDO connection parameters:

<?php
use Atlas\Orm\Atlas;

$atlas = Atlas::new(
    'mysql:host=localhost;dbname=testdb',
    'username',
    'password'
);

Optionally, you may pass a Transaction class name as the final parameter. (By default, Atlas will use an AutoCommit strategy, where transactions have to be managed manually.)

<?php
use Atlas\Orm\Atlas;
use Atlas\Orm\Transaction\AutoTransact;

$atlas = Atlas::new(
    'mysql:host=localhost;dbname=testdb',
    'username',
    'password',
    AutoTransact::CLASS
);

Alternatively, use the AtlasBuilder if you need to define a custom factory callable, such as for TableEvents and MapperEvents classes.

<?php
use Atlas\Orm\AtlasBuilder;
use Atlas\Orm\Transaction\BeginOnRead;

$builder = new AtlasBuilder(
    'mysql:host=localhost;dbname=testdb',
    'username',
    'password'
);

// get the ConnectionLocator to set read and write connection factories
$builder->getConnectionLocator()->...;

// set a Transaction class (the default is AutoCommit)
$builder->setTransactionClass(BeginOnRead::CLASS);

// set a custom factory callable
$builder->setFactory(function ($class) {
    return new $class();
});

// get a new Atlas instance
$atlas = $builder->newAtlas();

Now you can use Atlas to work with your database to fetch and persist Record objects, as well as perform other interactions.