ashallendesign/short-url

一个用于为您的Web应用程序创建短网址的Laravel包。

维护者

详细信息

github.com/ash-jc-allen/short-url

主页

源代码

问题

资助包维护！
ash-jc-allen

安装数: 829 113

依赖项: 0

建议者: 0

安全: 0

星星: 1 249

关注者: 18

分支: 158

公开问题: 2

v8.1.2 2024-09-17 09:48 UTC

Requires

Requires (Dev)

MIT f9094f907e11e9c4f65de6a6c759583190e4cf3e

  • Ash Allen <mail.woop@ashallendesign.co.uk>

laravelURL-Shortenerlaravel-packageashallendesignshort-urls

This package is auto-updated.

Last update: 2024-09-17 09:48:58 UTC

README

Latest Version on Packagist Total Downloads PHP from Packagist GitHub license

目录

概述

一个可用于将短网址添加到现有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。

use AshAllenDesign\ShortURL\Classes\Builder;

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

自定义键

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

$shortURLObject = app(Builder::class)->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）为缩短URL启用，除非启用了track_visits选项，否则它们不会被记录。如果您想在不单独设置每个选项的情况下启用/禁用缩短URL的跟踪，这可能很有用。

启用跟踪

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

$shortURLObject = app(Builder::class)->destinationUrl('https://destination.com')->trackVisits(false)->make();
跟踪IP地址

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

$shortURLObject = app(Builder::class)->destinationUrl('https://destination.com')->trackVisits()->trackIPAddress()->make();
跟踪浏览器及版本

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

$shortURLObject = app(Builder::class)->destinationUrl('https://destination.com')->trackVisits()->trackBrowserVersion()->make();
跟踪操作系统及版本

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

$shortURLObject = app(Builder::class)->destinationUrl('https://destination.com')->trackVisits()->trackOperatingSystemVersion()->make();
跟踪设备类型

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

$shortURLObject = app(Builder::class)->destinationUrl('https://destination.com')->trackVisits()->trackDeviceType()->make();
跟踪来源URL

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

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

use AshAllenDesign\ShortURL\Classes\Builder;

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

自定义短URL字段

有时您可能想在ShortURL模型中添加自己的自定义字段并将它们存储在数据库中。例如，您可能想要将缩短URL与租户、组织、用户等关联。

为此，您可以在构建缩短URL时使用beforeCreate方法。此方法接受一个闭包，该闭包在保存到您的数据库之前接收AshAllenDesign\ShortURL\Models\ShortURL模型实例。

以下示例展示了如何将tenant_id字段添加到AshAllenDesign\ShortURL\Models\ShortURL模型。

use AshAllenDesign\ShortURL\Models\ShortURL;
use AshAllenDesign\ShortURL\Facades\ShortURL as ShortUrlBuilder;

$tenantId = 123;

$shortURL = ShortUrlBuilder::destinationUrl($url)
    ->beforeCreate(function (ShortURL $model): void {
        $model->tenant_id = $tenantId;
    })
    ->make();

请记住，要将自定义字段存储到数据库中，您必须确保这些字段已添加到short_urls表。您可以通过创建一个新的迁移来向表中添加字段，或者通过更新此包提供的迁移来完成此操作。

单次使用

默认情况下，所有缩短的URL都可以访问，直到您将其删除。但是，您可能只想允许访问一次缩短的URL。然后，任何在URL已被查看之后访问此URL的访问者将收到HTTP 404。

要创建一个单次使用的缩短URL，您可以使用->singleUse()方法。

以下示例显示了如何创建一个单次使用的缩短URL。

use AshAllenDesign\ShortURL\Classes\Builder;

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

强制HTTPS

在构建缩短URL时，您可能希望确保访问者被重定向到目标URL的HTTPS版本。如果您允许您的Web应用用户创建自己的缩短URL，这尤其有用。

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

以下示例显示了如何创建一个安全的缩短URL。

use AshAllenDesign\ShortURL\Classes\Builder;

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

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

转发查询参数

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

或者，您也可以在构建缩短URL时使用->forwardQueryParams()方法，如下面的示例所示。

use AshAllenDesign\ShortURL\Classes\Builder;

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

根据上面的示例，假设原始缩短URL的destination_url是https://destination.com，对https://webapp.com/short/xxx?param1=abc¶m2=def的请求将重定向到https://destination.com?param1=test¶m2=def。

重定向状态码

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

以下示例显示了如何创建一个具有重定向HTTP状态码302的缩短URL。

use AshAllenDesign\ShortURL\Classes\Builder;

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

激活和停用时间

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

这样做对于营销活动很有用。例如，您可能希望在特定日期推出营销活动的URL，然后在营销活动结束时自动停用该URL。

以下示例显示了如何创建一个从明天开始激活的缩短URL。

use AshAllenDesign\ShortURL\Classes\Builder;

$shortURLObject = app(Builder::class)->activateAt(\Carbon\Carbon::now()->addDay())->make();

以下示例显示了如何创建一个从明天开始激活并在之后一天停用的缩短URL。

use AshAllenDesign\ShortURL\Classes\Builder;

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

使用自定义种子

默认情况下，包将使用最后插入的缩短URL的ID作为生成缩短URL密钥的种子。在某些情况下，您可能想使用自定义种子。为此，您可以将整数传递给generateKeyUsing方法，如下所示。

use AshAllenDesign\ShortURL\Classes\Builder;

$shortURLObject = app(Builder::class)->destinationUrl('https://destination.com')
   ->generateKeyUsing(12345)
   ->make();

门面

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

以下示例展示了如何使用外观创建缩短URL。

<?php

namespace App\Http\Controllers;

use ShortURL;

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

条件

Builder类使用Illuminate\Support\Traits\Conditionable特质，因此您可以在构建缩短URL时使用when和unless方法。

例如，让我们看看以下使用if构建缩短URL的代码块。

use AshAllenDesign\ShortURL\Classes\Builder;
 
$builder = app(Builder::class)->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 = app(Builder::class)
   ->destinationUrl('https://destination.com')
   ->when(
       $request->date('activation'),
       function (Builder $builder, Carbon $activateDate): Builder  {
           return $builder->activateAt($activateDate);
       },
   )
   ->make();

使用短网址

默认路由和控制器

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

自定义路由

您可能希望为缩短的URL使用不同于默认URL的不同的路由结构。例如，您可能想使用 https://webapp.com/s/{urlKey} 或 https://webapp.com/{urlKey}。您可以根据项目需求自定义此设置。

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

以下示例显示了如何将自定义路由添加到您的 web.php 文件以使用缩短的URL。

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

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

跟踪

如果启用了缩短URL的跟踪，每次点击链接时，数据库中都会创建一个新的 ShortURLVisit 行。默认情况下，该软件包设置为记录以下访客字段：

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

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

自定义

自定义默认路由

自定义默认URL

该软件包提供了一条您可以用于缩短URL的路由。默认情况下，此路由使用 Laravel 应用程序的 app.url 配置字段来构建 URL。

但是，您可能想覆盖此设置并使用不同的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。

自定义前缀

该软件包提供了一条您可以用于缩短URL的路由。默认情况下，此路由是 /short/{shortURLKey}。

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

例如，要将默认缩短URL更改为 /s，您可以更改配置值如下。

'prefix' => 's',
移除前缀

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

'prefix' => null,
定义中间件

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

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

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

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

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

需要注意的是，此中间件将自动应用于随包一起提供的默认短URL路由。如果您正在定义自己的路由，则需要您自己将此中间件应用于路由。

禁用默认路由

如果您已经将自定义路由添加到项目中，可能希望阻止包提供的默认路由。您可以通过在配置中设置以下值来实现此操作：

'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上的所有可用字段。但是，您可以在配置文件中切换此选项。

默认跟踪

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

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

注意：默认禁用跟踪不会禁用任何现有缩短URL的跟踪。它只会应用于配置更新后创建的所有缩短URL。

跟踪字段

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

例如，下面的代码片段显示了如何记录除访客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,

自定义数据库连接

默认情况下，Short URL 将使用您应用程序的默认数据库连接。但是，可能会有时候您想使用不同的连接。例如，您可能正在构建一个多租户应用程序，每个租户使用单独的连接，并且您可能想将短URL存储在中央数据库中。

为此，您可以在 config/short-url.php 文件中使用 connection 配置值设置连接名称，如下所示：

'connection' => 'custom_database_connection_name',

指定密钥生成器

默认情况下，Short URL 使用 AshAllenDesign\ShortURL\Classes\KeyGenerator 类来生成短URL的键。但是，您可能想使用自己的自定义键生成器类。

为此，您可以在 short-url.php 配置文件中定义要使用的类，如下所示：

'url_key_generator' => \AshAllenDesign\ShortURL\Classes\KeyGenerator::class,

您只需确保您的自定义键生成器类实现了 AshAllenDesign\ShortURL\Interfaces\KeyGenerator 接口。

指定用户代理解析器

默认情况下，短网址使用whichbrowser/parser包来解析访客的用户代理头以跟踪访问。然而，您可能想使用自己定制的用户代理解析器。

为此，您可以在 short-url.php 配置文件中定义要使用的类，如下所示：

'user_agent_driver' => \AshAllenDesign\ShortURL\Classes\UserAgent\ParserPhpDriver::class,

您只需确保您的自定义用户代理解析器类实现了AshAllenDesign\ShortURL\Interfaces\UserAgentDriver接口。

指定允许的URL方案

默认情况下，短网址将允许您为以http://或https://开头的任何URL创建短网址。

但是，您可能想更改允许的URL方案列表。例如，这可能是为了限制只能创建https:// URL。或者，这可能是为了允许使用其他方案创建URL，例如mailto://或甚至为您的应用程序创建自定义方案。

要更改允许的URL方案列表，您可以在您的short-url.php配置文件中使用allowed_url_schemes字段定义列表，如下所示

'allowed_url_schemes' => [
    'http://',
    'https://',
    'mailto://',
    'myapp://',
],

辅助方法

访问

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 联系我报告。

贡献

如果您想对该包进行任何更改或改进，请随意提交一个 pull request。

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

致谢

变更日志

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

升级

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

许可

MIT 许可证（MIT）。请参阅 许可文件 了解更多信息。

支持我

如果您觉得这个包很有用，请考虑购买一份 Battle Ready Laravel 以支持我的工作和努力。

每一笔销售对我都有巨大的影响，使我能够花费更多时间在开源项目和教程上。

为了表达深深的感谢，您可以使用代码 BATTLE20 获得书籍 20% 的折扣。

👉 获取您的副本！

Battle Ready Laravel