Developer API Reference: Core Action Hooks & Extensibility
Simple File Vault is engineered to be highly extensible. By utilizing WordPress’s native hook and filter architecture, developers can customize permissions, intercept file lifecycles, and seamlessly integrate vault operations with third-party tools, CRM platforms, Slack/Discord notifications, or custom transactional email systems.
This document details all core action hooks and filters exposed by the plugin and provides a production-ready PHP integration example.
1. Core Action Hooks
sfvlt_after_file_upload
Fires immediately after a file has been successfully validated, assembled from chunks, moved into the secure vault, and its uploader metadata has been persisted.
do_action( 'sfvlt_after_file_upload', string $file_path, array $file_meta_array, array $uploader_data );$file_path(string): The absolute physical path to the file inside the secure vault directory (e.g.,/var/www/html/wp-content/uploads/safe-vault/user-12/document.pdf).$file_meta_array(array): File metadata parsed by the server:name(string): The sanitized basename of the file.size(int): File size in bytes.type(string): The validated MIME type (e.g.,application/pdf).$uploader_data(array): Sanitized metadata collected from frontend uploader form inputs or form integrations:uploader_name(string): The uploader’s self-reported name.uploader_email(string): The uploader’s email address.uploader_comments(string): Accompanying text comments.
sfvlt_file_uploaded
Fires immediately after a file is stored on disk, before metadata is processed.
do_action( 'sfvlt_file_uploaded', string $file_path, string $filename );sfvlt_after_file_deleted
Fires immediately after a file is deleted from the vault by an administrator or manager, allowing developers to clean up external files, delete logs, or update database registries.
do_action( 'sfvlt_after_file_deleted', string $file_path );sfvlt_registry_rescanned
Fires whenever the transient file index registry has been fully rebuilt from a physical scan of storage directories.
do_action( 'sfvlt_registry_rescanned', array $files );sfvlt_verify_download_access
Fires during download token verification before the file is streamed to the user, allowing developers to enforce custom download access limits, quota trackers, or access logs.
do_action( 'sfvlt_verify_download_access', string $file_path );sfvlt_before_file_list
Fires directly before the frontend file list HTML container is rendered, ideal for outputting notices, instructions, or custom UI elements.
do_action( 'sfvlt_before_file_list' );sfvlt_run_cron_scan
Fires during background maintenance cron jobs to rebuild the file registry cache and synchronize external directory additions.
do_action( 'sfvlt_run_cron_scan' );2. Core Filter Hooks
| Filter Name | Default Value | Description |
|---|---|---|
sfvlt_upload_capability | 'upload_files' | Filters the WordPress user capability required to upload files to the vault. |
sfvlt_view_capability | 'read' | Filters the WordPress user capability required to view the vault file list. |
sfvlt_allow_subfolders | false (Core) / true (Pro) | Filters whether hierarchical subfolder navigation and storage is enabled. |
sfvlt_upload_filename | $filename | Filters the raw uploaded filename before sanitization and storage. |
sfvlt_render_file_actions | $actions array | Filters the action buttons (Download, Open preview, Share, Metadata) rendered for each file. |
sfvlt_query_files_list | $files_list array | Filters the entire file list payload returned by the REST API (used for access control, search, and metadata tagging). |
3. Practical Implementation: Custom Transactional Email Notification
The following PHP snippet demonstrates how a developer can tap into sfvlt_after_file_upload inside their child theme’s functions.php or custom plugin to trigger a custom transactional email notification containing uploader details and a dynamic, HMAC-signed download link:
<?php
/**
* Hook into Simple File Vault to send email notifications on successful frontend uploads.
*/
add_action( 'sfvlt_after_file_upload', 'custom_sfvlt_upload_notification', 10, 3 );
function custom_sfvlt_upload_notification( $file_path, $file_meta, $uploader_data ) {
// 1. Check if uploader metadata is populated. If empty, fallback gracefully.
$uploader_name = ! empty( $uploader_data['uploader_name'] ) ? esc_html( $uploader_data['uploader_name'] ) : 'Anonymous Client';
$uploader_email = ! empty( $uploader_data['uploader_email'] ) ? sanitize_email( $uploader_data['uploader_email'] ) : 'No email provided';
$uploader_notes = ! empty( $uploader_data['uploader_comments'] ) ? esc_html( $uploader_data['uploader_comments'] ) : 'No notes attached.';
$file_name = esc_html( $file_meta['name'] );
$file_size = size_format( $file_meta['size'] ); // WordPress helper to format bytes into KB/MB
// 2. Generate a secure, signed download URL for the administrator.
$uploader = new \SFVLT\SimpleFileVault\SFVLT_Uploader();
$base_dir = $uploader->get_vault_directory();
$relative_path = ltrim( str_replace( wp_normalize_path( $base_dir ), '', wp_normalize_path( $file_path ) ), '/' );
// Generate download token (valid for 3 hours)
$download_token = \SFVLT\SimpleFileVault\SFVLT_Rest_Api::generate_download_token( $relative_path );
$secure_download_url = esc_url_raw( rest_url( 'safe-vault/v1/download?token=' . urlencode( $download_token ) ) );
// 3. Compose the Email
$to = get_option( 'admin_email' ); // Send to site administrator
$subject = sprintf( '[Safe Vault] New File Uploaded: %s', $file_name );
$headers = array( 'Content-Type: text/html; charset=UTF-8' );
ob_start();
?>
<html>
<body style="font-family: sans-serif; line-height: 1.5; color: #333;">
<div style="max-width: 600px; margin: 0 auto; padding: 20px; border: 1px solid #eee; border-radius: 8px;">
<h2 style="color: #2563eb; margin-top: 0;">New Safe File Upload Notification</h2>
<p>A new document has been uploaded to the file vault. Here are the details:</p>
<table style="width: 100%; border-collapse: collapse; margin-bottom: 20px;">
<tr style="background: #f9fafb;">
<td style="padding: 8px; font-weight: bold; border-bottom: 1px solid #eee; width: 150px;">Uploader Name:</td>
<td style="padding: 8px; border-bottom: 1px solid #eee;"><?php echo $uploader_name; ?></td>
</tr>
<tr>
<td style="padding: 8px; font-weight: bold; border-bottom: 1px solid #eee;">Uploader Email:</td>
<td style="padding: 8px; border-bottom: 1px solid #eee;"><a href="mailto:<?php echo esc_attr( $uploader_email ); ?>"><?php echo $uploader_email; ?></a></td>
</tr>
<tr style="background: #f9fafb;">
<td style="padding: 8px; font-weight: bold; border-bottom: 1px solid #eee;">File Name:</td>
<td style="padding: 8px; border-bottom: 1px solid #eee;"><strong><?php echo $file_name; ?></strong></td>
</tr>
<tr>
<td style="padding: 8px; font-weight: bold; border-bottom: 1px solid #eee;">File Size:</td>
<td style="padding: 8px; border-bottom: 1px solid #eee;"><?php echo $file_size; ?></td>
</tr>
<tr style="background: #f9fafb;">
<td style="padding: 8px; font-weight: bold; border-bottom: 1px solid #eee;">Uploader Comments:</td>
<td style="padding: 8px; border-bottom: 1px solid #eee; font-style: italic;"><?php echo nl2br( $uploader_notes ); ?></td>
</tr>
</table>
<div style="text-align: center; margin-top: 25px;">
<a href="<?php echo $secure_download_url; ?>" style="background: #2563eb; color: #ffffff; padding: 12px 24px; text-decoration: none; border-radius: 6px; font-weight: bold; display: inline-block;">
Download Secure File
</a>
</div>
<p style="font-size: 11px; color: #999; margin-top: 30px; border-top: 1px solid #eee; padding-top: 10px; text-align: center;">
This secure link will expire in 3 hours. Direct request or public hotlinking is prohibited.
</p>
</div>
</body>
</html>
<?php
$body = ob_get_clean();
// 4. Fire the email transaction
wp_mail( $to, $subject, $body, $headers );
}