function backdrop_get_filename

Returns and optionally sets the filename for a system resource.

The filename, whether provided, cached, or retrieved from the database, is only returned if the file exists.

This function plays a key role in allowing Backdrop's resources (modules, layouts, and themes) to be located in different places depending on a site's configuration. For example, a module 'foo' may legally be located in any of these three places:

core/modules/foo/foo.module modules/foo/foo.module sites/example.com/modules/foo/foo.module

Calling backdrop_get_filename('module', 'foo') will give you one of the above, depending on where the module is located.

Parameters

string $type: The type of the item (theme, layout, theme_engine, module, profile).

string $name: The name of the item for which the filename is requested.

string|null $filename: The filename of the item if it is to be set explicitly rather than by consulting the database.

Return value

string|null|false: The filename of the requested item or NULL if the item is not found.

File

core/includes/bootstrap.inc, line 1080

Functions that need to be loaded on every Backdrop request.

Code

function backdrop_get_filename($type, $name, $filename = NULL) {
  // The location of files will not change during the request, so do not use
  // backdrop_static().
  static $files = array(), $dirs = array();

  // Profiles are a special case: they have a fixed location and naming.
  if ($type == 'profile') {
    $profile_filenames = array(
      "profiles/$name/$name.profile",
      "core/profiles/$name/$name.profile",
    );
    foreach ($profile_filenames as $profile_filename) {
      if (file_exists($profile_filename)) {
        $files[$type][$name] = $profile_filename;
        break;
      }
      else {
        $files[$type][$name] = FALSE;
      }
    }
  }
  if (!isset($files[$type])) {
    $files[$type] = array();
  }

  if (!empty($filename) && file_exists($filename)) {
    $files[$type][$name] = $filename;
  }
  elseif (isset($files[$type][$name])) {
    // The file is in the database but does not exist on the disk.
  }
  // Verify that we have an active database connection, before querying
  // the database. This is required because this function is called both
  // before we have a database connection (i.e. during installation) and
  // when a database connection fails.
  else {
    try {
      // Layouts we use the existing registry rather than the system table.
      if ($type === 'layout' && function_exists('layout_get_layout_template_info')) {
        $layout_info = layout_get_layout_template_info($name);
        if ($layout_info) {
          $files[$type][$name] = $layout_info['path'] . '/' . $layout_info['name'] . '.info';
        }
      }
      // Modules, themes, and profiles pull from the system table.
      elseif (function_exists('db_query')) {
        $file = db_query("SELECT filename FROM {system} WHERE name = :name AND type = :type", array(
          ':name' => $name,
          ':type' => $type,
        ))->fetchField();
        if ($file && file_exists(BACKDROP_ROOT . '/' . $file)) {
          $files[$type][$name] = $file;
        }
      }
    }
    catch (Exception $e) {
      // The database table may not exist because Backdrop is not yet installed,
      // or the database might be down. We have a fallback for this case so we
      // hide the error completely.
    }

    // Fallback to searching the filesystem if the database could not find the
    // file or the file returned by the database is not found.
    if (!isset($files[$type][$name])) {
      // We have a consistent directory naming: modules, themes...
      $dir = $type . 's';
      if ($type == 'theme_engine') {
        $dir = 'themes/engines';
        $extension = 'engine';
      }
      elseif ($type === 'theme' || $type === 'layout') {
        $extension = 'info';
      }
      else {
        $extension = $type;
      }

      if (!isset($dirs[$dir][$extension])) {
        $dirs[$dir][$extension] = TRUE;
        if (!function_exists('backdrop_system_listing')) {
          require_once BACKDROP_ROOT . '/core/includes/common.inc';
        }
        // Scan the appropriate directories for all files with the requested
        // extension, not just the file we are currently looking for. This
        // prevents unnecessary scans from being repeated when this function is
        // called more than once in the same page request.
        $matches = backdrop_system_listing("/^" . BACKDROP_PHP_FUNCTION_PATTERN . "\.$extension$/", $dir, 'name', 0);
        foreach ($matches as $matched_name => $file) {
          $files[$type][$matched_name] = $file->uri;
        }
      }
    }
  }

  return isset($files[$type][$name]) ? $files[$type][$name] : NULL;
}