add more methods for read stream data

inhere · inhere · commit 1df7b570a290 · 2021-09-05T11:57:25.000+08:00
diff --git a/src/File.php b/src/File.php
@@ -20,13 +20,17 @@
 use Toolkit\FsUtil\Traits\FileOperateTrait;
 use Toolkit\FsUtil\Traits\FileSnippetReadTrait;
 use function dirname;
+use function fgets;
 use function file_get_contents;
 use function file_put_contents;
+use function fread;
 use function function_exists;
 use function in_array;
 use function is_array;
 use function is_string;
+use function stream_get_contents;
 use function strlen;
+use function trim;
 
 /**
  * Class File
@@ -58,8 +62,21 @@ class File extends FileSystem
      *
      * @return array
      * @throws FileNotFoundException
+     * @deprecated please use parse()
      */
     public static function load(string $src, string $format = self::FORMAT_PHP): array
+    {
+        return self::parse($src, $format);
+    }
+
+    /**
+     * @param string $src 要解析的 文件 或 字符串内容。
+     * @param string $format
+     *
+     * @return array
+     * @throws FileNotFoundException
+     */
+    public static function parse(string $src, string $format = self::FORMAT_PHP): array
     {
         $src = trim($src);
         switch ($format) {
@@ -113,39 +130,82 @@ public static function loadPhp(string $file, bool $throwError = true): array
     }
 
     /**
-     * @param string $file
+     * @param string $fileOrContents
      *
      * @return array
      */
-    public static function loadJson(string $file): array
+    public static function parseJson(string $fileOrContents): array
     {
-        return JsonParser::parse($file);
+        return JsonParser::parse($fileOrContents);
     }
 
     /**
-     * @param string $ini 要解析的 ini 文件名 或 字符串内容。
+     * @param string $fileOrContents
      *
      * @return array
+     * @deprecated please use parseJson()
      */
-    public static function loadIni(string $ini): array
+    public static function loadJson(string $fileOrContents): array
     {
-        return IniParser::parse($ini);
+        return JsonParser::parse($fileOrContents);
     }
 
     /**
-     * @param string $yml 要解析的 yml 文件名 或 字符串内容。
+     * @param string $fileOrContents 要解析的 ini 文件名 或 字符串内容。
      *
      * @return array
      */
-    public static function loadYaml(string $yml): array
+    public static function parseIni(string $fileOrContents): array
     {
-        return YamlParser::parse($yml);
+        return IniParser::parse($fileOrContents);
+    }
+
+    /**
+     * @param string $fileOrContents 要解析的 ini 文件名 或 字符串内容。
+     *
+     * @return array
+     * @deprecated please use parseIni()
+     */
+    public static function loadIni(string $fileOrContents): array
+    {
+        return IniParser::parse($fileOrContents);
+    }
+
+    /**
+     * @param string $fileOrContents 要解析的 yml 文件名 或 字符串内容。
+     *
+     * @return array
+     */
+    public static function parseYaml(string $fileOrContents): array
+    {
+        return YamlParser::parse($fileOrContents);
+    }
+
+    /**
+     * @param string $fileOrContents 要解析的 yml 文件名 或 字符串内容。
+     *
+     * @return array
+     * @deprecated please use parseYaml()
+     */
+    public static function loadYaml(string $fileOrContents): array
+    {
+        return YamlParser::parse($fileOrContents);
     }
 
     /**********************************************************************************
      * php function wrapper, add error handle
      *********************************************************************************/
 
+    /**
+     * @param string $filename
+     *
+     * @return string
+     */
+    public static function readAll(string $filename): string
+    {
+        return self::getContents($filename);
+    }
+
     /**
      * @param string   $filename
      * @param bool     $useIncludePath
@@ -206,18 +266,16 @@ public static function save(string $filename, string $data, int $flags = 0, $con
     }
 
     /**
-     * @param $content
-     * @param $path
-     *
-     * @throws IOException
+     * @param string $content
+     * @param string $path
      */
-    public static function write($content, $path): void
+    public static function write(string $content, string $path): void
     {
-        $handler = static::openHandler($path);
+        $stream = static::streamOpen($path);
 
-        static::writeToFile($handler, $content);
+        static::streamWrite($stream, $content);
 
-        @fclose($handler);
+        fclose($stream);
     }
 
     /**
@@ -226,31 +284,64 @@ public static function write($content, $path): void
      * @return resource
      * @throws IOException
      */
-    public static function openHandler(string $path)
+    public static function streamOpen(string $path)
     {
-        if (($handler = @fopen($path, 'wb')) === false) {
-            throw new IOException('The file "' . $path . '" could not be opened for writing. Check if PHP has enough permissions.');
+        if (($stream = @fopen($path, 'wb')) === false) {
+            throw new IOException('The file "' . $path . '" could not be opened for writing. Check has enough permissions.');
         }
 
-        return $handler;
+        return $stream;
     }
 
     /**
      * Attempts to write $content to the file specified by $handler. $path is used for printing exceptions.
      *
-     * @param resource $handler The resource to write to.
+     * @param resource $stream  The resource to write to.
      * @param string   $content The content to write.
      * @param string   $path    The path to the file (for exception printing only).
      *
      * @throws IOException
      */
-    public static function writeToFile($handler, string $content, string $path = ''): void
+    public static function streamWrite($stream, string $content, string $path = ''): void
     {
-        if (($result = @fwrite($handler, $content)) === false || ($result < strlen($content))) {
+        if (($result = @fwrite($stream, $content)) === false || ($result < strlen($content))) {
             throw new IOException('The file "' . $path . '" could not be written to. Check your disk space and file permissions.');
         }
     }
 
+    /**
+     * @param resource $stream
+     * @param int      $length
+     *
+     * @return string
+     */
+    public static function streamRead($stream, int $length = 1024): string
+    {
+        return (string)fread($stream, $length);
+    }
+
+    /**
+     * @param resource $stream
+     *
+     * @return string
+     */
+    public static function streamReadln($stream): string
+    {
+        return trim((string)fgets($stream));
+    }
+
+    /**
+     * @param resource $stream
+     * @param int      $length
+     * @param int      $offset
+     *
+     * @return string
+     */
+    public static function streamReadAll($stream, int $length = -1, int $offset = -1): string
+    {
+        return (string)stream_get_contents($stream, $length, $offset);
+    }
+
     /**
      * ********************** 创建多级目录和多个文件 **********************
      * 结合上两个函数
@@ -291,6 +382,7 @@ public static function createAndWrite(array $fileData = [], bool $append = false
      * @return bool|string
      * @throws FileNotFoundException
      * @throws FileReadException
+     * @noinspection PhpComposerExtensionStubsInspection
      */
     public static function getContentsV2(
         string $file,
@@ -436,7 +528,7 @@ public static function stripPhpCode(string $source): string
      * @param string $file
      * @param string $as
      */
-    public static function downBigFile($file, $as): void
+    public static function downBigFile(string $file, string $as): void
     {
         header('Expires: Mon, 1 Apr 1974 05:00:00 GMT');
         header('Pragma: no-cache');
diff --git a/src/Parser/AbstractParser.php b/src/Parser/AbstractParser.php
@@ -13,6 +13,7 @@
 use function dirname;
 use function file_get_contents;
 use function is_file;
+use function strlen;
 
 /**
  * Class BaseParser
@@ -32,7 +33,7 @@ abstract class AbstractParser
      *
      * @param string   $string      Waiting for the parse data
      * @param bool     $enhancement 启用增强功能，支持通过关键字 继承、导入、参考
-     * @param callable $pathHandler When the second param is true, this param is valid.
+     * @param callable|null $pathHandler When the second param is true, this param is valid.
      * @param string   $fileDir     When the second param is true, this param is valid.
      *
      * @return array
@@ -58,7 +59,7 @@ public static function parse(
         callable $pathHandler = null,
         string $fileDir = ''
     ): array {
-        if (is_file($string)) {
+        if (strlen($string) < 256 && is_file($string)) {
             return self::parseFile($string, $enhancement, $pathHandler, $fileDir);
         }
 
@@ -78,7 +79,7 @@ public static function parseFile(
         string $file,
         bool $enhancement = false,
         callable $pathHandler = null,
-        $fileDir = ''
+        string $fileDir = ''
     ): array {
         if (!is_file($file)) {
             throw new InvalidArgumentException("Target file [$file] not exists");
@@ -91,7 +92,7 @@ public static function parseFile(
     }
 
     /**
-     * @param               $string
+     * @param string      $string
      * @param bool          $enhancement
      * @param callable|null $pathHandler
      * @param string        $fileDir
diff --git a/src/Parser/JsonParser.php b/src/Parser/JsonParser.php
@@ -39,8 +39,7 @@ class JsonParser extends AbstractParser
      * @param string   $fileDir     When the second param is true, this param is valid.
      *
      * @return array
-     * @throws InvalidArgumentException
-     * @throws UnexpectedValueException
+     * @throws InvalidArgumentException|\JsonException
      */
     protected static function doParse(
         string $string,
diff --git a/src/Traits/FileSystemFuncTrait.php b/src/Traits/FileSystemFuncTrait.php
@@ -10,6 +10,7 @@
 namespace Toolkit\FsUtil\Traits;
 
 use FilesystemIterator;
+use InvalidArgumentException;
 use Toolkit\FsUtil\Exception\FileSystemException;
 use Toolkit\FsUtil\Exception\IOException;
 use Toolkit\Stdlib\Arr;
@@ -22,13 +23,18 @@
 use function error_get_last;
 use function explode;
 use function function_exists;
+use function get_resource_type;
 use function implode;
 use function is_dir;
+use function is_resource;
+use function is_writable;
 use function mkdir;
 use function realpath;
 use function rmdir;
 use function str_replace;
+use function stream_get_meta_data;
 use function strlen;
+use function strpos;
 use const DIRECTORY_SEPARATOR;
 
 /**
@@ -38,6 +44,42 @@
  */
 trait FileSystemFuncTrait
 {
+
+    /**
+     * @param resource $stream
+     *
+     * @return bool
+     */
+    public static function isStream($stream): bool
+    {
+        return is_resource($stream) && get_resource_type($stream) === 'stream';
+    }
+
+    /**
+     * @param resource $stream
+     */
+    public static function assertStream($stream): void
+    {
+        if (!self::isStream($stream)) {
+            throw new InvalidArgumentException('Expected a valid stream');
+        }
+    }
+
+    /**
+     * @param resource $stream
+     */
+    public static function assertReadableStream($stream): void
+    {
+        if (!self::isStream($stream)) {
+            throw new InvalidArgumentException('Expected a valid stream');
+        }
+
+        $meta = stream_get_meta_data($stream);
+        if (strpos($meta['mode'], 'r') === false && strpos($meta['mode'], '+') === false) {
+            throw new InvalidArgumentException('Expected a readable stream');
+        }
+    }
+
     /**
      * @param string   $source
      * @param string   $dest
@@ -104,6 +146,20 @@ public static function isReadable(string $filename): bool
         return is_readable($filename);
     }
 
+    /**
+     * @param string $filename
+     *
+     * @return bool
+     */
+    public static function isWriteable(string $filename): bool
+    {
+        if ('\\' === DIRECTORY_SEPARATOR && strlen($filename) > 258) {
+            throw new IOException('Could not check if file is readable because path length exceeds 258 characters.');
+        }
+
+        return is_writable($filename);
+    }
+
     /**
      * Change mode for an array of files or directories.
      *
