improve directory listing

Crawler.php

@@ -13,6 +13,9 @@ class Crawler
     /** @var bool */
     protected $sortreverse = false;
 
+    /** @var bool */
+    protected $foldersFirst = false;
+
     /** @var string[] patterns to ignore */
     protected $ignore = [];
 
@@ -41,6 +44,11 @@ class Crawler
         $this->sortreverse = $sortreverse;
     }
 
+    public function setFoldersFirst($foldersFirst)
+    {
+        $this->foldersFirst = (bool)$foldersFirst;
+    }
+
     /**
      * Does a (recursive) crawl for finding files based on a given pattern.
      * Based on a safe glob reimplementation using fnmatch and opendir.
@@ -204,13 +212,41 @@ class Crawler
         $callback = [$this, 'compare' . ucfirst($this->sortby)];
         if (!is_callable($callback)) return $items;
 
-        usort($items, $callback);
-        if ($this->sortreverse) {
-            $items = array_reverse($items);
+        // Optional grouping: keep directories before files.
+        // Implement reverse ordering by inverting comparisons instead of array_reverse(),
+        // so the directory-first grouping stays intact.
+        if ($this->foldersFirst) {
+            usort($items, function ($a, $b) use ($callback) {
+                $aIsDir = $this->isDirectoryItem($a);
+                $bIsDir = $this->isDirectoryItem($b);
+                if ($aIsDir !== $bIsDir) {
+                    return $aIsDir ? -1 : 1;
+                }
+
+                $cmp = call_user_func($callback, $a, $b);
+                if ($this->sortreverse) $cmp = -$cmp;
+                return $cmp;
+            });
+        } else {
+            usort($items, $callback);
+            if ($this->sortreverse) {
+                $items = array_reverse($items);
+            }
         }
         return $items;
     }
 
+    /**
+     * Detect whether an item represents a directory.
+     * Supports both crawl() results (children tree) and listDirectory() results (isdir).
+     */
+    protected function isDirectoryItem($item)
+    {
+        if (!is_array($item)) return false;
+        if (!empty($item['isdir'])) return true;
+        return array_key_exists('children', $item) && $item['children'] !== false;
+    }
+
     /**
      * Check if a file is allowed by the configured extensions
      *