Merge branch 'develop'

* develop:
  specify next release
  do not throw if the transaction fail to start
  add upgrade documentation
  update documentation
  typo
  express the transaction failures in the return type of Manager::transactional()
  make transactions use Attempt
  make Repository::put() and ::remove() return an Attempt<SideEffect>
  make Repository::effect() return an Attempt<SideEffect>
  fix type declaration
  remove deprecated PointInTimeType::of()
  test against php 8.4
  update dependencies
  discard psalm error
  remove unused code

Author: Baptouuuu

.github/workflows/ci.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        php-version: ['8.2', '8.3']
+        php-version: ['8.2', '8.3', '8.4']
         dependency-versions: ['lowest', 'highest']
         mariadb: ['10', '11']
         elasticsearch: ['7.17.18']
@@ -60,7 +60,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        php-version: ['8.2', '8.3']
+        php-version: ['8.2', '8.3', '8.4']
         dependency-versions: ['lowest', 'highest']
     name: 'Coverage'
     services:
@@ -113,7 +113,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php-version: ['8.2', '8.3']
+        php-version: ['8.2', '8.3', '8.4']
         dependency-versions: ['lowest', 'highest']
     name: 'Psalm'
     steps:

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 5.0.0 - 2025-06-04
+
+### Changed
+
+- Requires `innmind/foundation:~1.1`
+- `Formal\ORM\Definition\Type\PointInTimeType\Format` has been renamed `Formats` and is now an enum
+- `Formal\ORM\Repository::effect()` now returns an `Innmind\Immutable\Attempt<Innmind\Immutable\SideEffect>`
+- `Formal\ORM\Repository::put()` now returns an `Innmind\Immutable\Attempt<Innmind\Immutable\SideEffect>`
+- `Formal\ORM\Repository::remove()` now returns an `Innmind\Immutable\Attempt<Innmind\Immutable\SideEffect>`
+- `Formal\ORM\Adapter\Transaction` methods now uses `Innmind\Immutable\Attempt` to handle errors
+- `Formal\ORM\Manager::transactional()` may also return a `Formal\ORM\Adapter\Transaction\Failure` as a left value
+
+### Removed
+
+- `Formal\ORM\Definition\Type\PointInTimeType::of()`
+
+### Fixed
+
+- Float properties couldn't not be loaded from Elasticsearch
+
 ## 4.1.1 - 2025-05-02
 
 ### Fixed

README.md

@@ -55,6 +55,6 @@ This simple example will retrieve from the database `50` elements (from index `1
 
 ## Documentation
 
-Full documentation available in the [here](https://formal-php.github.io/orm/).
+Full documentation available [here](https://formal-php.github.io/orm/).
 
 [^1]: Object Relational Mapping

composer.json

@@ -16,18 +16,11 @@
     },
     "require": {
         "php": "~8.2",
-        "innmind/immutable": "^5.14.3",
-        "innmind/specification": "~4.1",
+        "innmind/foundation": "~1.1",
         "ramsey/uuid": "~4.7",
-        "innmind/reflection": "~5.1",
-        "innmind/filesystem": "~7.4",
-        "innmind/json": "~1.3",
-        "innmind/time-continuum": "~3.3",
         "innmind/type": "~1.2",
         "formal/access-layer": "~4.2",
-        "innmind/http-transport": "~7.2",
-        "innmind/url-template": "~3.1",
-        "innmind/validation": "~1.4"
+        "innmind/url-template": "~3.1"
     },
     "autoload": {
         "psr-4": {
@@ -43,7 +36,6 @@
     "require-dev": {
         "innmind/static-analysis": "^1.2.1",
         "innmind/black-box": "~6.1",
-        "innmind/coding-standard": "~2.0",
-        "innmind/operating-system": "~5.2"
+        "innmind/coding-standard": "~2.0"
     }
 }

documentation/blog/posts/mass-update.md

@@ -12,11 +12,15 @@ In the latest release Formal now offers a way to update multiple aggregates dire
 Until now to update multiple aggregates you'd have to fetch all of them, update each one and then put them back in the repository. It would look something like this:
 
 ```php
+use Innmind\Immutable\SideEffect;
+
 $users = $orm->repository(User::class);
 $users
     ->all() #(1)
     ->map(static fn(User $user): User => $user->rename('Alice'))
-    ->foreach($users->put(...)); #(2)
+    ->sink(SideEffect::identity())
+    ->attempt(static fn($_, User $user) => $users->put($user))
+    ->unwrap(); #(2)
 ```
 
 1. or `->matching()` with some [specification](../../specifications/index.md)

documentation/getting-started/persist.md

@@ -9,16 +9,12 @@ In order to persist an aggregate you need 3 things:
 Translated into code this gives:
 
 ```php
-use Innmind\Immutable\Either;
-
 $user = User::new('alice');
 $users = $orm->repository(User::class);
 $result = $orm->transactional(
-    static function() use ($repository, $user) {
-        $repository->put($user);
-
-        return Either::right(null);
-    };
+    static fn() $repository
+        ->put($user)
+        ->either(),
 );
 ```
 
@@ -33,14 +29,17 @@ The `$users` repository is the abstraction that _represent all users_ in the sto
 
     Use your best judgment to choose the best option for your need.
 
-`$orm->transactional()` will start a transaction via the storage used by the ORM. It will then call the callable you passed to it. If the returned value is an `Either` with a value on the right side it will commit the transaction and return the `Either` object as the `$result` variable. If the `Either` contains a value on the left side it will rollback the transaction and return the `Either` object as the `$result` variable. If the callable throws an exception it will rollback as well an rethrow the exception.
+`$orm->transactional()` will start a transaction via the storage used by the ORM. It will then call the callable you passed to it. If the returned value is an `Either` with a value on the right side it will commit the transaction and return the `Either` object as the `$result` variable. If the `Either` contains a value on the left side it will rollback the transaction and return the `Either` object as the `$result` variable. If the callable throws an exception it will rollback as well and rethrow the exception.
+
+??? note
+    The left side of the `$result` `Either` may also contain a `Formal\ORM\Adapter\Transaction\Failure` if the commit or rollback failed itself.
 
 `$repository->put()` will call the storage to persist the aggregate. At this point the ORM knows to create the aggregate because it's unaware before that of its `Id` object reference. After the `put` the ORM is now aware of this id and if you do another `put` it will try to update the same entry in the storage. (1)
 { .annotate }
 
 1. That's why you can't clone an `Id` object as the ORM would no longer know if it needs to insert or update the aggregate.
 
-Finally we return `Either::right(null)` to tell the ORM to commit the transaction. We use `null` because there's no business logic done here. But you could imagine returning a computed value instead, or return a business error object on the left side of the `Either`.
+Finally we return `->either()` to tell the ORM to commit the transaction. We use the `SideEffect` returned by the `->put()` call because there's no business logic done here. But you could imagine returning a computed value instead, or return a business error object on the left side of the `Either`.
 
 This example only persist one aggregate but you can persist as many as you want.
 

documentation/getting-started/remove.md

@@ -9,19 +9,15 @@ In order to remove an aggregate you need 3 things:
 Translated into code this gives:
 
 ```php
-use Innmind\Immutable\Either;
-
 $users = $orm->repository(User::class);
 $result = $orm->transactional(
-    static function() use ($repository) {
-        $repository->remove(Id::of(User::class, 'alice-uuid'));
-
-        return Either::right(null);
-    };
+    static fn() => $repository
+        ->remove(Id::of(User::class, 'alice-uuid'))
+        ->either(),
 );
 ```
 
-If alice exists in the storage it will remove it and if it doesn't then nothing will happen. And like for [persisting](persist.md) the `Either::right(null)` will indicate to `transactional` to commit the transaction.
+If alice exists in the storage it will remove it and if it doesn't then nothing will happen. And like for [persisting](persist.md) the `->either()` will indicate to `transactional` to commit the transaction.
 
 ??? note
     If you want to remove multiple aggregates at once corresponding to a set of criteria head to the [Specification chapter](../specifications/index.md).

documentation/getting-started/update.md

@@ -59,7 +59,7 @@ $orm->transactional(
             ->get(Id::of(User::class, 'alice-uuid'))
             ->map(static fn(User $alice) => $alice->rename('bob'))
             ->match(
-                static fn(User $bob) => $repository->put($bob),
+                static fn(User $bob) => $repository->put($bob)->unwrap(),
                 static fn() => null,
             );
 
@@ -88,16 +88,17 @@ And like for persisting an aggregate we return `Either::right(null)` to commit t
         static fn() => $repository
             ->get(Id::of(User::class, 'alice-uuid'))
             ->map(static fn(User $alice) => $alice->rename('bob'))
-            ->map($repository->put(...))
+            ->attempt(static fn() => new \Exception('User not found'))
+            ->flatMap($repository->put(...))
             ->either(),
         },
     );
     ```
 
     This does the same thing except one thing. If alice doesn't exist it will rollback the transaction instead of committing it, but this doesn't change the end result.
 
-    `->map($repository->put(...))` this will call the `put` method if there was an alice that has been renamed to bob on the line before. 
+    `->flatMap($repository->put(...))` this will call the `put` method if there was an alice that has been renamed to bob on the line before.
 
-    `->either()` this transforms the `Maybe<void>` to an `Either<null, void>`. The `void` type is the return type of the `put` method and the `null` is when alice doesn't exist. That's why we rollback if alice doesn't exist, the returned `Either` contains `null` on the left side.
+    `->either()` this transforms the `Attempt<SideEffect>` to an `Either<\Throwable, SideEffect>`. That's why we rollback if alice doesn't exist, the returned `Either` contains `\Throwable` on the left side.
 
     Also note that all this is lazy evaluated, the `get` and eventually `put` occur when `transactional` checks the `Either` returned by the callable.

documentation/specifications/remove.md

@@ -5,5 +5,6 @@ This is pretty straightforward:
 ```php
 $orm
     ->repository(User::class)
-    ->remove(SearchByName::of(Name::of('alice')));
+    ->remove(SearchByName::of(Name::of('alice')))
+    ->unwrap();
 ```

documentation/upgrade/v4-to-v5.md

@@ -0,0 +1,81 @@
+# V4 to V5
+
+## `Repository->put()`
+
+=== "Before"
+    ```php
+    $repository->put($aggregate);
+    ```
+
+=== "After"
+    ```php
+    $repository->put($aggregate)->unwrap();
+    ```
+
+## `Repository->remove()`
+
+=== "Before"
+    ```php
+    $repository->remove($idOrSpecification);
+    ```
+
+=== "After"
+    ```php
+    $repository->remove($idOrSpecification)->unwrap();
+    ```
+
+## `Repository->effect()`
+
+=== "Before"
+    ```php
+    $repository->effect($effect);
+    ```
+
+=== "After"
+    ```php
+    $repository->effect($effect)->unwrap();
+    ```
+
+## Transactions
+
+=== "Before"
+    ```php
+    use Innmind\Immutable\Either;
+
+    $manager
+        ->transactional(static function() {
+            if (/* some condition */) {
+                return Either::right(new SomeValue);
+            }
+
+            return Either::left(new SomeError);
+        })
+        ->match(
+            static fn(SomeValue $value) => domSomething($value),
+            static fn(SomeError $value) => domSomething($value),
+        );
+    ```
+
+=== "After"
+    ```php hl_lines="14-15"
+    use Formal\ORM\Adapter\Transaction\Failure
+    use Innmind\Immutable\Either;
+
+    $manager
+        ->transactional(static function() {
+            if (/* some condition */) {
+                return Either::right(new SomeValue);
+            }
+
+            return Either::left(new SomeError);
+        })
+        ->match(
+            static fn(SomeValue $value) => domSomething($value),
+            static fn(SomeError|Failure $value) => match (true) {
+                $value instanceof Failure => throw $value->unwrap(),
+                default => domSomething($value),
+            },
+        );
+    ```
+
+    Errors happening during the transaction commit/rollback are now returned on the left side instead of thrown to let you decide if you prefer using exceptions or a monadic style.