More docs and fixes to the timestamp display.

The timestamp formatting would be picking up the current system
timezone, while we want to output file times in UTC.

README.md

@@ -42,6 +42,13 @@ $ php artisan storage:ls -d s3
 ```
 
 ```bash
+# Short format
+$ ./artisan storage:ls -d local -l
+.gitignore
+public
+
+# Long format
+
 $ ./artisan storage:ls -d local -l
 -         14 2019-03-05 14:27:03 .gitignore
 d          0 2019-08-21 11:19:46 public

composer.json

@@ -11,7 +11,8 @@
     ],
     "minimum-stability": "dev",
     "require": {
-        "illuminate/support": "~5.6"
+        "illuminate/support": "~5.6",
+        "php": "^7.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^7.0"

src/Console/Commands/ListStorage.php

@@ -9,13 +9,23 @@
 use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Storage;
 use DateTimeInterface;
+use DateTimeImmutable;
+use DateTimeZone;
 use Throwable;
 
 class ListStorage extends Command
 {
+    /**
+     * flyssytem object types, because flysystem does not have its own
+     * constants for these.
+     */
     const TYPE_DIR = 'dir';
     const TYPE_FILE = 'file';
 
+    /**
+     * Counts up the number of objects (files or directories) fetched.
+     * Used for output formatting.
+     */
     protected $dirIndex = 0;
 
     protected $signature = 'storage:ls
@@ -65,6 +75,16 @@ public function handle()
         $this->listDirectory($selectedDisk, $selectedDir, $recursive, $longFormat);
     }
 
+    /**
+     * List the contents of one directory and recurse if necessary.
+     *
+     * @param string $disk the name of the laravel filessystem disk
+     * @param string $directory the path from the root of the disk, leading "/" optional
+     * @param bool $recursive true to recurse into sub-directories
+     * @param bool $longFormat true to output long format, with sizes and timestamps
+     *
+     * @return void
+     */
     protected function listDirectory(
         string $disk,
         string $directory,
@@ -73,6 +93,10 @@ protected function listDirectory(
     ) {
         $content = Storage::disk($disk)->listContents($directory);
 
+        // If we are recursing into subdirectories, then display the directory
+        // before listing the contents.
+        // Precede with a blank line after the first directory.
+
         if ($recursive) {
             if ($this->dirIndex) {
                 $this->line('');
@@ -83,8 +107,12 @@ protected function listDirectory(
             $this->line($directory . ':');
         }
 
+        // To collect directories as we go through.
+
         $subDirs = [];
 
+        $dt = new DateTimeImmutable();
+
         foreach ($content as $item) {
             $basename = $item['basename'] ?? 'unknown';
             $dirname = $item['dirname'] ?? '/';
@@ -107,14 +135,22 @@ protected function listDirectory(
                 }
             }
 
+            // Format the timestamp if present.
+            // Just going down the seconds for now, and UTC is implied.
+
             $timestamp = $item['timestamp'] ?? null;
 
             if ($timestamp !== null) {
-                $datetime = date('Y-m-d H:i:s', $timestamp);
+                $datetime = $dt
+                    ->setTimezone(new DateTimeZone('UTC'))
+                    ->setTimestamp($timestamp)
+                    ->format('Y-m-d H:i:s');
             } else {
                 $datetime = '';
             }
 
+            // Two output formats at present: long and not long.
+
             if ($longFormat) {
                 $this->line(sprintf(
                     '%1s %10d %s %s',
@@ -133,11 +169,15 @@ protected function listDirectory(
                 }
             }
 
-            if ($type === static::TYPE_DIR) {
+            // Collect the list of sub-directories as we go through.
+
+            if ($recursive && $type === static::TYPE_DIR) {
                 $subDirs[] = $pathname;
             }
         }
 
+        // If recursing, go through the sub-directories collected.
+
         if ($recursive && $subDirs) {
             foreach ($subDirs as $subDir) {
                 $this->listDirectory($disk, $subDir, $recursive, $longFormat);