Merge pull request #16 from Innmind/documentation

Update documentation for the new APIs

Author: Baptouuuu

CHANGELOG.md

@@ -29,7 +29,6 @@
 - Requires `innmind/time-warp:~4.0`
 - Requires `innmind/io:~3.2`
 - Requires `innmind/immutable:~5.15`
-- `Innmind\OperatingSystem\Config::withHttpHeartbeat()` period is now expressed with a `Innmind\TimeContinuum\Period`
 - `Innmind\OperatingSystem\CurrentProcess::id()` now returns an `Innmind\Immutable\Attempt`
 - `Innmind\OperatingSystem\CurrentProcess::halt()` now returns `Innmind\Immutable\Attempt<Innmind\Immutable\SideEffect>`
 - `Innmind\OperatingSystem\Filesystem::mount()` now returns an `Innmind\Immutable\Attempt`

README.md

@@ -38,7 +38,10 @@ $os = Factory::build();
 ```php
 use Innmind\Url\Path;
 
-$adapter = $os->filesystem()->mount(Path::of('/var/data/'));
+$adapter = $os
+    ->filesystem()
+    ->mount(Path::of('/var/data/'))
+    ->unwrap();
 ```
 
 `$adater` is an instance of [`Innmind\Filesystem\Adapter`](http://innmind.github.io/Filesystem/).
@@ -55,7 +58,8 @@ use Innmind\Server\Control\Server\Command;
 $process = $os
     ->control()
     ->processes()
-    ->execute(Command::foreground('echo foo'));
+    ->execute(Command::foreground('echo foo'))
+    ->unwrap();
 ```
 
 `$process` is an instance of [`Innmind\Server\Control\Server\Process`](https://github.com/innmind/servercontrol#usage).
@@ -74,39 +78,36 @@ $server = $os
         IPv4::localhost(),
         Port::of(1337),
     )
-    ->match(
-        static fn($server) => $server->unwrap(),
-        static fn() => throw new \RuntimeException('Cannot open the socket'),
-    );
+    ->unwrap();
 ```
 
-`$server` is an instance of [`Innmind\Socket\Server`](https://github.com/innmind/socket#internet-socket).
+`$server` is an instance of [`Innmind\IO\Sockets\Servers\Server`](https://innmind.org/io/sockets/).
 
 ### Want to open a local socket ?
 
 ```php
 # process A
 use Innmind\Socket\Address\Unix;
 
-$server = $os->sockets()->open(Unix::of('/tmp/foo.sock'))->match(
-    static fn($server) => $server->unwrap(),
-    static fn() => throw new \RuntimeException('Cannot open the socket'),
-);
+$server = $os
+    ->sockets()
+    ->open(Unix::of('/tmp/foo.sock'))
+    ->unwrap();
 ```
 
-`$server` is an instance of [`Innmind\Socket\Server`](https://github.com/innmind/socket#unix-socket).
+`$server` is an instance of [`Innmind\IO\Sockets\Servers\Server`](https://innmind.org/io/sockets/).
 
 ```php
 # process B
 use Innmind\Socket\Address\Unix;
 
-$client = $os->sockets()->connectTo(Unix::of('/tmp/foo.sock'))->match(
-    static fn($client) => $client->unwrap(),
-    static fn() => throw new \RuntimeException('Cannot connect to the socket'),
-);
+$client = $os
+    ->sockets()
+    ->connectTo(Unix::of('/tmp/foo.sock'))
+    ->unwrap();
 ```
 
-`$client` is an instance of `Innmind\Socket\Client`.
+`$client` is an instance of [`Innmind\IO\Sockets\Clients\Client`](https://innmind.org/io/sockets/#clients).
 
 ### Want to execute commands on a remote server ?
 
@@ -118,7 +119,8 @@ $process = $os
     ->remote()
     ->ssh(Url::of('ssh://user@server-address:1337'))
     ->processes()
-    ->execute(Command::foreground('ls'));
+    ->execute(Command::foreground('ls'))
+    ->unwrap();
 ```
 
 `$process` is an instance of [`Innmind\Server\Control\Server\Process`](https://github.com/innmind/servercontrol#usage).
@@ -127,15 +129,15 @@ $process = $os
 
 ```php
 use Innmind\Http\{
-    Message\Request\Request,
-    Message\Method,
+    Request,
+    Method,
     ProtocolVersion,
 };
 use Innmind\Url\Url;
 
 $response = $os
     ->remote()
-    ->http()(new Request(
+    ->http()(Request::of(
         Url::of('http://example.com'),
         Method::get,
         ProtocolVersion::v20,
@@ -145,15 +147,15 @@ $response = $os
 ### Want to access current process id ?
 
 ```php
-$os->process()->id();
+$os->process()->id()->unwrap();
 ```
 
 ### Want to pause the current process ?
 
 ```php
-use Innmind\TimeContinuum\Earth\Period\Minute;
+use Innmind\TimeContinuum\Period;
 
-$os->process()->halt(new Minute(1));
+$os->process()->halt(Period::minute(1));
 ```
 
 ### Want to listen for a signal ?

documentation/advanced/logging.md

@@ -2,16 +2,12 @@
 
 If you want to trace everything that is done on your operating system you can use the logger decorator that will automatically write to your log file (almost) all operations.
 
-!!! note ""
-    Data and actions done on a socket are not logged as well as processes output to prevent logging too much data (at least for now).
-
 ```php
-use Innmind\OperatingSystem\OperatingSystem\Logger;
+use Innmind\OperatingSystem\Config\Logger;
 use Psr\Log\LoggerInterface;
 
-$os = Logger::psr(
-    $os,
-    /* any instance of LoggerInterface */
+$os = $os->map(
+    Logger::psr(/* any instance of LoggerInterface */),
 );
 ```
 

documentation/upgrade/v5-to-v6.md

@@ -0,0 +1,165 @@
+# V5 to V6
+
+### Resilient decorator
+
+=== "Before"
+    ```php
+    use Innmind\OperatingSystem\OperatingSystem\Resilient;
+
+    $os = Resilient::of($os);
+    ```
+=== "After"
+    ```php
+    use Innmind\OperatingSystem\Config\Resilient;
+
+    $os = $os->map(Resilient::new());
+    ```
+
+### Logger decorator
+
+=== "Before"
+    ```php
+    use Innmind\OperatingSystem\OperatingSystem\Logger;
+    use Psr\Log\LoggerInterface
+
+    $os = Logger::psr($os, /* instance of LoggerInterface */);
+    ```
+=== "After"
+    ```php
+    use Innmind\OperatingSystem\Config\Logger;
+
+    $os = $os->map(Logger::psr(/* instance of LoggerInterface */));
+    ```
+
+### HTTP client config
+
+=== "Before"
+    ```php
+    use Innmind\OperatingSystem\{
+        Factory,
+        Config,
+    };
+    use Innmind\TimeContinuum\Earth\ElapsedPeriod;
+
+    $os = Factory::build(
+        Config::of()
+            ->disableSSLVerification()
+            ->limitHttpConcurrencyTo(10)
+            ->withHttpHeartbeat(
+                ElapsedPeriod::of(1_000),
+                static fn() => 'heartbeat',
+            ),
+    );
+    ```
+
+=== "After"
+    ```php
+    use Innmind\OperatingSystem\{
+        Factory,
+        Config,
+    };
+    use Innmind\HttpTransport\Curl;
+    use Innmind\TimeContinuum\Period;
+
+    $config = Config::new();
+    $os = Factory::build(
+        $config->useHttpTransport(
+            Curl::of($config->clock(), $config->io())
+                ->disableSSLVerification()
+                ->maxConcurrency(10)
+                ->heartbeat(
+                    Period::second(1),
+                    static fn() => 'heartbeat',
+                ),
+        ),
+    );
+    ```
+
+### Filesystem config
+
+=== "Before"
+    ```php
+    use Innmind\OperatingSystem\{
+        Factory,
+        Config,
+    };
+    use Innmind\Filesystem\CaseSensitivity;
+
+    $os = Factory::build(
+        Config::of()->caseInsensitiveFilesystem(
+            CaseSensitivity::insensitive,
+        ),
+    );
+    ```
+
+=== "After"
+    ```php
+    use Innmind\OperatingSystem\{
+        Factory,
+        Config,
+    };
+    use Innmind\Filesystem\{
+        Adapter\Filesystem,
+        CaseSensitivity,
+    };
+
+    $os = Factory::build(
+        Config::new()->mountFilesystemVia(
+            static fn(Path $path, Config $config) => Filesystem::mount(
+                $path,
+                $config->io(),
+            )->withCaseSentitivity(
+                CaseSensitivity::insensitive,
+            ),
+        ),
+    );
+    ```
+
+### Current process id
+
+=== "Before"
+    ```php
+    $os->process()->id();
+    ```
+
+=== "After"
+    ```php
+    $os->process()->id()->unwrap();
+    ```
+
+### Halt current process
+
+=== "Before"
+    ```php
+    use Innmind\TimeContinuum\Earth\Period\Second;
+
+    $os->process()->halt(new Second(1));
+    ```
+
+=== "After"
+    ```php
+    use Innmind\TimeContinuum\Period;
+
+    $os->process()->halt(Period::second(1))->unwrap();
+    ```
+
+### Mount filesystem
+
+=== "Before"
+    ```php
+    use Innmind\Url\Path;
+
+    $adapter = $os
+        ->filesystem()
+        ->mount(Path::of('somewhere/'));
+    ```
+
+=== "After"
+    ```php
+    use Innmind\Url\Path;
+
+    $adapter = $os
+        ->filesystem()
+        ->mount(Path::of('somewhere/'))
+        ->unwrap();
+    ```

documentation/use_cases/filesystem.md

@@ -17,8 +17,14 @@ $backup = function(Adapter $source, Adapter $target): void {
     });
 };
 $backup(
-    $os->filesystem()->mount(Path::of('/path/to/source/')),
-    $os->filesystem()->mount(Path::of('/path/to/target/')),
+    $os
+        ->filesystem()
+        ->mount(Path::of('/path/to/source/'))
+        ->unwrap(),
+    $os
+        ->filesystem()
+        ->mount(Path::of('/path/to/target/'))
+        ->unwrap(),
 );
 ```
 
@@ -53,7 +59,10 @@ $addUserPicture = function(
         );
 };
 $addUserPicture(
-    $os->filesystem()->mount(Path::of('/path/to/users/data/')),
+    $os
+        ->filesystem()
+        ->mount(Path::of('/path/to/users/data/'))
+        ->unwrap(),
     'some-unique-id',
     File::named(
         'picture.png',
@@ -94,10 +103,18 @@ use Innmind\Url\Path;
 $path = Path::of('/path/to/some/required/folder/');
 
 if (!$os->filesystem()->contains($path)) {
-    $os->control()->processes()->execute($mkdirCommand);
+    $os
+        ->control()
+        ->processes()
+        ->execute($mkdirCommand)
+        ->unwrap();
 }
 
-$os->control()->processes()->execute($subProcessCommand);
+$os
+    ->control()
+    ->processes()
+    ->execute($subProcessCommand)
+    ->unwrap();
 ```
 
 See [processes](processes.md) section on how to execute commands on your operating system.
@@ -109,7 +126,10 @@ Sometimes you want to use the `tmp` folder to write down files such as cache tha
 ```php
 use Innmind\Filesystem\Adapter;
 
-$tmp = $os->filesystem()->mount($os->status()->tmp());
+$tmp = $os
+    ->filesystem()
+    ->mount($os->status()->tmp())
+    ->unwrap();
 $tmp instanceof Adapter; // true
 ```
 
@@ -131,10 +151,17 @@ $count = $runTests(
             return $continuation->stop($count);
         }
 
-        $os->control()->processes()->execute($phpunitCommand);
+        $os
+            ->control()
+            ->processes()
+            ->execute($phpunitCommand)
+            ->unwrap();
 
         return $continuation->continue(++$count);
     },
+)->match(
+    static fn(int $count) => $count, // always 42 as it's the stopping value
+    static fn(\Throwable $e) => throw $e,
 );
 ```