Steam wrappers were introduced in Drupal 7 and allow user file locations to be kept in a maintainable way, although I often forget which function to use to translate them. The three wrappers available are public://, private://, and temporary://, which map to the public, private, and temporary files directories respectively. All user files in Drupal are stored in either of these directories and they are referenced in the database as the file wrapper followed by the location of the file. This means that the location of the files is only dependent on a single config setting.
Translation of the stream wrapper into a file location is dependent on one of two functions, depending on what sort of file location you want. If you want to get a local file location then you would use drupal_realpath(), whereas if you want a URL of the file you would use file_create_url().
For example, the a file called test.png in the public file directory might have be presented as public://test.png, this would be translated in the following ways by the file_create_url() and drupal_realpath() functions.
- $url = file_create_url('public://test.png');
- print $url; // prints 'http://www.example.com/sites/default/files/test.png'
- $location = drupal_realpath('public://test.png');
- print $location; // prints '/path/to/docroot/sites/default/files/test.png'
If the file is kept in the private files directory (and Drupal has been configured to use this) then the output will be slightly different for the file_create_url() function. This is because private files must go through a layer of authentication and so the function doesn't link directly to the file.
- $url = file_create_url('private://test.png');
- print $url; // prints 'http://www.example.com/system/files/test.png'
The temporary:// stream wrapper is used to reference the temporary directory, which is set in the Drupal configuration. This generally shouldn't be available and therefore shouldn't be accessible as a URL.
- $location = drupal_realpath('temporary://test.png');
- print $location; // prints '/tmp/test.png'
The drupal_realpath() function is also a handy way in which to get hold of the user files directory by just passing it the stream wrapper on its own.
- $location = drupal_realpath('public://');
- print $location; // prints '/path/to/docroot/sites/default/files/'
You will find these stream wrappers being used all over Drupal where files are used. The following code is used to extract an image from an image field on a Drupal node and then inspect the data held within.
- $image = array_pop(field_get_items('node', $node, 'field_image'));
- print '<pre>' . print_r($image, true) . '</pre>';
This prints the following output. Notice that the file is called image.jpg and that it is held at 'public://image.jpg'.
- [fid] => 9
- [alt] =>
- [title] =>
- [width] => 380
- [height] => 253
- [uid] => 1
- [filename] => image.jpg
- [uri] => public://image.jpg
- [filemime] => image/jpeg
- [filesize] => 42649
- [status] => 1
- [timestamp] => 1372157519
To get the full URL of the image you would translate the uri element of the image array like this.
- print file_create_url($image['uri']);
- // prints 'http://www.example.com/sites/default/files/image.jpg'