Added more filesystems related examples (#1273)

Author: norberttech

examples/topics/cloud_storage/priority.txt

@@ -0,0 +1 @@
+2

examples/topics/cloud_storage/.gitignore renamed to examples/topics/filesystem/.gitignore

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+use function Flow\Filesystem\DSL\{fstab, path, protocol};
+
+require __DIR__ . '/../../../autoload.php';
+
+$filesystem = fstab()->for(protocol('file'));
+$outputStream = $filesystem->writeTo(path(__DIR__ . '/output.txt'));
+
+$outputStream->append("Files List\n\n");
+
+foreach ($filesystem->list(path(__DIR__ . '/*')) as $file) {
+    $outputStream->append(($file->isFile() ? 'File' : 'Directory') . ': ' . $file->path->basename() . "\n");
+}
+
+$outputStream->close();

examples/topics/cloud_storage/azure/.env.dist renamed to examples/topics/filesystem/azure/.env.dist

@@ -0,0 +1,46 @@
+Flow is based on a dedicated file system library that provides a clear 
+separation between reading/writing streams.  
+
+Filesystem component is available as a standalone package; 
+
+```
+composer require flow-php/filesystem
+```
+
+It was inspired by a linux FStab, and similarly to it to start
+using a filesystem it needs to be first mounted. 
+By default `fstab()` function registers two default filesystems: 
+
+- local native filesystem 
+- stdout write-only filesystem
+
+All filesystems supports listing files and opening streams
+into which you can read or write data.
+
+## Listing Files
+---
+
+To list files use `Filesystem::list(Path $path)` method
+which also supports `glob` pattern.
+
+List method returns and generator of `FileStatus` objects.
+
+Alternatively to check if a single file exists, use `Filesystem::status(Path $path) : ?FileStatus`
+
+## Reading Data
+---
+
+Reading data from a filesystem is done by opening a stream
+and deciding if you want to read it at once or in chunks.
+
+Additionally, you can read a part of a file from a specific offset.
+
+## Writing Data
+---
+
+Writing data to a filesystem is done by opening a stream throught
+one of two methods: 
+
+- `appendTo(Path $path) : DestinationStream`
+- `writeTo(Path $path) : DestinationStream`
+

examples/topics/cloud_storage/azure/code.php renamed to examples/topics/filesystem/azure/code.php

@@ -0,0 +1,6 @@
+Files List
+
+File: code.php
+File: description.md
+File: output.txt
+File: priority.txt

examples/topics/filesystem/azure/priority.txt

@@ -0,0 +1 @@
+1

examples/topics/filesystem/local/code.php

@@ -0,0 +1 @@
+4

examples/topics/filesystem/local/description.md

@@ -0,0 +1,5 @@
+<?php
+
+declare(strict_types=1);
+
+// Coming soon!

examples/topics/filesystem/local/output.txt

@@ -0,0 +1 @@
+S3 or any S3 like filesystem is coming soon!

examples/topics/filesystem/local/priority.txt

@@ -0,0 +1 @@
+3

examples/topics/filesystem/priority.txt

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+use function Flow\Filesystem\DSL\{fstab, path, protocol};
+
+require __DIR__ . '/../../../autoload.php';
+
+$outputStream = fstab()->for(protocol('stdout'))->writeTo(path('stdout://'));
+
+$outputStream->append("Files List\n\n");
+
+foreach (fstab()->for(protocol('file'))->list(path(__DIR__ . '/*')) as $file) {
+    $outputStream->append(($file->isFile() ? 'File' : 'Directory') . ': ' . $file->path->basename() . "\n");
+}
+
+$outputStream->close();

examples/topics/filesystem/s3/code.php

@@ -0,0 +1,7 @@
+Stdout is a special type of filesystem allowing to 
+write straight to stdout of the process.
+
+`Stdout is a write-only filesystem. It is not possible to read from it.`
+
+Its main purpose is to allow to allow web servers to stream 
+data to the client without buffering it in memory.

examples/topics/filesystem/s3/description.md

@@ -0,0 +1 @@
+5

examples/topics/filesystem/s3/priority.txt

@@ -1 +1 @@
-4
+7

examples/topics/filesystem/stdout/code.php

@@ -112,14 +112,4 @@ public function path() : Path
     {
         return $this->path;
     }
-
-    public function write(string $data) : void
-    {
-        if (!$this->isOpen()) {
-            throw new RuntimeException('Cannot write to closed stream');
-        }
-
-        \fseek($this->handle, 0);
-        \fwrite($this->handle, $data);
-    }
 }

examples/topics/filesystem/stdout/description.md

@@ -67,8 +67,4 @@ public function size() : int
     {
         return 0;
     }
-
-    public function write(string $data) : void
-    {
-    }
 }