README

概述

一个可用于将短网址添加到现有Web应用的Laravel包。

安装

要求

该包已开发和测试，以与以下最低要求兼容

PHP 8.0
Laravel 8.0

短网址需要PHP扩展中的BC Math或GMP，才能正常运行。

安装包

您可以通过Composer安装此包

composer require ashallendesign/short-url

发布配置和迁移

然后，您可以使用以下命令发布包的配置文件和数据库迁移

php artisan vendor:publish --provider="AshAllenDesign\ShortURL\Providers\ShortURLProvider"

迁移数据库

此包包含两个迁移，向数据库添加两个新表：short_urls和short_url_visits。要运行这些迁移，只需运行以下命令

php artisan migrate

使用方法

构建短网址

快速入门

创建短网址的最快方式是使用以下代码片段。->make()方法返回一个ShortURL模型，您可以从其中获取缩短后的URL。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->make();
$shortURL = $shortURLObject->default_short_url;

自定义键

默认情况下，生成的缩短URL将包含一个随机键。键的长度将定义为配置文件中指定的长度（默认为5个字符）。例如：如果URL是https://webapp.com/short/abc123，则键为abc123。

您可能希望为该URL定义一个自定义键，使其比随机生成的键更有意义。您可以使用->urlKey()方法完成此操作。示例

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->urlKey('custom-key')->make();
$shortURL = $shortURLObject->default_short_url;

// Short URL: https://webapp.com/short/custom-key

注意：所有URL键都是唯一的，因此您不能使用已存在于数据库中的键为另一个缩短URL。

跟踪访客

您可能想跟踪使用缩短URL的访客的一些数据。这可以用于分析。默认情况下，跟踪已启用，所有可用的跟踪字段也都已启用。您可以在配置文件中切换跟踪的不同部分的默认选项。有关如何自定义默认跟踪行为，请参阅自定义部分。

注意：即使跟踪选项（如 track_ip_address）对短网址已启用，除非启用了 track_visits 选项，否则不会记录。如果您想在不单独设置每个选项的情况下启用/禁用短网址的跟踪，这将非常有用。

启用跟踪

如果您希望在创建缩短网址时覆盖跟踪是否启用的设置，可以使用 ->trackVisits() 方法。此方法接受一个布尔值，但如果没有传递参数，则默认为 true。

以下示例显示了如何为网址启用跟踪并覆盖配置变量。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits()->make();

以下示例显示了如何禁用网址的跟踪并覆盖默认配置变量。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits(false)->make();

跟踪IP地址

如果您希望在创建缩短网址时覆盖 IP 地址跟踪是否启用的设置，可以使用 ->trackIPAddress() 方法。此方法接受一个布尔值，但如果没有传递参数，则默认为 true。

以下示例显示了如何为网址启用 IP 地址跟踪并覆盖默认配置变量。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits()->trackIPAddress()->make();

跟踪浏览器及版本

如果您希望在创建缩短网址时覆盖浏览器名称和浏览器版本跟踪是否启用的设置，可以使用 ->trackBrowser() 和 ->trackBrowserVersion() 方法。此方法接受一个布尔值，但如果没有传递参数，则默认为 true。

以下示例显示了如何为网址启用浏览器名称跟踪并覆盖默认配置变量。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits()->trackBrowser()->make();

以下示例显示了如何为网址启用浏览器版本跟踪并覆盖默认配置变量。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits()->trackBrowserVersion()->make();

跟踪操作系统及版本

如果您希望在创建缩短网址时覆盖操作系统名称和操作系统版本跟踪是否启用的设置，可以使用 ->trackOperatingSystem() 和 ->trackOperatingSystemVersion() 方法。这些方法接受一个布尔值，但如果没有传递参数，则默认为 true。

以下示例显示了如何为网址启用操作系统名称跟踪并覆盖默认配置变量。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits()->trackOperatingSystem()->make();

以下示例显示了如何为网址启用操作系统版本跟踪并覆盖默认配置变量。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits()->trackOperatingSystemVersion()->make();

跟踪设备类型

如果您希望在创建缩短网址时覆盖设备类型跟踪是否启用的设置，可以使用 ->trackDeviceType() 方法。此方法接受一个布尔值，但如果没有传递参数，则默认为 true。

以下示例显示了如何为网址启用设备类型跟踪并覆盖默认配置变量。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits()->trackDeviceType()->make();

跟踪来源URL

如果您希望在创建缩短网址时覆盖引用 URL 跟踪是否启用的设置，可以使用 ->trackRefererURL() 方法。此方法接受一个布尔值，但如果没有传递参数，则默认为 true。

以下示例显示了如何为网址启用引用 URL 跟踪并覆盖默认配置变量。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->trackVisits()->trackRefererURL()->make();

单次使用

默认情况下，所有缩短网址都可以访问，直到您停止它们。但是，您可能只想允许访问一次缩短网址。然后任何在网址已被查看后访问网址的访客将收到 HTTP 404 错误。

要创建一次性使用的缩短网址，可以使用 ->singleUse() 方法。

以下示例显示了如何创建一次性使用的缩短网址。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('https://destination.com')->singleUse()->make();

强制HTTPS

在构建缩短网址时，您可能希望强制将访客重定向到目标网址的 HTTPS 版本。如果您允许您的网络应用用户创建自己的缩短网址，这尤其有用。

要强制使用 HTTPS，可以在构建缩短网址时使用 ->secure() 方法。

以下示例显示了如何创建安全的缩短网址。

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('http://destination.com')->secure()->make();

// Destination URL: https://destination.com

转发查询参数

在构建短网址时，您可能希望将请求中发送的查询参数转发到目标网址。默认情况下，此功能是禁用的，但可以通过将 forward_query_params 配置选项设置为 true 来启用。

或者，您也可以在构建短网址时使用 ->forwardQueryParams() 方法，如下例所示

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('http://destination.com?param1=test')->forwardQueryParams()->make();

根据上述示例，假设原始短网址的 destination_url 为 https://destination.com，对 https://webapp.com/short/xxx?param1=abc¶m2=def 进行请求将重定向到 https://destination.com?param1=test¶m2=def

重定向状态码

默认情况下，所有短网址都是使用 301 HTTP 状态码进行重定向。但是，可以在使用 ->redirectStatusCode() 方法构建短网址时覆盖此设置。

以下示例显示了如何创建具有 302 重定向 HTTP 状态码的短网址

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->destinationUrl('http://destination.com')->redirectStatusCode(302)->make();

激活和停用时间

默认情况下，您创建的所有短网址都处于活动状态，直到您删除它们。但是，在创建网址时，您可以设置网址的激活和停用时间。

这样做对于营销活动很有用。例如，您可能希望在特定日期启动营销活动的新的网址，并在营销活动结束时自动停用该网址。

以下示例显示了如何创建一个从明天这个时候开始生效的短网址

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->activateAt(\Carbon\Carbon::now()->addDay())->make();

以下示例显示了如何创建一个从明天这个时候开始生效并随后停用的短网址

$builder = new \AshAllenDesign\ShortURL\Classes\Builder();

$shortURLObject = $builder->activateAt(\Carbon\Carbon::now()->addDay())
                          ->deactivateAt(\Carbon\Carbon::now()->addDays(2))
                          ->make();

外观

如果您喜欢使用 Laravel 的外观，可以选择使用提供的 ShortURL 外观，而不是手动实例化 Builder 类。

以下示例显示了如何使用外观创建短网址

<?php

namespace App\Http\Controllers;

use ShortURL;

class Controller
{
    public function index()
    {
        $shortURLObject = ShortURL::destinationUrl('https://destination.com')->make();
        ...
    }
}

条件

Builder 类使用了 Illuminate\Support\Traits\Conditionable 特性，因此在构建短网址时可以使用 when 和 unless 方法。

例如，让我们看看这个在构建短网址时使用 if 的代码块

use AshAllenDesign\ShortURL\Classes\Builder;
 
$shortURLObject = (new Builder())
    ->destinationUrl('https://destination.com');

if ($request->date('activation')) {
    $builder = $builder->activateAt($request->date('activation'));
};

$shortURLObject = $builder->make();)

这可以重写为如下所示的 when

use AshAllenDesign\ShortURL\Classes\Builder;
use Carbon\Carbon;

$shortURLObject = (new Builder())
   ->destinationUrl('https://destination.com')
   ->when(
       $request->date('activation'),
       function (Builder $builder, Carbon $activateDate): Builder  {
           return $builder->activateAt($activateDate);
       },
   )
   ->make();

使用短网址

默认路由和控制器

默认情况下，创建的短网址使用包的路线和控制器。这些路由采用以下结构： https://webapp.com/short/{urlKey}。此路由使用位于 \AshAllenDesign\ShortURL\Controllers\ShortURLController 的单次使用控制器。

自定义路由

您可能希望为短网址使用不同于默认网址的不同路由结构。例如，您可能想使用 https://webapp.com/s/{urlKey} 或 https://webapp.com/{urlKey}。您可以将其自定义以适应您项目的需求。

要使用自定义路由，您只需要在项目中添加一个指向 ShortURLController 的 web 路由，并使用 {shortURLKey} 字段。

以下示例显示了如何向您的 web.php 文件添加自定义路由以使用短网址

Route::get('/custom/{shortURLKey}', '\AshAllenDesign\ShortURL\Controllers\ShortURLController');

注意：如果您使用自定义路由，您可能希望禁用应用提供的默认路由。有关详细信息，请参阅下面的自定义部分。

跟踪

如果启用了短网址的跟踪，每次访问链接时，数据库中都会创建一个新的 ShortURLVisit 记录。默认情况下，包设置为记录以下访客字段

IP 地址
浏览器名称
浏览器版本
操作系统名称
操作系统版本
引用 URL（访客最初到达的 URL）
设备类型（可以是：desktop/mobile/tablet/robot）

您可以在配置文件中切换这些字段，以仅记录所需的字段。有关如何操作的详细信息，请参阅下面的自定义部分。

自定义

自定义默认路由

自定义默认网址

该包附带了一条您可用于短网址的路由。默认情况下，此路由使用您Laravel应用的app.url配置字段来构建URL。

但是，您可能希望覆盖此设置并使用不同的URL来创建短网址。例如，您可能希望为短网址使用不同的域名。

要覆盖基本URL，您可以设置default_url配置字段。例如，要将基本URL设置为https://example.com，您可以在config/short-url.php文件中将default_url配置如下

'default_url' => 'https://example.com',

要使用您应用程序的app.url配置字段，您可以设置short_url.default_url字段为null。

自定义前缀

该包附带了一条您可用于短网址的路由。默认情况下，此路由为/short/{shortURLKey}。

您可能希望继续使用此默认路由，但将/short/前缀更改为其他名称。为此，您可以在配置中更改prefix字段。

例如，要将默认短网址更改为/s，您可以按如下方式更改配置值

'prefix' => 's',

删除前缀

您也可以完全从默认路由中删除前缀。例如，如果您想通过/{shortUrlKey}访问短网址，则可以将prefix配置值更新为null，如下所示

'prefix' => null,

定义中间件

您可能希望将默认短网址通过您应用的一些中间件运行。为此，您可以通过middleware配置值定义路由应使用的中间件。

例如，如果您有一个MyAwesomeMiddleware类，您可以按如下方式更新您的short-url配置

'middleware' => [
    MyAwesomeMiddleware::class,
],

您也可以使用相同的方法来定义中间件组而不是单个中间件类。例如，如果您想您的默认短网址路由使用web中间件组，您可以按如下方式更新您的配置

'middleware' => [
    'web',
],

请注意，此中间件将仅自动应用于随包提供的默认短网址路由。如果您正在定义自己的路由，您需要自己将此中间件应用于路由。

禁用默认路由

如果您已在项目中添加了您自己的自定义路由，您可能想要阻止包提供的默认路由。您可以在配置中设置以下值来完成此操作

'disable_default_route' => true,

如果默认路由被禁用，任何访问/short/{shortURLKey}路由的访客将收到HTTP 404错误。

您可能想要手动防止路由自动注册，并在自己的路由文件中手动注册它。为此，您可以在路由文件（例如web.php）中添加以下代码

\AshAllenDesign\ShortURL\Facades\ShortURL::routes();

默认URL键长度

在构建缩短URL时，您可以选择定义自己的URL密钥或随机生成一个。如果随机生成，其最小长度由配置决定。

出于性能原因，已强制执行最小密钥长度为3。

例如，要创建一个10个字符长度的缩短URL，您可以在配置中设置以下内容

'key_length' => 10,

默认情况下，创建的缩短URL密钥长度为5。

请注意，您在配置中指定的密钥长度仅为期望长度。它作为最小长度而不是固定长度。例如，如果配置中的key_length设置为3，并且有一个尚未使用的唯一3个字符长度的密钥，则创建的密钥长度将为3个字符。然而，如果所有可能的3个字符长度的密钥都已占用，则创建的密钥长度将为4个字符。

使用Hashids库来辅助创建URL密钥。

跟踪访问

默认情况下，该包启用对构建的每个URL上所有可用字段的跟踪。但是，这可以在配置文件中切换。

默认跟踪

要默认禁用所有未来生成的短链接的跟踪，请在配置中设置以下内容

'tracking'   => [
        'default_enabled' => true,
        ...
]

注意：默认禁用跟踪不会禁用已经存在的任何缩短链接的跟踪。它只会应用于配置更新后创建的所有缩短链接。

跟踪字段

您可以通过在配置中更改它们来切换可以跟踪的每个字段的默认选项。然后可以在创建时覆盖每个短链接的这些选项，如跟踪访客部分所示。

例如，下面的代码片段显示了如何记录除了访客的IP地址之外的所有字段

'tracking'   => [
        ...
        'fields' => [
            'ip_address'               => false,
            'operating_system'         => true,
            'operating_system_version' => true,
            'browser'                  => true,
            'browser_version'          => true,
            'referer_url'              => true,
            'device_type'              => true,
        ],
    ],

配置验证

默认情况下，short-url.php配置文件中定义的值未经验证。然而，库中包含一个验证器，可以用来确保您的值安全使用。要启用配置验证，您可以在配置中设置以下选项

'validate_config' => true,

辅助方法

访问

ShortURL模型包括一个关系（您可以像使用任何其他Laravel模型关系一样使用它），用于获取缩短链接的访问量。

要使用关系获取访问量，请使用->visits或->visits()。以下示例代码片段显示了如何操作

$shortURL = \AshAllenDesign\ShortURL\Models\ShortURL::find(1);
$visits = $shortURL->visits;

按URL键查找

要找到与给定缩短链接密钥对应的ShortURL模型，您可以使用->findByKey()方法。

例如，要找到具有密钥abc123的缩短链接的ShortURL模型，您可以使用以下代码

$shortURL = \AshAllenDesign\ShortURL\Models\ShortURL::findByKey('abc123');

按目标URL查找

要找到重定向到给定目标URL的ShortURL模型，您可以使用->findByDestinationURL()方法。

例如，要找到所有重定向到https://destination.com的缩短链接的ShortURL模型，您可以使用以下代码

$shortURLs = \AshAllenDesign\ShortURL\Models\ShortURL::findByDestinationURL('https://destination.com');

跟踪启用

要检查短链接是否启用了跟踪，您可以使用->trackingEnabled()方法。如果启用了跟踪，它将返回true，如果没有，则返回false。

以下示例显示了如何检查短链接是否启用了跟踪

$shortURL = \AshAllenDesign\ShortURL\Models\ShortURL::first();
$shortURL->trackingEnabled();

跟踪字段

要检查短链接启用了哪些跟踪字段，您可以使用->trackingFields()方法。它将返回一个数组，包含当前启用的每个跟踪字段的名称。

注意：即使跟踪选项（如track_ip_address）为短链接启用并返回，除非启用了track_visits选项，否则它们不会被记录。如果您想启用/禁用短链接的跟踪，而不需要分别设置每个选项，这可能会很有用。

以下示例显示了如何获取短链接的所有跟踪启用字段的数组

$shortURL = \AshAllenDesign\ShortURL\Models\ShortURL::first();
$shortURL->trackingFields();

模型工厂

该软件包包含用于测试目的的模型工厂，这在生成多态关系时非常有用。《ShortURL》模型工厂还包括您可能需要时使用的额外状态，例如deactivated和inactive。

use AshAllenDesign\ShortURL\Models\ShortURL;

$shortUrl = ShortURL::factory()->create();

// URL is deactivated
$deactivatedShortUrl = ShortURL::factory()->deactivated()->create();

// URL is neither activated nor deactivated
$inactiveShortURL = ShortURL::factory()->inactive()->create();

如果您正在使用自己的自定义模型工厂，您可以通过更新factories配置字段来定义ShortURL和ShortURLVisit模型应使用的工厂。

'factories' => [
    \AshAllenDesign\ShortURL\Models\ShortURL::class => \AshAllenDesign\ShortURL\Models\Factories\ShortURLFactory::class,
    \AshAllenDesign\ShortURL\Models\ShortURLVisit::class => \AshAllenDesign\ShortURL\Models\Factories\ShortURLVisitFactory::class
],

事件

短网址访问

每次访问短链接时，都会触发以下事件，您可以在其中监听

AshAllenDesign\ShortURL\Events\ShortURLVisited

如果您使用301 HTTP状态代码重定向用户，如果访客之前已经访问过此短链接，则此事件可能不会被触发。这是由于大多数浏览器会将目标URL缓存为'永久重定向'，并且实际上不会首先访问短链接。

为了获得更好的结果，请使用302 HTTP状态代码，因为大多数浏览器会将短链接视为'临时重定向'。这意味着短链接将在浏览器中访问，并且在重定向到目标URL之前，事件将按预期分派。

测试

要运行软件包的单元测试，请运行以下命令

vendor/bin/phpunit

安全

如果您发现任何与安全相关的问题，请直接通过mail@ashallendesign.co.uk联系我，以报告问题。

贡献

如果您想对包进行任何修改或改进，请随时提交一个拉取请求。

注意：将很快添加贡献指南。

致谢

变更日志

查看变更日志以获取有关最新更改的更多信息。

升级

查看升级指南以获取有关如何更新此库到新版本的更多信息。

许可

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

chapdel / uri

维护者

详情

README

目录

概述

安装

要求

安装包

发布配置和迁移

迁移数据库

使用方法

构建短网址

快速入门

自定义键

跟踪访客

启用跟踪

跟踪IP地址

跟踪浏览器及版本

跟踪操作系统及版本

跟踪设备类型

跟踪来源URL

单次使用

强制HTTPS

转发查询参数

重定向状态码

激活和停用时间

外观

条件

使用短网址

默认路由和控制器

自定义路由

跟踪

自定义

自定义默认路由

自定义默认网址

自定义前缀

删除前缀

定义中间件

禁用默认路由

默认URL键长度

跟踪访问

默认跟踪

跟踪字段

配置验证

辅助方法

访问

按URL键查找

按目标URL查找

跟踪启用

跟踪字段

模型工厂

事件

短网址访问

测试

安全

贡献

致谢

变更日志

升级

许可