From 160386e80d4f6c81b1e20119cacecf2645c15bf8 Mon Sep 17 00:00:00 2001 From: Jan Skrasek Date: Sun, 16 Aug 2020 21:32:59 +0200 Subject: [PATCH] doc: add migration guide for 4.0 --- doc/menu.texy | 3 +- doc/migrate_2.0.texy | 163 ------------------------------------------- doc/migrate_3.0.texy | 63 ----------------- doc/migrate_4.0.texy | 45 ++++++++++++ 4 files changed, 46 insertions(+), 228 deletions(-) delete mode 100644 doc/migrate_2.0.texy delete mode 100644 doc/migrate_3.0.texy create mode 100644 doc/migrate_4.0.texy diff --git a/doc/menu.texy b/doc/menu.texy index 8f5aefef..e67b811d 100644 --- a/doc/menu.texy +++ b/doc/menu.texy @@ -19,5 +19,4 @@ Tutorials: .[h4] - [Embeddables | embeddables] - [UniqueConstraint | unique-constraint] -- [Migration to 3.0 | migrate_3.0] -- [Migration to 2.0 | migrate_2.0] +- [Migration to 4.0 | migrate_4.0] diff --git a/doc/migrate_2.0.texy b/doc/migrate_2.0.texy deleted file mode 100644 index ad3f84d2..00000000 --- a/doc/migrate_2.0.texy +++ /dev/null @@ -1,163 +0,0 @@ -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. - /--php - /** - * @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 symmetric (newly, relationship can be oneSided, see [Relationships | 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. - /--php - 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. - /--php - // 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 | relationships] chapter. - /--php - // 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. diff --git a/doc/migrate_3.0.texy b/doc/migrate_3.0.texy deleted file mode 100644 index 1f3d951b..00000000 --- a/doc/migrate_3.0.texy +++ /dev/null @@ -1,63 +0,0 @@ -Migration Guide for 3.0 -####################### - -BC breaks -========= - -The following BC breaks are quite important and you will probably have to deal with them in your code: - -- **required PHP 7.0 and new types** - We have added scalar types to Orm interfaces; your repository and mapper will have to be probably updated; -- **Collection: removed comparison operator `!`** - We have removed `!` comparison operator that has been a duplicated of `!=`; use equivalent `!=` operator; - /--php - $collection->findBy(['name!' => 'Jon']); - // replace with - $collection->findBy(['name!=' => 'Jon']); - \-- -- **Entity: all `datetime` property types have to be replaced with `\DateTimeImmutable` type;** - We have dropped support for simple `DateTime`, in fact, there is no useful usecase for the mutable type. - During the entity parsing all places will be checked and exception will be thrown if you use the muttable date time. - /--php - /** - * @property DateTime $born - */ - class MyEntity extends Nextras\Orm\Entity\Entity {} - - // replace with - /** - * @property DateTimeImmutable $born - */ - class MyEntity extends Nextras\Orm\Entity\Entity {} - \-- -- **IEntity::toArray() method was moved away from Entity** - The `Nextras\Orm\Entity\Entity` still contains `toArray()` method; The conversion type constants were moved to the helper. - See the "[commit]":https://github.com/nextras/orm/commit/1f01f75dd5627c25ab8fb745c8b3261bed455849; -- **IEntity::setAsModified() method does not return the entity** - See the "[commit]":https://github.com/nextras/orm/commit/a7c6d7201d58a615e2ecc0f079f12f9e9344a9c3; -- **IEntity::hasValue() throws an exception when property does not exist** - See the "[commit]":https://github.com/nextras/orm/commit/a7c6d7201d58a615e2ecc0f079f12f9e9344a9c3; -- **Entity: all event methods are included in the interface definition** - The events method are currently included in th interface and are called directly when the event should be fixed; Therefore if you override the methods, you will have to changed their visibility modifier to public; "[commit]":https://github.com/nextras/orm/commit/548faa1e7c716f0f0717a5fe0ce5e39fa2a8c669; -- **Entity relationships: removed duplicate relationship names in property modifiers** - We have cleaned up the relationship names, currently supported are only these with the letter `m`, e.g. `1:m`, `m:1`, `m:m` as abbreviation of the Many word; "[commit]":https://github.com/nextras/orm/commit/1cc1f2464f15d45265bea1cbd5e59001eb8f4b58; -- **Mapper: proxy calls from repository have to return ICollection or IEntity|null** - We have dropped the magic; the proxied methods on mapper have to return already converted results as ICollection or IEntity|null; to achieve this, use DbalMapper::toCollection() or DbalMapper::toEntity() methods; "[commit]":https://github.com/nextras/orm/commit/a7a2744b7a769f472297aa6319d55aceeb0cce81; -- **Dbal changes** - Orm 3.0 requires Nextras Dbal 3.0. Dbal brings datetime handling changes, generally speaking, if you use columns with timezone support, you should be pretty safe to upgrade. See Dbal "3.0.0 release notes":https://github.com/nextras/dbal/releases/tag/v3.0.0. - - -The following BC breaks are quite internal, in other words, you probably will not have to do anything because of them: - -- Model: refactored internals to use Repository loader. - See the "[commit]":https://github.com/nextras/orm/commit/0af0c911a5dddf4f58fc4184f921beff6c393403; -- Entity: removed serialization support, the support was not tested and well covered. - We encourage to serialize entity id and refetch the entity every time you need it; -- Entity: method getRepository throws an exception, when entity is not attached to repository; - To check the state use the `IEntity::isAttached()` method; -- Entity: virtual properties are never implicitly stored; - We have removed `IEntity::SKIP_SET_VALUE`; "[commit]":https://github.com/nextras/orm/commit/987ca131e7bc2b49dcdb2d7963ed9c221f0f78c7; -- Entity relationships: refactored iterators and collections internals; - See the relevant commits: "[commit]":https://github.com/nextras/orm/commit/f4cf22baef87a7ad5232d6d877616e96f1b67d36, "[commit]":https://github.com/nextras/orm/commit/eabd333e96b026debc9fe5c63ea9347725638625, "[commit]":https://github.com/nextras/orm/commit/f3a589a4b7e640b94079a5d60dc82ed0920c01fc; -- Entity|Repository: event handling was refactored to own methods, removed fireEvent() methods and replaced with custom methods for each event. -- Repository|Mapper|Model: many interface changes. diff --git a/doc/migrate_4.0.texy b/doc/migrate_4.0.texy new file mode 100644 index 00000000..363fd281 --- /dev/null +++ b/doc/migrate_4.0.texy @@ -0,0 +1,45 @@ +Migration Guide for 4.0 +####################### + +We evaluate here only BC breaks you will probably encounter. This major version consists also of other minor BC breaks which are quite internal, i.e. the probability you don't use these semi-public API is quite high. + +- **required PHP 7.1 and new types** + We have added scalar types to Orm interfaces; Some of you implementations have to be updated; +- **Removed BaseMapper & Collection** + These classes were just pure aliases. Use specific implementations (DbalMapper / DbalCollection) directly. +- **StorageReflection renamed to Conventions** + We have renamed StorageReflection classes to Conventions. New name better covers what these classes do. Also, the property name changes from underscored to pascal-cased is handled by inflector class, not by inheritance anymore. + /--php + class BooksMapper extends DbalMapper + { + // change inflection from SnakeCaseInflector + protected function createInflector(): IInflector + { + return new CamelCaseInflector(); + } + + // add mapping + protected function createConventions(): IConventions + { + $conventions = parent::createConventions(); + $conventions->setMapping('price->cents', 'price'); + return $conventions; + } + } + \-- +- **Collection namespace restructured** + ArrayCollection and DbalCollection moved to Collection sub-namespace; helper classes moved and renamed; +- **Collection: reworked custom collection functions** + Custom functions have been completely reworked and simplified, see [docs | collection-functions] what they can do now and how to write them. +- **Collection: removed `this->` prefix for relationship traversals** + Relationship traversal newly does not require putting `this->` prefix in collection filtering expression. + /--php + $booksCollection->findBy(['this->author->name' => 'John']); + // after + $booksCollection->findBy(['author->name' => 'John']); + \-- +- **Entity: renamed property containers to property wrappers** + This is purely naming change when property containers are called wrappers. Use new `{wrapper YourClass}` modifier. +- **Entity: ImmutableValuePropertyContainer was reworked** + ImmutableValuePropertyContainer - a helper for property wrapper was reworked and renamed to ImmutableValuePropertyWrapper. + Change contains renamed APIs, wrapper does not depend on entity, and doesn't handle null for you, i.e. you can have now easily nullable property wrapper.