Migration Guide for 2.0

General#

Minimal PHP version was increased to 5.5.
Orm requires Nextras Dbal 2.0.

Entity#

Each entity has to define primary property; use primary or primary-proxy modifier.

/**
 * @property int $id {primary}
 * @property int $followers {1:m BookFollowers::$book}
 * ...
 */
class Book extends Nextras\Orm\Entity\Entity {}

/**
 * @property int $id {primary-proxy}
 * @property Book $book {m:1 Book::$followers} {primary}
 * @property User $user {m:1 User::$followedBooks} {primary}
 * ...
 */
class BookFollowers extends Nextras\Orm\Entity\Entity {}

1:1d relationship modifier was renamed to 1:1. The old 1:1 relationship support was removed entirely.
```
// old
{1:1d UserEntity::$meta primary}

// new
{1:1 UserEntity::$meta, isMain=true}
```

New format for modifier syntax: each argument has to be separated by comma; values are assigned by =; values can be an array.

// old
{modifier value another key:value}
{enum self::ONE_CONSTANT self::ANOTHER}

// new
{modifier value, another, key=value, arrayValue=[val1, val2]}
{enum self::ONE_CONSTANT, self::ANOTHER}

Relationship modifiers requires defined target property, if relationship is symetric (newly, relationship can be oneSided, see Relationships chapter). Old and deprecated relationship format was removed.
```
// old
{1:m UsersRepository}
{1:m UsersRepository $posts}

// new
{1:m UserEntity::$posts}
{1:m UserEntity::$posts}
```

Changes were made to keys names and accepted values of Relationship modifiers.

order → orderBy

primary → isMain

// old
{1:m UserEntity::$posts order:id}
{1:m UserEntity::$posts order:id,DESC}

// new
{1:m UserEntity::$posts, orderBy=id}
{1:m UserEntity::$posts, orderBy=[id, DESC]}


// old
{m:m UserEntity::$posts primary}

// new
{m:m UserEntity::$posts, isMain=true}

Modifiers no longer allow random and unused parameters.
```
// old
{primary foo bar}
```
Modifiers now supports literal parsing, this may break some expresions that were previously parsed as string, now they are evaluated as in php.
```
// old - resulted into string "123"
{default 123}

// new
{default "123"}
// or for int
{default 123}
```

Repository#

Each repository has to define static method getEntityClassNames() that returns accepted entity class names.

class BooksRepository extends Nextras\Orm\Repository\Repository
{
     public static function getEntityClassNames()
     {
          return [Book::class];
     }
}

Repository no longer supports @method annotations that are not proxies for its mapper; you have to rewrite these methods manually.

// old

/**
 * @method Book|null getByTitle($title)
 */
class BooksRepository extends Nextras\Orm\Repository\Repository
{
     // ...
}


// new

class BooksRepository extends Nextras\Orm\Repository\Repository
{
     // ...

     /**
      * @param  string $title
      * @return Book|null
      */
     public function getByTitle($title)
     {
          return $this->getBy(['title' => $title]);
     }
}

Recursive remove no longer works. The second parameter of IRepository::remove() method was renamed to $withCascade. The cascade is definied as a parameter in relationship modifier, the removal cascade is not added by default, only the perists one. See Relationships chapter.
```
// old
$authorRepository->remove($author, true);

// new
/**
 * @property OneHasMany|Book[] $books {1:m Book::$author, cascade=[persist, remove]}
 */
class Author extends Nextras\Orm\Entity\Entity {}
$authorRepository->remove($author, true);
```

Mapper#

Removed DbalMapper::createCollection() method. Override findAll() method to modify maximal set of entities.
DbalMapper was refactored, if you are overriding relationship mappers, you have to do this by new createRelationshipMapper() and getRelationshipMapper() methods.

Orm

Documentation