A data mapper is an instance of a class that implements the Opis\Orm\IDataMapper interface. This interface provides several methods that can be used to manipulate the data associated with an entity. This data represents a row that is or will be stored into a table.

Getting column values

Getting the value of a column is done with the help of the getColumn method.

class User extends Entity
{
    public function name(): string
    {
        return $this->orm()->getColumn('name');
    }
}

If a casting type was specified for this column, the method will take care of casting the value to match the specified casting type. Also, if a getter callback was set for this column, the callback will be called by passing the value as an argument and the result return by the callback will be considered the new value of the column. At the end, the value of the column will be cached and finally returned. Any subsequent calls to this method will result in returning the cached value.

To clear the cached value, and force a rebuild, use the clearColumn method

$this->orm()->clearColumn('name');

Getting the columns’ raw value is done by using the getRawColumns method.

$columns = $this->orm()->getRawColumns();

Setting column values

Setting the value of a column is done by using the setColumn method. This method will first call the setter callback (if any), then it will cast the resulted value to match the specified type (if such casting rule was defined), and in the end, the resulted value will be set as the raw value of the column.

class User extends Entity
{
    public function setName(string $value): void
    {
        $this->orm()->setColumn('name', $value);
    }
}

If you want to set the raw value directly, use the setRawColumn method

$this->orm()->setRawColumn('foo', $value);

You can also perform a mass assignment of values, by using the assign method.

$this->orm()->assign([
    'name' => 'John Doe',
    'age' => 24
]);

Getting a list of modified columns is done by calling the getModifiedColumns method

$modified = $this->orm()->getModifiedColumns();

Handling relationships

Getting a related entity is done by calling the getRelated method. This method takes a single argument, representing the name of the relationship.

class User extends Entity
{
    public function profile(): Profile
    {
        return $this->orm()->getRelated('profile');
    }
}

The value returned by calling this method will be cached, and subsequent calls to this method will return the cached value. The cached value can be cleared by using the clearRelated method.

$this->orm()->clearRelated('profile');

Setting a related entity value is done by using the setRelated method. The first argument that this method takes, represents the relationship name, while the second argument must be an instance of an entity or null.

class User extends Entity
{
    public function setProfile(Profile $value): void
    {
        $this->orm()->setRelated('profile', $value);
    }
}

Linked entities

If the type of the relationship between two entities is either shareOne or shareMany, then setting a related entity is done with the help of the link method.

class User extends Entity
{
    public function addHobby(Hobby $value): void
    {
        $this->orm()->link('hobies', $value);
    }
}

This kind of relationships allow you to remove the link between two entities and make them unrelated. This can be accomplished with the help of the unlink method.

$this->orm()->unlink('hobbies', $value);

Reload data

If you want to force a data mapper hydration, you can simply specify that the values contained by the data mapper are stale.

$this->orm()->stale();

Meta information

Checking if the data mapper was altered, by either setting a column’s value or by setting a relationship, is done with the help of the wasModified method.

if($this->orm()->wasModifed()) {
    // do something
}

If you want to check if the row referenced by the data mapper was persisted or not into a database, simply use the isNew method

if ($this->orm()->isNew()) {
    // never persisted
}

Checking if the row referenced by the data mapper was deleted is done with the help of the isDeleted method.

if ($this->orm()->isDeleted()) {
    // row was deleted
}

You can also check if the row referenced by a data mapper is available only for reading

if ($this->orm()->isReadOnly()) {
    // just for reading
}