Random File

This plugin provides template tags that allow you to retrieve the name, path (relative or absolute), url, or fully marked-up link to a randomly chosen file or files in a specified directory.

Arguments to the functions permit you to limit what file(s) can be randomly selected based on a given set of file extensions. You can also explicitly specify files that should not be randomly selected.

This functionality can be useful for displaying random images/logos or including text from random files onto your site (writing excerpts, multi-line quotes, etc). Other ideas: random ads, random CSS files, random theme template selection.

Notes:

• If you want to actually display the name of the random file, be sure to ‘echo’ the results:

• Unless you limit the file search to only include a particular extension (via $extensions argument), all files in the specified $dir will be under consideration for random selection

• Can be run inside or outside of “the loop”

Links: Plugin Homepage | Plugin Directory Page | GitHub | Author Homepage

Developer Documentation

Developer documentation can be found in DEVELOPER-DOCS.md. That documentation covers the template tags and hooks provided by the plugin.

As an overview, these are the template tags provided by the plugin:

• c2c_random_file() : Retrieves the name of a random file from a specified directory and returns information based on the file.
• c2c_random_files() : Retrieves the name, path, or link to a specified number of randomly chosen files in a specified directory.

Theses are the hooks provided by the plugin:

• c2c_random_file : Filter to safely invoke c2c_random_file() in such a way that if the plugin were deactivated or deleted, then your calls to the function won’t cause errors in your site.
• c2c_random_files : Filter to safely invoke c2c_random_files() in such a way that if the plugin were deactivated or deleted, then your calls to the function won’t cause errors in your site.

2.0 (2024-08-13)

Highlights:

This minor update features improved randomization of file selection, adds support for the extensions arugment to be an array, notes compatibility through WP 6.6+, removes unit tests from release packaging, updates copyright date (2024), and other code improvements and minor changes.

Details:

• Change: Switch to using wp_rand() for more reliable randomization
• Change: Allow $extensions argument to also accept an array of extensions
• Change: Strip surrounding whitespace and leading periods from provided extensions
• Change: Explicitly return false if no file could be found
• Change: Switch to use a switch statement, which is more concise
• Change: Use cleaner sprintf() approach to outputting markup
• Hardening: Escape text shown via ‘hyperlink’ output (though it’s never anything other than plaintext)
• Change: Note compatibility through WP 6.6+
• Change: Update copyright date (2024)
• Change: Tweak filter descriptions in readme.txt
• New: Add .gitignore file
• Change: Remove development and testing-related files from release packaging
• Unit tests:
  • Hardening: Prevent direct web access to bootstrap.php
  • Allow tests to run against current versions of WordPress
  • New: Add more unit tests
  • New: Add composer.json for PHPUnit Polyfill dependency
  • Change: In bootstrap, store path to plugin directory in a constant
  • Change: Rename a test

1.8.12 (2023-05-21)

• New: Add DEVELOPER-DOCS.md and move hooks documentation into it
• Change: Note compatibility through WP 6.3+
• Change: Update copyright date (2023)

1.8.11 (2021-09-18)

• Change: Note compatibility through WP 5.8+
• Unit tests:
  • Change: Restructure unit test directories
    • Change: Move phpunit/ into tests/
    • Change: Move phpunit/bin into tests/
  • Change: Remove ‘test-‘ prefix from unit test file
  • Change: In bootstrap, store path to plugin file constant
  • Change: In bootstrap, add backcompat for PHPUnit pre-v6.0

Full changelog is available in CHANGELOG.md.

1. Install via the built-in WordPress plugin installer. Or download and unzip random-file.zip inside the plugins directory for your site (typically wp-content/plugins/)
2. Activate the plugin through the ‘Plugins’ admin menu in WordPress
3. Make use of the c2c_random_file() or c2c_random_files() template function in your code or template (see examples below).