Implemented FR #53407 (make scandir()'s directory sorting optional).

NEWS

@@ -128,6 +128,10 @@ PHP                                                                        NEWS
   . PDO_mysql: Removed support for linking with MySQL client libraries older
     than 4.1. (Johannes)
 
+- Improved filesystem functions:
+  . scandir() now accepts SCANDIR_SORT_NONE as a possible sorting_order value.
+    FR #53407. (Adam)
+
 - Improved HASH extension:
   . Added Jenkins's one-at-a-time hash support. (Martin Jansen)
   . Added FNV-1 hash support. (Michael Maclean)

UPGRADING

@@ -136,6 +136,10 @@ UPGRADE NOTES - PHP X.Y
 - The third parameter ($matches) to preg_match_all() is now optional. If
   omitted, the function will simply return the number of times the pattern was
   matched in the subject and will have no other side effects.
+- The second argument of scandir() now accepts SCANDIR_SORT_NONE (2) as a
+  possible value. This value results in scandir() performing no sorting: on
+  local filesystems, this allows files to be returned in native filesystem
+  order.
  
 
 ===================================
@@ -298,6 +302,9 @@ UPGRADE NOTES - PHP X.Y
        - ENT_XML1
        - ENT_XHTML
        - ENT_HTML5
+       - SCANDIR_SORT_ASCENDING
+       - SCANDIR_SORT_DESCENDING
+       - SCANDIR_SORT_NONE
 
      g. New classes
 

ext/standard/dir.c

@@ -148,6 +148,10 @@ PHP_MINIT_FUNCTION(dir)
 	pathsep_str[1] = '\0';
 	REGISTER_STRING_CONSTANT("PATH_SEPARATOR", pathsep_str, CONST_CS|CONST_PERSISTENT);
 
+	REGISTER_LONG_CONSTANT("SCANDIR_SORT_ASCENDING",  PHP_SCANDIR_SORT_ASCENDING,  CONST_CS | CONST_PERSISTENT);
+	REGISTER_LONG_CONSTANT("SCANDIR_SORT_DESCENDING", PHP_SCANDIR_SORT_DESCENDING, CONST_CS | CONST_PERSISTENT);
+	REGISTER_LONG_CONSTANT("SCANDIR_SORT_NONE",       PHP_SCANDIR_SORT_NONE,       CONST_CS | CONST_PERSISTENT);
+
 #ifdef HAVE_GLOB
 
 #ifdef GLOB_BRACE
@@ -563,8 +567,10 @@ PHP_FUNCTION(scandir)
 		context = php_stream_context_from_zval(zcontext, 0);
 	}
 
-	if (!flags) {
+	if (flags == PHP_SCANDIR_SORT_ASCENDING) {
 		n = php_stream_scandir(dirn, &namelist, context, (void *) php_stream_dirent_alphasort);
+	} else if (flags == PHP_SCANDIR_SORT_NONE) {
+		n = php_stream_scandir(dirn, &namelist, context, NULL);
 	} else {
 		n = php_stream_scandir(dirn, &namelist, context, (void *) php_stream_dirent_alphasortr);
 	}

ext/standard/php_dir.h

@@ -37,4 +37,8 @@ PHP_FUNCTION(getdir);
 PHP_FUNCTION(glob);
 PHP_FUNCTION(scandir);
 
+#define PHP_SCANDIR_SORT_ASCENDING 0
+#define PHP_SCANDIR_SORT_DESCENDING 1
+#define PHP_SCANDIR_SORT_NONE 2
+
 #endif /* PHP_DIR_H */

ext/standard/tests/dir/scandir_basic.phpt

@@ -25,7 +25,7 @@ echo "\n-- scandir() with mandatory arguments --\n";
 var_dump(scandir($directory));
 
 echo "\n-- scandir() with all arguments --\n";
-$sorting_order = 1;
+$sorting_order = SCANDIR_SORT_DESCENDING;
 $context = stream_context_create();
 var_dump(scandir($directory, $sorting_order, $context));
 

ext/standard/tests/dir/scandir_variation10.phpt

@@ -0,0 +1,79 @@
+--TEST--
+Test scandir() function : usage variations - different sorting constants
+--FILE--
+<?php
+/* Prototype  : array scandir(string $dir [, int $sorting_order [, resource $context]])
+ * Description: List files & directories inside the specified path 
+ * Source code: ext/standard/dir.c
+ */
+
+printf("SCANDIR_SORT_ASCENDING: %d\n", SCANDIR_SORT_ASCENDING);
+printf("SCANDIR_SORT_DESCENDING: %d\n", SCANDIR_SORT_DESCENDING);
+printf("SCANDIR_SORT_NONE: %d\n", SCANDIR_SORT_NONE);
+
+/*
+ * Pass different integers as $sorting_order argument to test how scandir()
+ * re-orders the array
+ */
+
+echo "*** Testing scandir() : usage variations ***\n";
+
+// include for create_files/delete_files functions
+include(dirname(__FILE__) . '/../file/file.inc');
+
+// create directory and files
+$dir = dirname(__FILE__) . '/scandir_variation10';
+mkdir($dir);
+@create_files($dir, 2);
+
+// Deterministic tests.
+var_dump(scandir($dir, SCANDIR_SORT_ASCENDING));
+var_dump(scandir($dir, SCANDIR_SORT_DESCENDING));
+
+// Non-deterministic tests.
+$files = scandir($dir, SCANDIR_SORT_NONE);
+var_dump(count($files));
+var_dump(in_array('.', $files));
+var_dump(in_array('..', $files));
+var_dump(in_array('file1.tmp', $files));
+var_dump(in_array('file2.tmp', $files));
+
+delete_files($dir, 2);
+?>
+===DONE===
+--CLEAN--
+<?php
+$dir = dirname(__FILE__) . '/scandir_variation10';
+rmdir($dir);
+?>
+--EXPECTF--
+SCANDIR_SORT_ASCENDING: 0
+SCANDIR_SORT_DESCENDING: 1
+SCANDIR_SORT_NONE: 2
+*** Testing scandir() : usage variations ***
+array(4) {
+  [0]=>
+  string(1) "."
+  [1]=>
+  string(2) ".."
+  [2]=>
+  string(9) "file1.tmp"
+  [3]=>
+  string(9) "file2.tmp"
+}
+array(4) {
+  [0]=>
+  string(9) "file2.tmp"
+  [1]=>
+  string(9) "file1.tmp"
+  [2]=>
+  string(2) ".."
+  [3]=>
+  string(1) "."
+}
+int(4)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+===DONE===

ext/standard/tests/dir/scandir_variation3.phpt

@@ -16,7 +16,7 @@ echo "*** Testing scandir() : usage variations ***\n";
 // Initialise function arguments not being substituted
 $dir = dirname(__FILE__) . '/scandir_variation3';
 mkdir($dir);
-$sorting_order = 0;
+$sorting_order = SCANDIR_SORT_ASCENDING;
 
 //get an unset variable
 $unset_var = 10;