English
English
In PHP, stream_get_meta_data is a very useful function that retrieves metadata about a stream resource. This metadata includes important details such as the stream’s status, type, and whether it is open. Understanding how to properly use this function is crucial for developers, especially when handling file streams or other types of streams (such as network streams).
File stream metadata refers to additional information about the stream itself. Typically, stream metadata includes the stream’s status, file type, encoding method, whether it is open, and the mode it was opened with. The stream_get_meta_data function is specifically designed to retrieve this information. It does not return the file’s content directly but instead provides basic status information about the stream.
The basic syntax of the stream_get_meta_data function is as follows:
<span><span><span class="hljs-title function_ invoke__">stream_get_meta_data</span></span><span>(resource </span><span><span class="hljs-variable">$stream</span></span><span>): </span><span><span class="hljs-keyword">array</span></span><span>
</span></span>The $stream parameter is a valid stream resource (for example, one created using fopen(), stream_socket_client(), and similar functions).
The function returns an array that contains the stream’s metadata. Common metadata keys include:
timed_out: Boolean, indicates whether the stream has timed out.
blocked: Boolean, indicates whether the stream is in blocking mode.
eof: Boolean, indicates whether the stream has reached the end of the file.
stream_type: String, indicates the type of stream (e.g., tcp, udp, file).
wrapper_type: String, indicates the type of wrapper used for the stream.
wrapper_data: String, contains additional wrapper information (such as HTTP response headers).
mode: String, indicates the mode in which the file was opened (e.g., r, w, a).
Let’s look at an example of how to use stream_get_meta_data to retrieve file stream metadata.
<span><span><span class="hljs-meta"><?php</span></span><span>
</span><span><span class="hljs-comment">// Open a file stream</span></span><span>
</span><span><span class="hljs-variable">$stream</span></span><span> = </span><span><span class="hljs-title function_ invoke__">fopen</span></span><span>(</span><span><span class="hljs-string">"example.txt"</span></span><span>, </span><span><span class="hljs-string">"r"</span></span><span>);
<p></span>// Retrieve metadata of the file stream<br>
$metadata = stream_get_meta_data($stream);</p>
<p>// Output metadata<br>
print_r($metadata);</p>
<p>// Close the file stream<br>
fclose($stream);<br>
?><br>
</span>In the example above, we first open a file example.txt using fopen(), then use stream_get_meta_data() to retrieve the file stream’s metadata. The returned $metadata array may look like this:
<span><span><span class="hljs-title function_ invoke__">Array</span></span><span>
(
[timed_out] =>
[blocked] =>
[eof] =>
[stream_type] => file
[wrapper_type] =>
[wrapper_data] =>
[mode] => r
[seekable] => </span><span><span class="hljs-number">1</span></span><span>
[uri] => example.txt
)
</span></span>timed_out: For network streams, timed_out indicates whether the stream was interrupted due to a timeout. For file streams, this field is usually empty.
blocked: Indicates whether the stream is in blocking mode, mainly relevant for network streams. File streams are generally unaffected.
eof: Returns true when the end of the file is reached, otherwise returns false.
stream_type: Indicates the type of stream. For example, for regular file streams, it returns file; for network connections, it may return tcp or udp.
mode: Indicates the mode in which the stream was opened, such as r for read-only, w for write-only, and a for append.
In addition to file streams, stream_get_meta_data can also be used to retrieve metadata for network streams. Here’s an example with an HTTP request stream:
<span><span><span class="hljs-meta"><?php</span></span><span>
</span><span><span class="hljs-comment">// Create a TCP connection</span></span><span>
</span><span><span class="hljs-variable">$stream</span></span><span> = </span><span><span class="hljs-title function_ invoke__">stream_socket_client</span></span><span>(</span><span><span class="hljs-string">"tcp://www.example.com:80"</span></span><span>, </span><span><span class="hljs-variable">$errno</span></span><span>, </span><span><span class="hljs-variable">$errstr</span></span><span>, </span><span><span class="hljs-number">30</span></span><span>);
<p></span>// Retrieve metadata of the connection stream<br>
$metadata = stream_get_meta_data($stream);</p>
<p>// Output metadata<br>
print_r($metadata);</p>
<p>// Close the stream<br>
fclose($stream);<br>
?><br>
</span>In this example, stream_socket_client is used to create a TCP connection and then retrieve metadata about it. The returned metadata may include additional details about the network stream, such as whether it is blocking or has timed out.
File Streams vs Network Streams: The metadata returned by stream_get_meta_data differs between file and network streams. For network streams, the metadata focuses more on network-related status, while for file streams, it highlights file modes and EOF markers.
Retrieving File Information: When working with files, the eof (end of file) field is particularly useful. It helps prevent reading beyond the end of the file.
Performance: While stream_get_meta_data provides very useful information, calling it too frequently can introduce performance overhead, especially with large files or frequent network requests. In most cases, it’s best to use it only when needed.
stream_get_meta_data is an extremely practical function when dealing with streams, as it allows you to quickly obtain metadata and understand the stream’s status. By using this function appropriately, developers can debug stream operations more effectively and ensure stability and correctness when reading from or writing to streams. Whether you are working with file streams, network streams, or other types of streams, knowing how to properly retrieve and interpret metadata is essential for writing efficient PHP programs.
