README

保护并跟踪您网站上的下载。防止并跟踪下载盗链尝试。

这是一个Craft CMS 5的商业插件。

目录

• 要求
• 安装
• 设置
• 配置变量
• 模板变量
• 事件

要求

• Craft CMS v5.0.0+
• PHP 8.2+

安装

将以下内容添加到您的composer.json要求中。请确保调整版本号以匹配您要安装的版本。

"masugadesign/linkvault": "5.0.2",

设置

盗链尝试模板

当启用盗链阻止时，此模板将在有人尝试作为盗链下载URL时以403状态加载。如果此设置留空，Link Vault提供默认模板以供使用。

丢失文件模板

当有人尝试下载不存在的文件时，此模板将以404状态加载。如果此设置留空，Link Vault提供默认模板以供使用。

配置变量

Link Vault有一些配置变量，您可以通过在项目的craft/config/文件夹中创建一个linkvault.php文件来覆盖这些变量。默认值如下所示。

<?php

return [
    // Set to "true" for additional logging.
    'debug' => false,
    // The route URI to use when generating download URLs.
    'downloadTrigger' => 'download',
    // Set to "true" to prevent file leeching.
    'blockLeechAttempts' => true,
    // Set to "true" to log leech attempts.
    'logLeechAttempts' => true
];

模板变量

downloadUrl

下载URL接受两个参数

• 文件 - 这可能是一个Asset元素的实例，也可能是一个指向服务器上文件的系统路径（字符串）。只要路径可以通过web服务器访问，它就可以存在任何地方。
• 附加参数 - 这是一个自定义字段或其他要保存到下载记录中的变量的数组。

示例

{# Example 1: Passing an Asset element instance. #}
{% for download in entry.downloadableAssets.all() %}
    <a href="{{ craft.linkvault.downloadUrl(download) }}" >Download This</a>
{% endfor %}

{# Example 2: A hard-coded full system path. #}
<a href="{{ craft.linkvault.downloadUrl('/home/user1337/www/uploads/songs/love.mp3') }}" >Download This</a>

{# Example 3: A full URL to a remote file. #}
<a href="{{ craft.linkvault.downloadUrl('http://example.com/downloads/art/cat-rides-bike.zip') }}" >Download This</a>

如您所见，传递Asset元素的实例是创建Link Vault下载URL的最简单方法。此方法也适用于存储在S3源上的文件。

以下是使用第二个参数传递元素ID的一些示例。在Craft中，条目和资产具有唯一的元素ID。您可以将什么存储在linkvault_downloads.elementId列中完全取决于您，因为它仅用于信息目的。如果第一个参数是有效的AssetD，Link Vault将自动将其ID存储在linkvault_downloads.assetId列中。

{# Example 5: The asset's parent entry's ID is stored in the elementId column. #}
{% for download in entry.downloadableAssets.all() %}
    <a href="{{ craft.linkvault.downloadUrl(download, {elementId : entry.id}) }}" >Download This</a>
{% endfor %}

{# Example 6: The asset's ID is stored in the elementId column. #}
{% for download in entry.downloadableAssets.all() %}
    <a href="{{ craft.linkvault.downloadUrl(download, {elementId : download.id}) }}" >Download This</a>
{% endfor %}

您可以使用Link Vault的控制面板中的自定义字段选项卡创建自定义字段来存储任何您喜欢的数据。一旦您创建了一个字段，只需在数组参数中使用该字段的handle即可。

{# Example 7: Passing along a value for a user-defined field. #}
{% for download in entry.downloadableAssets.all() %}
    <a href="{{ craft.linkvault.downloadUrl(download, {userEmail : craft.session.getUser().email}) }}" >Download This</a>
{% endfor %}

zipUrl

zipUrl模板变量生成一个用于将文件集合即时压缩的Link Vault下载URL。每个文件都会在日志中单独跟踪。根据要压缩的文件的大小，即时压缩文件可能需要大量的内存。建议仅在小文件（<10MB）上使用此功能。

第一个参数可能是一个Craft Asset元素的数组或Craft Asset ID。第二个参数是要生成的压缩文件的基准名称。

示例

{% set assetIds = craft.assets.volume('misc').limit(5).ids() %}
<a href="{{ craft.linkvault.zipUrl(assetIds, 'some-misc-assets') }}" >Download Now</a>

totalDownloads

totalDownloads变量返回给定一组标准下的总下载量。它与downloadUrl变量非常相似，但它只有一个参数，可以是以下三种之一

• 一个Asset元素的实例。
• 一组参数
• 包含文件完整系统路径的字符串。

示例

{# Example 8: Passing an Asset element. #}
{% for download in entry.downloadableAssets %}
    <p>The {{ download.filename }} file has been downloaded {{ craft.linkvault.totalDownloads(download) }} times!</p>
{% endfor %}

{# Example 9: Passing an array of parameters. #}
{% for download in entry.downloadableAssets %}
    <p>Your bird.txt Downloads: {{ craft.linkvault.totalDownloads({userId:craft.session.getUser().id, fileName:"bird.txt" }) }}</p>
{% endfor %}

{# Example 10: Passing a string containing the full system path. #}
Total face.gif downloads: {{ craft.linkvault.totalDownloads('/home/user1337/www/uploads/face.gif') }}

{# Example 11: Passing a URL. #}
Downloads: {{ craft.linkvault.totalDownloads('https://example.com/documents/contract.docx') }}

文件大小

文件大小模板变量用于获取指定文件的易读文件大小字符串。这可以用于存储在Craft中作为资产之外的服务器文件，尽管它也可以与资产文件一起使用。对于资产元素，使用原生的{{ file.size|filesize }}可能更合适。

示例

{# Example 12: Passing a file path. #}
bees.jpg is {{ craft.linkvault.fileSize('/home/user1337/hidden-files/bees.jpg') }}.

{# Example 13: Passing an instance of an Asset element. #}
{{ file.filename }} is {{ craft.linkvault.fileSize(file) }}.

{# Example 14: Passing a URL. WARNING: The fileSize variable is sometimes inconsistent with remote files any may not always return a file size. #}
{{ craft.linkvault.fileSize('https://example.com/songs/dance-me-to-the-end-of-love.flac') }}

baseTwoFileSize（自v3.1.2添加）

baseTwoFileSize模板变量是文件大小模板变量的别名。使用1024作为除数。

baseTenFileSize（自v3.1.2添加）

baseTenFileSize模板变量与文件大小和baseTwoFileSize类似，但文件大小是使用1000作为除数来计算的。

下载次数

下载次数模板变量根据指定的标准获取下载记录。

示例

{# Example 15: Fetch the ten most recent download records for cheese.mpg. #}
{% for record in craft.linkvault.downloads.fileName('cheese.mpg).limit(10).all() %}
    <p>User {{ record.userId }} downloaded it on {{ record.dateCreated }}</p>
{% endfor %}

{# Example 16: Fetch 5 most recent downloads that occurred prior to March 1, 2016. #}
{% for record in craft.linkvault.downloads.before('2016-03-01').limit(10).all() %}
    <p>User {{ record.userId }} downloaded {{ record.filename }} before March 1.</p>
{% endfor %}

{# Example 17: Fetch records based on custom field value. In this example, assume existence of "downloadPage" field. #}
{% for record in craft.linkvault.downloads.downloadPage('super-mega-rockstar/free-songs').all() %}
    <p>User {{ record.userId }} downloaded {{ record.filename }} song file on {{ record.dateCreated }}</p>
{% endfor %}

盗链尝试

盗链尝试模板变量与下载次数变量工作方式完全相同，但它只返回盗链尝试记录。

记录

记录模板变量与下载次数和盗链尝试变量工作方式相同，但它将返回所有记录，而不管类型如何。

groupCount（自v1.0.2添加）

groupCount模板变量查询记录数并将它们按特定列名分组。

{# Example 18: Fetch a particular user's top five file downloads by `fileName`. Order the results by the count, descending. #}
{% set topDownloads = craft.linkvault.groupCount('fileName', {
    'userId' : currentUser.id
}, 'COUNT(*) desc', 5) %}
<ol>
{% for topDownload in topDownloads %}
    <li>{{ topDownload.fileName }} ({{ topDownload.census|number_format(0) }} downloads)</li>
{% endfor %}
</ol>

customFields（自v3.2.0添加）

customFields模板变量允许查询Link Vault定义的自定义字段。

{% set myField = craft.linkvault.customFields.fieldName('myField').one() %}

{% set allFields = craft.linkvault.customFields.all() %}

事件

LinkVaultDownload元素继承了所有标准的Craft元素事件。以下是一个关于craft\base\Element::EVENT_BEFORE_SAVE事件的示例

<?php

use craft\events\ModelEvent;
use Masuga\LinkVault\elements\LinkVaultDownload;
use yii\base\Event;

Event::on(LinkVaultDownload::class,
    LinkVaultDownload::EVENT_BEFORE_SAVE,
    function (ModelEvent $event) {
        $linkVaultDownloadElement = $event->sender;
        $isNew = $event->isNew;
});

此外，Link Vault包含以下事件

LinkClickEvent（自v3.1.0添加）

此事件在某人点击/跟随Link Vault URL并解密加密参数后立即触发。

<?php

use Masuga\LinkVault\controllers\LinkVaultController;
use Masuga\LinkVault\events\LinkClickEvent;
use yii\base\Event;

Event::on(LinkVaultController::class,
    LinkVaultController::EVENT_LINK_CLICK,
    function (LinkClickEvent $event) {
	    $event->parameters['additional_parameter'] = 'a value';
        if ( $event->parameters['assetId'] == 5 ) {
            ...
        }
});

ModifyZipUrlFilesEvent（自v3.1.0添加）

此事件在Link Vault zipUrl标签创建即时生成的zip文件之前立即触发。该事件允许向要压缩的文件数组中添加文件或从数组中删除文件。

<?php

use Masuga\LinkVault\events\ModifyZipUrlFilesEvent;
use Masuga\LinkVault\services\ArchiveService;
use yii\base\Event;

...

Event::on(ArchiveService::class,
    ArchiveService::EVENT_MODIFY_ZIP_URL_FILES,
    function (ModifyZipUrlFilesEvent $event) {
	    $event->files[] = '/path/to/file.jpg';
        $event->files[] = 5; // Asset ID
});