C H A P T E R 1 4

■ ■ ■

Working with Files

Drupal has the ability to upload and download files in a variety of ways. In this chapter, you’ll learn about public and private files and how they’re served, deal briefly with the handling of media files, and look at Drupal’s file authentication hook.

How Drupal Serves Files

Drupal follows the same mechanism for accessing files that the UNIX operating system does, streams. Streams revolutionized how UNIX accesses files, treating files as just another resource that can be accessed and interacted with through a common set of functions (system calls). The power of streams is that the concept of a file can be extended to include virtually anything that is accessible electronically yet the function calls to interact with that electronic resource are the same regardless of whether it’s a file residing on a disk or any other electronic resource.

The concept of streams has permeated nearly every operating system and programming language, including PHP, which introduced the concept of a “stream wrapper” notation. What this means is that a file or any other electronic resource is named using a set of standards or “schemes” followed by “://” and then a “target”, which is essentially the path in the file system.

Drupal uses php’s stream wrapper notation for file names. public files use “public://filepath” where filepath is the directory and name of the file. Private files use “private://filepath”, and temporary files use “temporary://filepath”. As a developer you can also write modules that implement other stream wrappers by implementing the DrupalStreamWrapperInterface class. the Drupal File Example module (http://drupal.org/project/examples) demonstrates how you can create a new stream wrapper for accessing information stored in $_SESSION as a demonstration of how you can write your own stream wrappers. You can also find other example stream wrappers that are included with PHP, including FILE://, FTP://, and HTTP://, all of which can be used in your module.

Managed and Unmanaged Drupal APIs

Drupal provides two “layers” of FILE APIs, “managed” and “Unmanaged”. The “Managed” APIs provide an entry into the file_managed table so that files can be accessed beyond the life of the current user action. Modules that use persistent files will need to use the managed file apis.

The Unmanaged functions provide the same functionality as the underlying PHP file APIs, however nothing about the file being operated on is stored in the database.

323

CHAPTER 14 ■ WORKING WITH FILES

■ Caution Because public and private file storage methods result in different URLs being generated for file downloads, it’s important to choose the option that will work best for your site before you start uploading files, and stick to the method you choose.

To set up the file system paths and specify which download method to use, navigate to Configuration -> File system page (see figure 14-1).

Figure 14-1. The interface for specifying file-related settings in Drupal. The directory specified in the public and private file system path must be created and given appropriate permissions.

324