Mappings

Mappings

Mappings are a type of configuration that defines how the database or data-source maps to your entity. They are created by mappers.

Mappers

Every entity that you want hydrated or persisted to a database or data-source will require a mapper. A mapper lets you build up a mapping, defining attributes, relationships and any data-source specific details. Think of it like a migration on steroids.

Creating a mapper

All mappers must extend Sprocketbox\Articulate\Entities\EntityMapper, and be registered in the configuration file.

An example mapper is as follows;

namespace App\Mappers;

use Sprocketbox\Articulate\Entities\EntityMapper;
use Sprocketbox\Articulate\Contracts\EntityMapping;

class UserMapper extends EntityMapper
{
    public function entity(): string
    {
        return App\Entities\User::class;
    }

    public function source(): string
    {
        return 'illuminate';
    }

    /**
     * @param  EntityMapping|Sprocketbox\Articulate\Sources\Illuminate\EntityMapping $mapping
     */
    public function map(EntityMapping $mapping)
    {
        $mapping->setKey('id');
        $mapping->setRepository(App\Repositories\UserRepository::class);
        $mapping->setTable('users');

        $mapping->int('id')->setImmutable();
        $mapping->string('name');
        $mapping->string('password');
        $mapping->string('email');
        $mapping->string('remember_token');
        $mapping->timestamps();
    }
}

Entity mappers have 3 methods, letting you define the different parts of the mapping.

Entity

The entity() method returns the fully qualified namespace of the entity that should be used as a representation of the data.

Source

The source() method returns a string ident for the source that should be used. Each source will have a unique ident. The example above uses the ident used for the Illuminate source.

Map

The map() method receives a single parameter that will also be an instance of Sprocketbox\Articulate\Contracts\EntityMapping. This method allows you to build up the mapping.

Each source defines its own entity mapper, and while not all will add any extra methods, some will. A prime example of this is the Illuminate source which allows you to set the table, connection and also some helpers for relationships. For more on that see sources.

Source specific mappings

It can be useful to type hint a sources entity mapper so that your IDE knows what's what.

Available Methods

By default, the injected Sprocketbox\Articulate\Contracts\EntityMapping has the following methods:

Attributes

All attributes registered in the configuration file are available here as methods using a camelCase version of the key provided in the configuration.

Available Attributes

Boolean

Entity

Integer

Json

String

Tex

Array

Component

Timestamp

Float

Uuid