Swat improvements

[cviebrock]

Changes

• work on moving PHPstan analysis from level 1 → 2
• fix typos and parse errors in docblocks
  • also started switching from HTML markup to Markdown in docblocks
• fix bugs in and simplify home-grown SwatNumber::roundUp() and SwatNumber::roundToEven() methods by switching to native PHP round() with PHP_ROUND_HALF_UP/PHP_ROUND_HALF_EVEN flags
  • added unit tests
• eliminate fallback code for SwatNumber::ordinal() and only use ICU-methods since the intl extension is required by the package
  • added unit tests
• convert constructors to use promoted properties where possible
• fixed PHPstan annotations on SwatDBEnumMapper (was using @template incorrectly)
• stricter typing in SwatDBRange class
  • added unit tests
• stricter typing in SwatI18N* classes
  • added unit tests
• fixed bug in SwatI18NLocale::get() where valid locales would get cached, and then could get returned for invalid lookups
• simplify formatting logic in SwatI18NLocale::formatCurrency()
  • added tests
• defer SwatI18NLocale::roundToEven() to SwatNumber::roundToEven() instead of reimplementing it
• fixed bug in SwatI18NLocale::getFractionalPrecision() where, if the underlying system local used a comma as a decimal separator, the precision was incorrectly returned
  • PHP 8.0 always uses a "." as a decimal separator when converting a float to a string, so we don't need to involve the locale at all when searching for digits after the decimal
• SwatI18NNumberFormat (and therefore SwatI18NCurrencyFormat) no longer extend SwatObject, so no longer have need for a __toString() method
  • removed methods and method tests

New Features

• SwatDBRecordsetWrapper should now properly infer the type of it's records if marked up correctly. Child classes should add the following notation to the class-level docblock:

  @extends SwatDBRecordsetWrapper<XXX>
  

  where XXX is the class being wrapped. For example, a ChapterWrapper class would look like:

  /**
   * @extends SwatDBRecordsetWrapper<Chapter>
   */
  class ChapterWrapper extends SwatDBRecordsetWrapper
  {
      protected function init()
      {
          parent::init();
  
          $this->row_wrapper_class = SwatDBClassMap::get(Chapter::class);
          $this->index_field = 'id';
      }
  }

Potential Breaking Changes

• strict typing to SwatDB::getGroupedOptionArray() and SwatDB::initArray() may require downstream changes
• clarified return types on some SwatDBDataObject methods; downstream overrides should be checked that they conform:
  • hasSubDataObject($key): bool
  • setDatabase(MDB2_Driver_Common $db, array $set = []): void
  • save(): void (from SwatDBRecordable)
  • load(mixed $id): bool (from SwatDBRecordable)
  • delete(): void (from SwatDBRecordable)
  • isModified(): bool (from SwatDBRecordable)
  • checkDB(): void
  • setFlushableCache(SwatDBCacheNsFlushable $cache): void (from SwatDBFlushable)
  • marshall(array $tree = []): array (from SwatDBMarshallable)
  • unmarshall(array $data = []): void (from SwatDBMarshallable)
  • getSerializableSubDataObjects(): array
  • getSerializablePrivateProperties(): array