=== If File Exists ===
Contributors: coffee2code
Donate link: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=6ARCFJ9TX3522
Tags: file, exists, existence, check, presence, files, theme, template tag, coffee2code
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Requires at least: 2.7
Tested up to: 5.3
Stable tag: 2.2.7

Check if a file exists and return true/false or display a string containing information about the file.


== Description ==

This plugin provides the functions `c2c_if_file_exists()`, `c2c_if_theme_file_exists()`, `c2c_if_plugin_file_exists()` that check if a file exists and either return true/false or display a string containing information about the file.

* If a format string is not passed to it, the functions return a simple boolean (true or false) indicating if the specified file exists.
* Otherwise, the format string provided to it will be used to construct a response string, which can be customized to display information about the file (such as file_name, file_url, or file_path). If the `$echo` argument is true, that string is displayed on the page. Regardless of the value of `$echo`, the response string is returned by the function.

By default, 'c2c_if_file_exists()' assumes you are looking for the file relative to the default WordPress upload directory. If you wish to search another directory, specify it as the $dir argument. 'c2c_if_theme_file_exists()' assumes you are looking for a file relative to the currently active theme's home directory. 'c2c_if_plugin_file_exists()' assumes you are looking for a file relative to the directory that contains WordPress plugins.

Links: [Plugin Homepage](http://coffee2code.com/wp-plugins/if-file-exists/) | [Plugin Directory Page](https://wordpress.org/plugins/if-file-exists/) | [GitHub](https://github.com/coffee2code/if-file-exists/) | [Author Homepage](http://coffee2code.com)


== Installation ==

1. Install via the built-in WordPress plugin installer. Or download and unzip `if-file-exists.zip` inside the plugins directory for your site (typically `wp-content/plugins/`)
2. Activate the plugin through the 'Plugins' admin menu in WordPress
3. In one or more of your templates, utilize one of the template tags provided by this plugin (see examples)


== Template Tags ==

The plugin provides three template tags for use in your theme templates.

= Functions =

* `<?php function c2c_if_file_exists($filename, $format = '', $echo = true, $dir = '') ?>`
Checks if a file exists and returns true/false or displays a string containing information about the file.
* `<?php function c2c_if_plugin_file_exists( $filename, $format = '', $echo = true, $dir = '', $show_if_not_exists = '' ) ?>`
Checks if a file exists (relative to the plugins directory) and returns true/false or displays a string containing information about the file.
* `<?php function c2c_if_theme_file_exists( $filename, $format = '', $echo = true, $dir = '', $show_if_not_exists = '' ) ?>`
Checks if a file exists (relative to the current theme's directory) and returns true/false or displays a string containing information about the file. If the current theme is a child theme, then the function will check if the file exists first in the child theme's directory, and if not there, then it will check the parent theme's directory.

= Arguments =

* `$filename`
String. Name of the filename whose existence is being checked. Do not include path information.

* `$format`
(optional) String. Text to be displayed or returned when $filename exists. Leave blank to return true or false. The following percent-tag substitutions are available for optional use in the $format string:
    * `%file_directory%` : the directory of the file, i.e. "/usr/local/www/yoursite/wp-content/uploads/"
    * `%file_extension%` : the extension of the file, i.e. "zip"`
    * `%file_name%` : the name of the file, i.e. "pictures.zip"
    * `%file_url%` : the URL of the file, i.e. "http://yoursite.com/wp-content/uploads/pictures.zip"
    * `%file_path%`: the filesystem path to the file, i.e. "/usr/local/www/yoursite/wp-content/uploads/pictures.zip"

* `$echo`
(optional) Boolean. Should `$format` be echoed when the filename exists? NOTE: the string always gets returned unless file does not exist). Default is true.

* `$dir`
(optional) String|Boolean. The directory (relative to the root of the site) to check for $filename. If empty, the WordPress upload directory is assumed (if using `c2c_if_file_exists()`). If 'true', then it indicates the filename includes the directory.

* `$show_if_not_exists`
(optional) String. Text to display if the file does not exists. $format must also be specified. Format is the same as $format argument.

= Examples =

* `<?php
$format = "<a href='%file_url%'>Download %file_name% now!</a>";
$file_name = 'pictures-' . get_the_ID() . '.zip';
c2c_if_file_exists($file_name, $format);
?>`

* `<?php
if ( c2c_if_file_exists($file_name) ) {
   // Do stuff here
}
?>`

* `<?php c2c_if_file_exists($file_name, '%file_name% exists!'); ?>`

* `<?php c2c_if_file_exists($file_name, '%file_name% also exists in upload2 directory', true, 'wp-content/uploads2'); ?>`

* `<?php c2c_if_file_exists($file_name, '%file_name% also exists in upload2 directory', true, 'wp-content/uploads2', '%file_name% did not exist!'); ?>`

* `<?php c2c_if_plugin_file_exists('akismet.php', 'Akismet is present', true, 'akismet'); ?>`

* `<?php c2c_if_plugin_file_exists('akismet/akismet.php', 'Akismet is present', true, true); ?>`

* `<?php c2c_if_theme_file_exists('home.php', 'Home template is present', true, '', 'Home template does not exist.'); ?>`


== Hooks ==

The plugin exposes three filters for hooking. Code using these filters should ideally be put into a mu-plugin or site-specific plugin (which is beyond the scope of this readme to explain). Less ideally, you could put them in your active theme's functions.php file.

**c2c_if_file_exists (filter)**

The 'c2c_if_file_exists' hook allows you to use an alternative approach to safely invoke `c2c_if_file_exists()` 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.

Arguments:

* same as for `c2c_if_file_exists()`

Example:

Instead of:

`<?php c2c_if_file_exists( $file, '%file_url%' ); ?>`

Do:

`<?php apply_filters( 'c2c_if_file_exists', $file, '%file_url%' ); ?>`

**c2c_if_plugin_file_exists (filter)**

The 'c2c_if_plugin_file_exists' hook allows you to use an alternative approach to safely invoke `c2c_if_plugin_file_exists()` 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.

Arguments:

* same as for `c2c_if_plugin_file_exists()`

Example:

Instead of:

`<?php $exists = c2c_if_plugin_file_exists( $file ); ?>`

Do:

`<?php $exists = apply_filters( 'c2c_if_plugin_file_exists', $file ); ?>`

**c2c_if_theme_file_exists (filter)**

The 'c2c_if_theme_file_exists' hook allows you to use an alternative approach to safely invoke `c2c_if_theme_file_exists()` 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.

Arguments:

* same as for `c2c_if_theme_file_exists()`

Example:

Instead of:

`<?php $exists = c2c_if_theme_file_exists( $file ); ?>`

Do:

`<?php $exists = apply_filters( 'c2c_if_theme_file_exists', $file ); ?>`


== Changelog ==

= 2.2.7 (2019-11-22) =
* Change: Note compatibility through WP 5.3+
* Change: Update copyright date (2020)

= 2.2.6 (2019-02-11) =
* New: Add CHANGELOG.md and move all but most recent changelog entries into it
* Change: Note compatibility through WP 5.1+
* Change: Update unit test install script and bootstrap to use latest WP unit test repo
* Change: Reformat function docblocks for better line-wrapping and alignment
* Change: Update copyright date (2019)
* Change: Update License URI to be HTTPS
* Change: Split paragraph in README.md's "Support" section into two

= 2.2.5 (2018-05-22) =
* New: Add README.md
* New: Add GitHub link to readme
* Change: Minor whitespace tweaks to unit test bootstrap
* Change: Rename readme.txt section from 'Filters' to 'Hooks'
* Change: Modify formatting of hook name in readme to prevent being uppercased when shown in the Plugin Directory
* Change: Note compatibility through WP 4.9+
* Change: Update copyright date (2018)

= Full changelog is available in [CHANGELOG.md](CHANGELOG.md). =


== Upgrade Notice ==

= 2.2.7 =
Trivial update: noted compatibility through WP 5.3+ and updated copyright date (2020).

= 2.2.6 =
Trivial update: created CHANGELOG.md to store historical changelog outside of readme.txt, noted compatibility through WP 5.1+, and updated copyright date (2019)

= 2.2.5 =
Trivial update: noted compatibility through WP 4.9+, added README.md for GitHub, updated copyright date (2018), and other minor changes

= 2.2.4 =
Trivial update: fixed some unit tests, noted compatibility through WP 4.7+, updated copyright date

= 2.2.3 =
Trivial update: improved support for localization, minor unit test tweaks, verified compatibility through WP 4.4+, and updated copyright date (2016)

= 2.2.2 =
Trivial update: noted compatibility through WP 4.1+ and updated copyright date (2015)

= 2.2.1 =
Trivial update: noted compatibility through WP 4.0+; added plugin icon.

= 2.2 =
Recommended minor update: fixed a few minor bugs; added unit tests; noted compatibility through WP 3.8+

= 2.1.3 =
Trivial update: noted compatibility through WP 3.5+; minor documentation changes

= 2.1.2 =
Trivial update: noted compatibility through WP 3.4+; explicitly stated license

= 2.1.1 =
Trivial update: noted compatibility through WP 3.3+ and minor readme.txt tweaks

= 2.1 =
Recommended minor update. Highlights: fixed a few minor bugs, added tests, clarified/updated some documentation, and verified compatibility with WordPress 3.2.

= 2.0 =
Recommended feature update. Highlights: added c2c_if_plugin_file_exists() and c2c_if_theme_file_exists(); added %file_directory% and %file_extension%; added hooks for customization; minor fixes and tweaks; renamed blog_time() to c2c_blog_time(); renamed class; verified WP 3.0 compatibility.