If you've been writing PHP for a long time, you may have needed to work with local or remote files at some point. The following PHP code is a common way to read a file into a variable that you can do something with:
$contents = '';
$handle = fopen("/local/path/to/file/image.jpg", "rb");
while (!feof($handle)) {
$contents .= fread($handle, 8192);
}
fclose($handle);
This is pretty straightforward. We get a handle to a local file using fopen() and read 8 KB chunks of the file using fread() until feof() indicates that we've reached the end of the file. At that point, we use fclose() to close the handle. The contents of the file are now in the $contents variable.
In addition to local files, we can also access remote ones through fopen() in the exact same way but by specifying the actual remote path instead of the local one we saw before (starting with http(s)://).
Data that we can access this way is streamable, meaning we can open it, close it, or seek to a specific place in it.
Stream wrappers are an abstraction layer on top of these streams that tell PHP how to handle specific types of data. When using a stream wrapper, we refer to the file just like a traditional URL—scheme://target. As a matter of fact, the previous example uses one of PHP's built-in stream wrappers: the file:// wrapper for accessing files on local storage. It is actually the default scheme when none is specified, so that is why we got away with omitting it and just adding the file path. Had the file been on a remote location, we would have used something like http://example.com/file/path/image.jpg. That is another PHP built-in stream wrapper: http:// (for the HTTP protocol).
If that's not enough, PHP also allows us to define our own wrappers for schemes that PHP does not handle out of the box; the Drupal File API was built to take advantage of this. This is where we link back to the different types of file storage we talked about earlier, as they all have their own stream wrappers defined by Drupal.
The public filesystem uses the rather known public:// stream wrapper, the private one uses private://, the temporary one temporary:// and the translation one translations://. These map to the local file paths that we defined in the settings.php (or UI). Later in the chapter we will see how we can define our own stream wrapper and what some of the things that go into it are. First, though, let's talk a bit about the different ways we can manage files in Drupal 8.