Developer API Reference: Core Action Hooks & Extensibility

By /

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 NameDefault ValueDescription
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_subfoldersfalse (Core) / true (Pro)Filters whether hierarchical subfolder navigation and storage is enabled.
sfvlt_upload_filename$filenameFilters the raw uploaded filename before sanitization and storage.
sfvlt_render_file_actions$actions arrayFilters the action buttons (Download, Open preview, Share, Metadata) rendered for each file.
sfvlt_query_files_list$files_list arrayFilters 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 );
}
Scroll to Top