Edit

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;

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

  /**
   * @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];

• IEntity::setAsModified() method does not return the entity

  See the [commit];

• IEntity::hasValue() throws an exception when property does not exist

  See the [commit];

• 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];

• 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];

• 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];

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

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];

• 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];

• Entity relationships: refactored iterators and collections internals;

  See the relevant commits: [commit], [commit], [commit];

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