Link Vault for ExpressionEngine - PHP Library

As of release version 1.3.0, Link Vault includes a PHP library that can be used to extend the add-on beyond the limitations of regular ExpressionEngine™ extensions. In order to use the Link Vault PHP library, the add-on must be installed.

Usage

If you are developing a custom third-party add-on, you can load the Link Vault library using the following code:

Sample Code

ee()->load->add_package_path( PATH_THIRD.'link_vault' );
ee()->load->library('link_vault_library');

url

RETURN : String - The encrypted URL

Parameters

  • $params : array
  • $custom_field_params : array

Sample Code

$params = array(
    'url'       => 'http://myothersite.com/some/page',
    'entry_id'  => '340'
);

$custom_fields = array(
    'screen_name'   => 'SuperDuperDev',
    'page_load'     => '2013-08-13 04:23:44'
);

$url = ee()->link_vault_library->url($params, $custom_fields);

pretty_url

RETURN : String - The pretty URL.

Parameters

  • $params : array
  • $custom_field_params : array

Sample Code

$params = array(
    'url'  => 'http://somesite.com/aReallyLongUrlYouWantToTrack',
    'text' => 'Visit my other site'
);

$url = ee()->link_vault_library->pretty_url( $params );

// The result URL will look something like this: http://site.com?go=Visit-my-other-site&ACT=56

RETURN : String - HTML link element.

Parameters

  • $params : array
  • $custom_field_params : array

Sample Code

$link = ee()->link_vault_library->download_link(array(
    'directory'   => '../the-files/',
    'file_name'   => 'software.zip',
    'link_text'   => 'Download my free software',
    'entry_id'    => $entry_id
), array(
    'screen_name' => ee()->session->userdata('screen_name'),
));

download_button

RETURN : String - HTML form and form elements.

Parameters

  • $params : array
  • $custom_field_params : array

Sample Code

$link = ee()->link_vault_library->download_button(array(
    'remote'       => true,
    'file_name'    => 'http://site.com/link/to/file/on/other/site/file.zip',
    'button_text'  => 'Click here to download the zip file',
    'entry_id'     => $entry_id
), array(
    'screen_name'  => ee()->session->userdata('screen_name'),
));

download_count

RETURN : Integer - The number of downloads matching the criteria specified in the parameters.

Parameters

  • $params : array
  • $custom_field_params : array

Sample Code

// Specifying a full system path and a member ID
$count = ee()->link_vault_library->download_count(array(
    'file_path'  => '/the/system/path/to/the/file.zip',
    'member_id'  => '312',
));

// Specifying a directory relative to the document root and file separately
$count = ee()->link_vault_library->download_count(array(
    'directory'  => '../files/',
    'file_name'  => 'music-collection.zip',
));

// Specifying a URL to a file that is hosted on the site
$count = ee()->link_vault_library->download_count(array(
    'file_path' => 'http://example.com/downloads/images/horsemask.jpg'
));

click_count

RETURN : Integer - The number of times a link to a non-file URL has been clicked.

Sample Code

// Specifying a URL
$count = ee()->link_vault_library->click_count(array(
    'url' => 'http://example.com/watch/a/tutorial'
));

// Specifying a pretty URL ID
$count = ee()->link_vault_library->click_count(array(
    'pretty_url_id' => 3
));

// Counting link clicks between two dates for a particular member
$count = ee()->link_vault_library->click_count(array(
    'url'         => 'http://example.com/charts/signups',
    'member_id'   => '14023',
    'start_date'  => '2013-01-01',
    'end_date'    => '2013-04-15'
));

file_size

RETURN : String - A string representation of the file size.

This method returns the file size for a given file. The $params array parameter may containfile_pathdirectory and/or file_name. If file_path and directory

Sample Code

// Specifying a URL
$size = ee()->link_vault_library->file_size(array(
    'file_path' => 'http://example.com/storage/files/collection.zip'
));

// Specifying a full system path separate from the file
$size = ee()->link_vault_library->file_size(array(
    'directory'  => '/the/path/to/the/folder/',
    'file_name'  => 'celebration.mp3'
));

Sample output might look like:

Sample Code

11 B
24 KB
3 GB
14 TB

download

RETURN : Boolean - If the download occurred and it was logged successfully, this method returns true. Otherwise, it returns false.

This method accepts an array of link_vault_downloads columns and initiates a download based on the values in the directory and file_name parameters.

Parameters

  • $log_record_data : array

Sample Code

$status = ee()->link_vault_library->download(array(
    'unix_time'     => date('U'),
    'entry_id'      => '2034',
    'member_id'     => ee()->session->userdata('member_id'),
    'remote_ip'     => '127.0.0.1',
    'directory'     => '../hidden_files/',
    'file_name'     => 'security-files.zip',
    'is_link_click' => 'n',
    'cf_page'       => 'tutorials/security'
));

remote_download

RETURN : Void - This method redirects to a file hosted on a remote server.

This method is similar to the download() method except that it will redirect to a remote file specified in the file_name parameter.

Parameters

  • $log_record_data : array

Sample Code

ee()->link_vault_library->remote_download(array(
    'unix_time'     => date('U'),
    'member_id'     => '4',
    'remote_ip'     => '127.0.0.1',
    'file_name'     => 'http://othersite.com/path/to/file.tar.gz',
    'is_link_click' => 'n',
    'cf_page'       => 'downloads/other'
));

s3_download

RETURN : Void - This method redirects to the temporary S3 download path.

Use this method to serve a file from an S3 account. It redirects to a temporary download URL. Like download and remote_download, it also accepts an array of link_vault_downloads table columns.

Parameters

  • $log_record_data : array

Sample Code

ee()->link_vault_library->s3_download(array(
    'unix_time'  => date('U'),
    'member_id'  => ee()->session->userdata('member_id'),
    'remote_ip'  => '127.0.0.1',
    's3_bucket'  => 'site-downloads',
    'file_name'  => 'my_ebook.zip',
));

get_mime_type

RETURN : String - The MIME type.

This method fetches the MIME type for a given file extension. If the extension isn't recognized, it returns 'application/force-download'.

Parameters

  • $file_extension : string

Sample Code

$mime_type = ee()->link_vault_library->get_mime_type('zip');
$mime_type = ee()->link_vault_library->get_mime_type('jpg');
$mime_type = ee()->link_vault_library->get_mime_type('mp3');

serve_file

RETURN : Void - This method serves a file.

Parameters

  • $header_data : array

Sample Code

ee()->link_vault_library->serve_file(array(
    'mime_type'  => ee()->link_vault_library->get_mime_type('zip'),
    'file_path'  => '/the/full/system/path/to/file.zip',
    'file'       => 'file.zip'
));

ee()->link_vault_library->serve_file(array(
    'mime_type'   => ee()->link_vault_library->get_mime_type('zip'),
    'file_path'   => '/the/full/system/path/to/super-long-filename-382572983584937485784.zip',
    'file'        => 'your_download.zip'
));

normalize_directory

This method formats a system path so that it is relative to document root, Link Vault's preferred method for storing the directory column values in the link_vault_downloads table.

RETURN : String - The directory as it should be stored in the Link Vault tables.

Parameters

  • $dir : string

Sample Code

$dir = ee()->link_vault_library->normalize_directory('/the/system/path/public_html/downloads');
// $dir = 'downloads/';

$dir = ee()->link_vault_library->normalize_directory('/the/system/path/files');
// $dir = '../files/';

distinct_download_directory_options

RETURN : Array - An associative array of distinct directories to directories. Yes, you read that correctly. It is primarily used by the control panel reporting tool to build an HTML select element.

Parameters

  • $table_name : string

Sample Code

$options = ee()->link_vault_library->distinct_download_directory_options('downloads');
$options = ee()->link_vault_library->distinct_download_directory_options('leeches');

A sample array result may look like:

Sample Code

Array(
    '../downloads/' => '../downloads/',
    'my/files/'     => 'my/files',
    'images/'       => 'images/'
)

distinct_s3_bucket_options

RETURN : Array - An associative array of S3 buckets to S3 buckets. This method is also primarily used to construct a list of options for an HTML select element.

Parameters

  • $table_name : string

Sample Code

$options = ee()->link_vault_library->distinct_s3_bucket_options('downloads');
$options = ee()->link_vault_library->distinct_s3_bucket_options('leeches');

A sample array result may look like:

Sample Code

Array(
    'images'    => 'images',
    'music'     => 'music',
    'personal'  => 'personal'
)

distinct_pretty_urls

RETURN : Array - An associative array of pretty URL IDs to their corresponding text.

Sample Code

$options = ee()->link_vault_library->distinct_pretty_urls();

A sample array result may look like:

Sample Code

Array(
    '1' => 'Google-Search-Results',
    '2' => 'Visit-My-Business-Website',
    '3' => 'Disguised-Affiliate-Link'
)

log_download

RETURN : Integer - The id of the inserted log row.

This method logs a download without actually serving the file. It assumes that the file is being served elsewhere. The $record_data array should contain link_vault_downloads table column names to values.

Parameters

  • $record_data : array

Sample Code

$data = array(
    'site_id'        => '1',
    'entry_id'       => '1013',
    'unix_time'      => '1366903271',
    'member_id'      => '9',
    'remote_ip'      => '127.0.0.1',
    'directory'      => '../downloads/',
    'file_name'      => 'phone-images.zip',
    'is_link_click'  => 'n',
    'cf_my_field'    => 'Whatever you want to store in the log'
);

$id = ee()->link_vault_library->log_download( $data );

encrypt

RETURN : String - The encrypted string

This method encrypts some text using the salt value saved in the Link Vault settings.

Parameters

  • $string : string

Sample Code

$text = 'Some secret information';
$encrypted_text = ee()->link_vault_library->encrypt( $text );

decrypt

RETURN : String - The unencrypted text.

This method decrypts an encrypted string that was encrypted using the Link Vault library's encrypt method.

Parameters

  • $string : string

Sample Code

$text = ee()->link_vault_library->decrypt( $encrypted_string );

fetch_boolean

RETURN : Boolean

This method is used to handle the forgiveness of improper boolean parameter values.

Parameters

  • $value : mixed (Default: false)

Sample Code

$bool = ee()->link_vault_library->fetch_boolean('on');     // true
$bool = ee()->link_vault_library->fetch_boolean('off');    // false
$bool = ee()->link_vault_library->fetch_boolean('yes');    // true
$bool = ee()->link_vault_library->fetch_boolean('no');     // false
$bool = ee()->link_vault_library->fetch_boolean('true');   // true
$bool = ee()->link_vault_library->fetch_boolean('false');  // false
$bool = ee()->link_vault_library->fetch_boolean('1');      // true
$bool = ee()->link_vault_library->fetch_boolean('0');      // false

row_search

RETURN : Array - The array of result rows.

This method serves as a query builder for the Link Vault control panel reporting tool and the:records template tag. You are free to use it, but you'll probably just want to build your own queries.

Parameters

  • $query_data : Array - This parameter contains table columns and values as well as instructions for how to build the query.
  • $custom_fields : Array - This parameter contains an associative array of Link Vault custom field column names to values.
  • $cf_exact_match : boolean - If this parameter is set to true, the query will look for an exact match with the custom field parameters. (Default: false)
  • $prefix : string - Any specified prefix will be prepended to the return row column names. This is useful for template tags.

Sample Code

/*
This example will return the top 5 downloads between two dates for member with ID 3405 where the download page is exactly 'downloads/music'. The results are ordered by most downloads in descending order.
*/

$data = array(
    'table'           => 'downloads', // (downloads | leeches)
    'member_id'       => '3405',
    'start_date'      => 1366903271,
    'end_date'        => 1366908135,
    'group_by'        => 'file_name',
    'count_variable'  => 'my_count',
    'order_by'        => 'my_count',
    'sort'            => 'desc',
    'limit'           => '5'
);

$custom_fields = array(
    'cf_download_page' => 'downloads/music'
);

$rows = ee()->link_vault_library->row_search($data, $custom_fields, true, 'lv_');

row_search_count

Added in version 1.3.8

RETURN : integer - The number of matching rows.

This method is just like the row_search method except it only returns the number of matching rows without loading them into memory.

Parameters

  • $query_data : Array - This parameter contains table columns and values as well as instructions for how to build the query.
  • $custom_fields : Array - This parameter contains an associative array of Link Vault custom field column names to values.
  • $cf_exact_match : boolean - If this parameter is set to true, the query will look for an exact match with the custom field parameters. (Default: false)

Sample Code

/*
This example will return the total number of downloads for a particular member between two dates.
*/

$data = array(
    'table'           => 'downloads', // (downloads | leeches)
    'member_id'       => '3405',
    'start_date'      => 1366903271,
    'end_date'        => 1366908135
);

$total_downloads = ee()->link_vault_library->row_search_count($data);