Edit

Migration Guide for 4.0

BC Breaks#

We evaluate here only BC breaks you will probably encounter. This major version consists also of other minor (quite internal) BC breaks, 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;

• required Nextras Dbal 4.0

  Nextras Dbal comes with own batch of deprecations & changes. See the release notes.

• 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.

  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 collection functions

  Custom functions have been completely reworked and simplified, see docs what they can do now and how to write them.

  In short:

  • IArrayFilterFunction became IArrayFunction;
  • IQueryBuilderFilterFunction became IQueryBuilderFunction and has to return DbalExpressionResult;
  • IArrayFunction is removed, your functions have be designed as expressions;
  • IQueryBuilderFunction is removed, your functions have be designed as expressions;
• Collection's iterator throws when calling current() on invalid state

  The iterator implementation is now more typesafe. That means that calling current() method on the collection's iterator throws when the iterator is in invalid state, e.g. method next() was called after the last item. This is quite internal thing and usually you don't use it directly. However, there is a bug in nette/latte when using $iterator, accessing $iterator->nextValue may throw since nette/latte is missing a check. There is already a PR fixing this bug but until then you may fix it manually:

  // before
  {if $iterator->nextValue !== null}{$iterator->nextValue->...}{/if}
  
  // with temporal fix
  {if $iterator->getInnerIterator()->valid() && $iterator->nextValue !== null}{$iterator->nextValue->...}{/if}

• Entity: setter & getters are ONLY user-input-facings converters

  Setters and getters are no longer exectured during entity data-load. This allows new possibilites to expose data to user. However in the same time, it is quite a BC break. If you need validate / convert some data during their load from storage, please use property wrapper or onLoad event to convert the passed data.

• 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.

Deprecations#

• required Nextras Dbal 4.0

  See the release notes. You will probably encounter deprecated leftJoin and other methods, replace them with joinLeft and similar.

• Collection: removed this-> prefix for relationship traversals

  Relationship traversal newly does not require putting this-> prefix in collection filtering expression.

  $booksCollection->findBy(['this->author->name' => 'John']);
  // after
  $booksCollection->findBy(['author->name' => 'John']);

• Entity/Relationship: deprecated get() method, use toCollection()

  Relationship conversion to ICollection is newly done by toCollection() method.

  $author->books->toCollection()->findBy(...);