ImcStream
, (*1)
This read-only wrapper is an abstract layer between stream open function and
any other wrapper. It controls data limit and timeout, gives rewind/seek
support to unseekable stream, replaces error reporting with exception handlers,
and more!, (*2)
Depict
Previously:, (*3)
+----------------------+ +----------------+
| Stream open function | -----> | Any wrapper |
| e.g fopen() | <----- | e.g http://... |
+----------------------+ +----------------+
Now:, (*4)
+----------------------+ +-------------+ +----------------+
| Stream open function | -----> | imc wrapper | -----> | Any wrapper |
| e.g fopen() | <----- | imc://... | <----- | e.g http://... |
+----------------------+ +-------------+ +----------------+
Installation
Simply add a dependency on coldume/imc-stream to your project's composer.json
file:, (*5)
{
"require": {
"coldume/imc-stream": "~1.0"
}
}
Usage:
Exception Handling
Any supported filesystem function will thorw exception when an error occurs,
such as file not found, read error, etc., (*6)
use ImcStream\ImcStream;
use ImcStream\Exception\TranslatedException;
ImcStream::register();
$arr = ['uri' => __FILE__];
$path = 'imc://'.serialize($arr);
try {
$fp = fopen($path, 'rb');
fread($fp, 10);
fclose($fp);
} catch (TranslatedException $e) {
echo $e->getMessage();
}
In addition to the default English exception message, ImcStream can be switched
to other languages. You can help with existing translations or to add another
language., (*7)
ImcStream::register(['locale' => 'zh_TW']);
Seek and Rewind
use ImcStream\ImcStream;
use ImcStream\Exception\TranslatedException;
ImcStream::register();
$arr = [
'uri' => 'http://www.example.com',
'seek' => true,
];
$path = 'imc://'.serialize($arr);
try{
$fp = fopen($path, 'rb');
fseek($fp, 300);
fread($fp, 800);
rewind($fp);
fseek($fp, 500);
fread($fp, 1024);
} catch (TranslatedException $e) {
echo $e->getMessage();
}
Data Limit and Timeout
These two directives only work on non-local stream., (*8)
The stream read function will throw exception if data read exceeds allowalbe
size limit or timeout expired., (*9)
use ImcStream\ImcStream;
use ImcStream\Exception\TranslatedException;
ImcStream::register();
$arr = [
'uri' => 'http://www.example.com',
'data_limit' => 500, // Unit in KB.
'timeout' => 5, // Unit in second.
];
$path = 'imc://'.serialize($arr);
try {
$fp = fopen($path, 'rb');
while (!feof($fp)) {
fread($fp, 1024);
}
fclose($fp);
} catch (TranslatedException $e) {
echo $e->getMessage();
}
Global URI
This directive only works on non-local stream., (*10)
Sometimes, you have to open an URI multiple times:, (*11)
$fp = fopen('http://www.example.com', 'rb');
fread($fp, 1024);
fclose($fp);
file_get_contents('http://www.example.com');
file_get_contents('http://www.example.com');
The above operations is inefficient, as it will download the same network
resource three times. This problem can be solved by enabling global and seek
directive:, (*12)
use ImcStream\ImcStream;
use ImcStream\Exception\TranslatedException;
ImcStream::register();
$arr = [
'uri' => 'http://www.example.com',
'seek' => true,
'global' => true,
];
$path = 'imc://'.serialize($arr);
try {
fopen($path, 'rb');
fread($fp, 1024);
fclose($path);
file_get_contents($path);
file_get_contents($path);
ImcStream::fclose($path);
} catch (TranslatedException $e) {
echo $e->getMessage();
}
Once global directive is activated, fclose() will merely rewind internal
file pointer, let the latter function read from beginning of the file. You have
to call ImcStream::fclose() to close the internal file pointer., (*13)
Resources
-
PHP supported protocols and wrappers., (*14)
http://php.net/manual/en/wrappers.php, (*15)
-
The streamWrapper class., (*16)
http://php.net/manual/en/class.streamwrapper.php, (*17)
Wallogit.com
