Keeps public files of a publicly inaccessible entity in the private filesystem until the entity becomes available for the public. Entity files are all files referred by the entity, either via entity reference fields or uploaded and embedded in text blobs.

Terminology

How does it work?

To be able to move a file from public to private filesystem and vice versa, the module should be able to determine which is the source entity for a certain file and determine its visibility for anonymous users. But checking the source entity visibility is not enough; it should follow the path from the source entity to the file destination and check the visibility of each traversable entity on the way. This is achieved by the Drupal\file_visibility\FileVisibility service. The service interrogates all FileVisibility plugins and collects paths from source entities to the file. If at least one path has all entities publicly visible, then we consider that the file is in use and should be publickly accessible under its original public file system. If there's no path that can be traversed by an anonymous user, the file is moved under the private file system.

The main module, file_visibility, offers the FileVisibility plugin type. This plugin type knows how to determine the relation between a file and its source entity, including all paths from source to the file. By default, the module only provides the plugin discovery attributes, the manager and the interface, but no plugin class. But there is the file_visibility_track_usage submodule that ships a plugin which computes such relation by extracting data from the Track Usage module.

Third-party modules can provide their own plugins using different methods.

Configuration

This section covers the configuration when using the file_visibility_track_usage submodule.

Configure the Track Usage module first. Note that this is critical for the module to work, and it's crucial to understand how Track Usage works and how to track the relation between source entities, such as Content (node), and _File_ (file) entities.

Visit /admin/config/system/track-usage/settings and add a new tracking configuration, dedicated for File Visibility.
After adding a label, you can restrict some tracker plugins from being used. If not sure, leave all unchecked.
If your site is publicly exposing the source entity revisions, you might want to check the "Track only the active entity revision" checkbox.
Check "Record entity changes in real time"
Pay attention to the Source entity types section and check the entities acting as source entities. Usually, the node entity type should be checked.
If your site is using a complex, nested structure with paragraphs and/media, make sure you do the proper selection under the Traversable entity types section.
Select the File(file) entity type under Target entity types section.
It's time to configure the file visibility settings. On a complex setup you might have more than one file visibility plugins. On the /admin/config/file-visibility page you can restrict the plugins to be used. For now just leave all unchecked.
Visit /admin/config/file-visibility/track-usage page, select the Track Usage configuration you've just created, and press the Save configuration button.
Now it's time to create the initial track usage records with Drush. From the console run drush track_usage:update <config-machine-name>, where <config-machine-name> is the name of the Track Usage configuration you've just created. To get some help on the command, run drush track_usage:update --help.

You're done! Drupal will automatically track and record file usages and will move files accordingly between the public and the private filesystem.

Contribute

DDEV, a Docker-based PHP development tool for a streamlined and unified development process, is the recommended tool for contributing to the module. The DDEV Drupal Contrib addon makes it easy to develop a Drupal module by offering the tools to set up and test the module.

Install DDEV

Checkout the module

Normally, you check out the code form an issue fork:

git clone git@git.drupal.org:issue/file_visibility-[issue number].git
cd file_visibility-[issue number]

Start DDEV

Inside the cloned project run:

ddev start

This command will fire up the Docker containers and add all configurations.

Install dependencies

ddev poser

This will install the PHP dependencies. Note that this is a replacement for Composer install command that knows how to bundle together Drupal core and the module. Read more about this command at https://github.com/ddev/ddev-drupal-contrib?tab=readme-ov-file#commands

ddev symlink-project

This symlinks the module inside web/modules/custom. Read more about this command at https://github.com/ddev/ddev-drupal-contrib?tab=readme-ov-file#commands. Note that as soon as vendor/autoload.php has been generated, this command runs automatically on every ddev start.

This command should also be run when adding new directories or files to the root of the module.

ddev exec "cd web/core && yarn install"

Install Node dependencies. This is needed for the ddev eslint command.

Install Drupal

ddev install

This will install Drupal and will enable the module.

Changing the Drupal core version

Create a file .ddev/config.local.yaml
In the new config file, set the desired Drupal core version. E.g.,
```
  web_environment:
    - DRUPAL_CORE=^10.4
```
Run ddev restart

Refer to the original documentation: Changing the Drupal core version

Run tests

ddev phpunit: run PHPUnit tests
ddev phpcs: run PHP coding standards checks
ddev phpcbf: fix coding standards findings
ddev phpstan: run PHP static analysis
ddev eslint: Run ESLint on Javascript and YAML files.

File Visibility

Top 3 contributors

Issues