Feature: Added generic default classes

Feature: All traits support \JsonSerializable. IsCollectionType and derivatives support \Iterator.
Feature: Added Percentage and Email classes
Feature: Several new methods on IsCollectionType (merge, withMerged, pop, popMultiple, split, shuffle, withReversedOrder)
Improvement: Psalm annotations for IDE type hints and autocompletion. Use @extends to make use of it (see README examples)
Improvement: More specific error message when adding/subtracting values that bring the total above maximum/below minimum allowed value
Improvement: InvalidValue renders different types better instead of wrapping everything in double quotes
Improvement: Option to get $reasons back from ConversionError after instantiation
Dev: Library tested against PHP 8.4 (no changes were necessary)
Dev: Upgraded PhpUnit from 9 to 11.5 and Infection from don't-remember to 0.29.0 (latest)
Dev: Upgrades improved MSI from 97% to 99%, MCC from 98% to 99% and CC-MCI from 98% to 100%.

----------------------------------

Squashed commit of the following:

commit c211916
Author: Jay Atkins <[email protected]>
Date:   Tue Dec 24 12:39:03 2024 +0000

    Misc: Updated README and CHANGELOG

commit a486b47
Author: Jay Atkins <[email protected]>
Date:   Tue Dec 24 00:23:24 2024 +0000

    Improvement: Added jsonSerialize to all types, and implemented \JsonSerializable in generic classes.

    Updated README.md.
    Added required tests and ran test suite.
    Re-ran Infection and looked through infection.log. Only false positives left.
    Updated badges.

commit 903a5af
Author: Jay Atkins <[email protected]>
Date:   Sun Dec 22 22:10:22 2024 +0000

    Tests: Upgraded from Phpunit 10.5 to 11.5 (this was a forced update, as the testdox option was removed in 10.5 but brought back in 11.5)*
    Tests: Run Infection and fixed any true issues (ignoring false positives of course)
    Tests: Changed from using @Covers, @uses, @dataProvider, @Depends to using relevant attributes

    Running the tests with testdox means that only errors are printed, not every single assertion with a tick or an X.
    For over 1,500 assertions, it meant that finding errors was incredibly frustrating and time-consuming.
    In PhpUnit 11.5 it is called testdoxSummary, as opposed to testdox (as it was called in PHPUnit 8), and isn't available at all in PhpUnit 9.5.

commit 215d8a0
Author: Jay Atkins <[email protected]>
Date:   Sun Dec 22 17:38:16 2024 +0000

    Feature: Added more methods to IsCollectionType.

        - `merge`
        - `withMerged`
        - `pop`
        - `popMultiple`
        - `split`
        - `shuffle`
        - `withReversedOrder`

    Tests: Added missing Unit tests and fixed pre-existing ones. Back to 100% test coverage.
    Tests: Ran all tests against PHP 8.4. No changes to code required - all tests successful.
    Misc: Updated CHANGELOG.md

    TODO:
    - Update README.md
    - Run Infection and fix accordingly.

commit 07c4da4
Author: Jay Atkins <[email protected]>
Date:   Sun Jun 23 13:12:23 2024 +0100

    WIP: Added Any* classes and made changes to ConversionError
    TODO: Re-run all tests

.env.dist

@@ -1,2 +1,5 @@
 LIBRARY_NAME=value-types
-USER_ID=1000
+USER_ID=1000
+
+# Used by composer
+COMPOSER_ROOT_VERSION=2.7

.nvmrc

@@ -0,0 +1 @@
+v20.15.0

README_dev.md

@@ -1,5 +1,26 @@
 # Development
 
+## Table of Contents
+
+- [Tests](#tests)
+  - [Set-up](#set-up)
+  - [Run tests](#run-tests)
+    - [Multiple PHP versions](#multiple-php-versions)
+    - [Commands to run tests](#commands-to-run-tests)
+    - [Run a specific test](#run-a-specific-test)
+      - [Class/Method](#method-or-class)
+      - [Named data set](#named-data-set)
+      - [Unnamed data set](#unnamed-data-set)
+    - [Adding new tests](#adding-new-tests)
+- [Dependencies](#dependencies)
+- [Commits](#commits)
+  - [Validate composer.json](#validate-composerjson)
+  - [Update CHANGELOG.md](#update-changelogmd)
+  - [Regenerate badges with new code coverage scores](#regenerate-badges-with-new-code-coverage-scores)
+  - [Regenerate the README.md file](#regenerate-the-readmemd-file)
+  - [Tag your commit](#tag-your-commit)
+
+
 ## Tests
 
 
@@ -8,55 +29,114 @@ In order to be able to run tests, go through the following steps to set up the D
 
 
 #### Download and build the Docker image
-`docker-compose build --build-arg UID=`id -u` lib`
+`docker-compose build --build-arg UID=`id -u` lib84 lib81`
+
+or: (make sure that `USER_ID` in the `.env` file is correct)
+
+`docker compose up --build`
 
 
 #### Install dependencies
 
-`docker-compose run lib composer install`
+`docker-compose run lib84 composer install`
 
 
 ### Run tests
 
+#### Multiple PHP versions
+
+Since version `2.7`, we have more than one Dockerfile, to run the tests against more than one PHP version.
+
+There is only one `vendor` folder as we're not changing the minimum required PHP version dependency, so you only need to install them on the `lib81` service, and they'll automatically be available to `lib84` too.
+
+In order to run the PHP 8.1 container, you'd use:
+`docker compose run --rm lib81 vendor/bin/phpunit`
+
+In order to run the PHP 8.4 container, you'd use:
+`docker compose run --rm lib84 vendor/bin/phpunit`
+
+*Wherever you see `run --rm lib84` in this file, update the last 2 numbers to run the relevant PHP version (if available), e.g. `run --rm lib81`. (The `--rm` flag makes sure that the container instance is removed once the command has finished executing, avoiding orphans).*
+
+
+#### Commands to run tests
+
 To run mutation tests:
-`docker-compose run lib php infection.phar`
+`docker compose run --rm lib84 php infection.phar`
 
 To run the unit tests:
-`docker-compose run lib vendor/bin/phpunit`
+`docker compose run --rm lib84 vendor/bin/phpunit`
 
 To create a code coverage report in HTML style:
-`docker-compose run lib vendor/bin/phpunit --coverage-html ./coverage-report`
+`docker compose run --rm lib84 vendor/bin/phpunit --coverage-html ./coverage-report`
 
 To create a quick code coverage overview in the CLI:
-`docker-compose run lib vendor/bin/phpunit --coverage-text`
+`docker compose run --rm lib84 vendor/bin/phpunit --coverage-text`
 
 
 #### Run a specific test
 
+##### Method or Class
+
 To run a specific class, or method, run:
 
-`docker-compose run lib vendor/bin/phpunit --filter testWithValueDoesNotChangePreExisting`
+`docker compose run --rm lib84 vendor/bin/phpunit --filter testWithValueDoesNotChangePreExisting`
 
 where `testWithValueDoesNotChangePreExisting` is the name of the method. You can also use the name of a class instead.
 
+
+##### Named data set
+
 To run a specific data set (when using data providers), you can use the name of the data set after the `@`, e.g.:
 
-` docker-compose run lib vendor/bin/phpunit --filter testWithValueDoesNotChangePreExisting@invalidNumber`
+` docker compose run --rm lib84 vendor/bin/phpunit --filter testWithValueDoesNotChangePreExisting@invalidNumber`
 
 where `testWithValueDoesNotChangePreExisting` is the name of the method, and `invalidNumber` is the name of the data set. Note that this only works with non-numeric data set names.
 
 
+##### Unnamed data set
+
+If you have unnamed data sets, you can still run an individual using the following syntax:
+
+`--filter methodName#dataSetNumber`
+
+E.g.: 
+`docker compose run --rm lib84 vendor/bin/phpunit testFromStringWithValidValue#3`
+
+Data set numbers start from 0.
+You can also use ranges:
+
+`docker compose run --rm lib84 vendor/bin/phpunit testFromStringWithValidValue#3-5`
+
+The above will run any test methods that are named "testFromStringWithValidValue", but only with the 4th, 5th and 6th data set.
+
+For more information, see the PhpUnit documentation.
+
+
 #### Adding new tests
 
 Remember that each test method name needs to start with "test", otherwise it will be ignored by PhpUnit.
 
 
+#### Removing orphaned containers
+
+If you see a lot of container names when running tests and the error message `If you removed or renamed this service in your compose file, you can run this command with the --remove-orphans flag to clean it up.`, you'll probably trust the message and run the same command again but with the `--remove-orphans` flag.
+This then results in you seeing `Unknown option "--remove-orphans"`, and thinking "...Wtf?"
+
+Despite the message telling you otherwise, the `--remove-orphans` flag is only available on the `docker compose up` and `docker compose down` command, so just run the following to clear them:
+
+```bash
+docker compose up --remove-orphans
+```
+
+In order to avoid orphans in the first place, run all commands with `--rm`, which removes the container automatically once it's finished executing. 
+
+
 ## Dependencies
 
 ### Adding new dev dependencies
 
 Use the --dev option when requiring new dev dependencies via composer:
-`docker-compose run lib composer require --dev phpunit/phpunit ^9`
+`docker compose run --rm lib84 composer require --dev phpunit/phpunit ^9`
 
 
 ## Commits
@@ -76,7 +156,7 @@ Any slightly more "complex" tasks have been detailed below.
 
 ### Validate composer.json
 
-Run `docker-compose run lib composer validate` to make sure `composer.json` is still valid.
+Run `docker compose run --rm lib84 composer validate` to make sure `composer.json` is still valid.
 
 
 ### Update CHANGELOG.md
@@ -97,15 +177,15 @@ If there are versions missing in CHANGELOG, add them. These commands should help
 ### Regenerate badges with new code coverage scores
 
 Run this command (but don't forget substituting values with the current values):
-`docker-compose run lib php docs/generateBadges.php --cc=0 --msi=0 --mcc=0 --ccm=0`
+`docker compose run --rm lib84 php docs/generateBadges.php --cc=0 --msi=0 --mcc=0 --ccm=0`
 
 *Round all percentages to 0 decimals. Round down until .49, round up from .5.*
 
 #### cc
-`cc` is the Code Coverage percentage of covered methods. You get this value by running `docker-compose run lib vendor/bin/phpunit --coverage-text` and taking the "Methods" percentage from the summary section.
+`cc` is the Code Coverage percentage of covered methods. You get this value by running `docker compose run --rm lib84vendor/bin/phpunit --coverage-text` and taking the "Methods" percentage from the summary section.
 
 #### msi, mcc, ccm
-All of these values are taken from the Infection summary. Run `docker-compose run lib php infection.phar`, which gives you a "Metrics" section, from which you take the following percentages:
+All of these values are taken from the Infection summary. Run `docker compose run --rm lib84php infection.phar`, which gives you a "Metrics" section, from which you take the following percentages:
 
 msi: Mutation Score Indicator
 

composer.json

@@ -22,6 +22,6 @@
     "minimum-stability": "stable",
     "require-dev": {
 		"ext-gd": "*",
-        "phpunit/phpunit": "^9"
+        "phpunit/phpunit": "^11.5"
     }
 }