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.

1.1.0

• New method: "toReindexed"
  Make a clone of the current collection, indexed by (i.e. keys being changed) the logic provided in a Closure. Very useful for indexing database records, which has a unique column (ID (often AUTO_INCREMENT), UUID, and similar). In case of duplicate keys, the default behavior is that an exception is thrown. However, this may be changed so that no exception is thrown and instead either the first or the last encountered element with the same key is used.
• CollectionInterface: Added proper @param Closure type hints, explaning the parameters and return types involved.
• Various coding style fixes.

1.0.0

Version 1.0.0 is here!