Getting Started

Installation

Maghead ORM supports installation through Composer package manager, to install:

$ composer require maghead/maghead "4.0.x-dev"

After the installation, you shall see an auto-generated script vendor/autoload.php, you may run the generated script to make sure it works for you:

$ php vendor/autoload.php

And then, make sure it works:

php vendor/bin/maghead 

Configuration

First, you need to create a config file in YAML format, and paste the config content to db/config/database.yml:

$ mkdir -p db/config
$ cat > db/config/database.yml

Suppose your application code is located in src/ directory, then you should provide your schema path in following format:

---
cli:
  bootstrap: vendor/autoload.php
schema:
  auto_id: 1
  paths:
    - src/TodoApp/Model
instance:
  local:
    driver: mysql
    host: localhost
    user: root
    pass: qwer1234
databases:
  master:
    driver: mysql
    database: myapp
    host: localhost
    user: root
    pass: qwer1234

Please note the vendor/autoload.php is your application bootstrap script, if you don't have one, you may change the bootstrap script path to generated autoloader script vendor/autoload.php.

The schema.paths denotes the paths where you define your model schema files.

In the above config file, the auto_id means an id column with auto-increment integer primary key is automatically inserted into every schema class, so you don't need to declare an primary key id column in your every schema file.

Connecting Configuration With The Command-line tool

Maghead ORM command-line tool is named maghead, which reads your configuration through a symlink .lazy.php. The symlink points to your database configuration file.

You may run maghead use command to build your configuration and create the config symlink:

$ vendor/bin/maghead use db/config/database.yml

Building config from db/config/database.yml
Making link => .lazy.yml
Done.

Creating Database

If you want to use PostgreSQL or MySQL as your backend database, you can create your database through the db create command:

$ maghead db create master
creating database myapp...
Done

If you'd like to drop the database and recreate a new database, you can run recreate

$ maghead db recreate master
recreating database myapp...
Done

Setting up Environment

Maghead connection manager manages your database connections. To initialise the database connection for your application, you need to setup Maghead\Runtime\Config\FileConfigLoader to prepare the connection settings.

Here is the simple bootstrap code:

<?php
# app.php
require 'vendor/autoload.php';

use Maghead\Runtime\Config\FileConfigLoader;
use Maghead\Runtime\Bootstrap;

$config = FileConfigLoader::load( __DIR__ . '/db/config/database.yml');
Bootstrap::setup($config);  // true -> prepare connection only

Remember the auto-generated script file vendor/autoload.php? we need that autoloader script to load Maghead classes automatically through the spl_autoload_ functions.

The Bootstrap::setup will setup the data source manager and connection manager automatically.

Bootstrap::setup saves the config object in Bootstrap::$config static property. Bootstrap::getConfig() could be used to get the config object of the current environment.

The prototype of Bootstrap::setup is:

public static function setup(Config $config, DataSourceManager $dataSourceManager = null)

If $dataSourceManager argument is not given, then Maghead\Runtime\DataSourceManager::getInstance() singleton will be used. Therefore, you can get the corresponding data source manager instance via Maghead\Runtime\DataSourceManager::getInstance().

Now, please run this script to make sure it works for you:

$ php app.php

The command above should run silently without any error.

Adding Schema

Put the content below the the file src/TodoApp/Model/TodoSchema.php:

<?php

namespace TodoApp\Model;

use Maghead\Schema\DeclareSchema;

class TodoSchema extends DeclareSchema
{
    public function schema()
    {
        $this->column('title')
            ->varchar(80)
            ->label('Todo')
            ;

        $this->column('done')
            ->boolean()
            ->label('Done')
            ->default(false)
            ;
    }
}

To make the schema classes to be loaded easily, you can add the classmap or psr-4 class loading rules to your composer.json like this:

{
    "autoload-dev": {
        "classmap": ["tests"],
        "psr-4": {
            "AuthorBooks\\": "examples/books/",
            "MetricApp\\": "examples/metric/",
            "PageApp\\": "examples/page/",
            "StoreApp\\": "tests/apps/StoreApp/",
            "TestApp\\": "tests/apps/TestApp/",
            "Todos\\": "examples/todos/src/Todos/"
        }
    }
}

Then you should be able to get the schemas via the schema list command:

maghead schema list

And then you can build the static class files by running the command below:

maghead schema build

Building tables

If it's the first time to build the table, you can run the command below to build up the database schemas:

maghead sql

If you need to rebuild everything, you can run this:

maghead sql --rebuild

Creating some Todos

Remember the app.php file that you just created?

<?php
require '../../vendor/autoload.php';

use Maghead\Runtime\Config\FileConfigLoader;
use Maghead\Runtime\Bootstrap;

// **** include this line to use Todo quickly ****
use Todos\Model\Todo;

$config = FileConfigLoader::load('db/config/database.yml');
Bootstrap::setup($config);

// **** define the todo ****
$titles = [
    ['title' => 'Attend the design meeting'],
    ['title' => 'Buy some fruits'],
    ['title' => 'Fix the bugs'],
];

foreach ($titles as $title) {
    $ret = Todo::create([
        'title' => 'Attend the design meeting'
    ]);
    if ($ret->error) {
        echo $ret->message , "\n";
        var_dump($ret);
    }
}

Querying the todos

To query all the todos that you just created, you can use TodoCollection:

use Todos\Model\TodoCollection;

$todos = new TodoCollection;
foreach ($todos as $todo ) {
    echo $todo->id , ' - ' , $todo->title, "\n";
}

By default, TodoCollection connects to the master database (the primary one named as "master").

Now let's add some conditions:

use Todos\Model\TodoCollection;

$todos = new TodoCollection;
$todos->where()->is('done', true);

foreach ($todos as $todo ) {
    echo $todo->id , ' - ' , $todo->title, "\n";
}

For more details, please see the example code https://github.com/maghead/maghead/tree/master/examples/todos

For more details about the CRUD operations, please see Daily CRUD