2.0.0

Version 2.0.0

This version was created from the tag 1.1.0, specifically.

Changes from version 1.x

• New Composer requirements
  • php:^8.3
  • eboreum/caster:^2.1
  • eboreum/exceptional:^2.0
• phpstan level 10 (up from 9).
• Removed Eboreum\Collections\Attribute\Method\Overridden, Eboreum\Collections\Contract\CollectionElementInterface, and Eboreum\Collections\Contract\GeneratedCollectionInterface. They were unused.
• Most methods are now fully typed.
• 2 exception classes removed:
  1. Eboreum\Collections\Exception\UnexpectedValueException
  2. Eboreum\Collections\Exception\InvalidArgumentException
• The 2 above-mentioned exception classes have become obsolete, mainly due to the built-in type system in PHP. They have been replaced with one of the 5 new exception classes mentioned under "New features".
• Caster now uses both wrapping and will escape ASCII control characters.
• Eboreum\Collections\StringCollection now implements Eboreum\Collections\Contract\CollectionInterface\SortableCollectionInterface, meaning it exposes the toSorted method. Internally, the space operator, <=>, is used for sorting, which does not sort correctly for all collations. For proper collation sorting, please use the newly added method, toSortedByCollator.

Fixes

None.

New features

• New methods on Eboreum\Collections\Contract\CollectionInterface:
  • findOrFail: Similar to the find method, but instead of returning null on miss, an exception is thrown.
  • firstKeyOrFail: Similar to the findKey method, but instead of returning nullwhen the collection is empty, an exception is thrown.
  • firstOrFail: Similar to the first method, but instead of returning null when the collection is empty, an exception is thrown.
  • getOrFail: Similar to the get method, but instead of returning null on miss, an exception is thrown.
  • guardCollectionInheritanceAndAcceptedElements: A common method for ensuring that the interaction between two collections (i.e. $this and an argument) is valid.
  • lastKeyOrFail: Similar to the lastKey method, but instead of returning null when the collection is empty, an exception is thrown.
  • lastOrFail: Similar to the last method, but instead of returning null when the collection is empty, an exception is thrown.
  • toDifference: Similar to array_diff, but with guards.
  • toDifferenceByKey: Similar to array_diff_key, but with guards.
  • toIntersection: Similar to array_intersect, but with guards.
  • toIntersectionByKey: Similar to array_intersect_key, but with guards.
• New method Eboreum\Collections\StringCollection->toSortedByCollator. Requires either the "intl" extension or a polyfill (e.g. symfony/polyfill-intl-icu) for the Collator class to be present. The "intl" extension is not a requirement in composer.json, but the method call will simply fail in non-compliant code bases.
• New methods Eboreum\Collections\Object_\AbstractDateTimeCollection->toTimestampIntegerCollection and Eboreum\Collections\Object_\AbstractDateTimeCollection->toMicrosecondTimestampIntegerCollection, which means they are available on Eboreum\Collections\Object_\DateTimeCollection, Eboreum\Collections\Object_\DateTimeImmutableCollection, and Eboreum\Collections\Object_\DateTimeInterfaceCollection.
• New class Eboreum\Collections\Object_\AbstractDateTimeCollection. Some of the redundant logic from the Moved DateTime*Collection classes has been moved to this abstract class.
• New interface Eboreum\Collections\Object_\DateTimeCollectionInterface, utilized by Eboreum\Collections\Object_\AbstractDateTimeCollection.
• 5 new exception classes:
  1. Eboreum\Collections\Exception\ElementNotFoundException
  2. Eboreum\Collections\Exception\InvalidClosureReturnValueException
  3. Eboreum\Collections\Exception\KeyNotFoundException
  4. Eboreum\Collections\Exception\UnacceptableCollectionException
  5. Eboreum\Collections\Exception\UnacceptableElementException
• The 5 new exception classes all extend Eboreum\Collections\Exception\RuntimeException, which should help avoid backward-compatibility breakage. They are either completely new or is now in several places being used instead of the generic Eboreum\Collections\Exception\RuntimeException.