热门/短网址

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

维护者

详细信息

github.com/waichoonpopular/short-url

主页

源代码

资助包维护！
ash-jc-allen

安装: 18

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 159

1.0.9 2023-10-03 01:01 UTC

Requires

Requires (Dev)

MIT 7d7afd92f688cb407a2eeb72a834854c4658ce4f

  • popular

laravelURL-Shortenerlaravel-packageshort-urls

This package is auto-updated.

Last update: 2024-10-03 03:13:41 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。

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

$shortURLObject = $builder->destinationUrl('https://destination.com')->make();
$shortURL = $shortURLObject->default_short_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的访客的一些数据。这可以用于数据分析。默认情况下，跟踪是启用的，并且所有可用的跟踪字段也都是启用的。您可以在配置文件中切换跟踪的不同部分的默认选项。在自定义部分中进一步阅读，了解如何自定义默认跟踪行为。

注意：即使跟踪选项（如track_ip_address）为缩短URL启用，除非启用了track_visits选项，否则它们不会被记录。如果您想在不单独设置每个选项的情况下启用/禁用缩短URL的跟踪，这可能会很有用。

启用跟踪

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

单次使用

默认情况下，所有缩短URL都可以在您保持它们可用的情况下访问。然而，您可能只想允许访问一次缩短URL。然后任何在URL已被查看之后访问该URL的访客将收到HTTP 404。

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

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

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

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

强制HTTPS

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

为了强制使用HTTPS，当构建缩短的URL时，您可以使用->secure()方法。

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

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

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

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

转发查询参数

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

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

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

$shortURLObject = $builder->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。

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

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

激活和停用时间

默认情况下，您创建的所有缩短的URL在删除之前都是活动的。但是，您可以在创建时为您的URL设置激活和停用时间。

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

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

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

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

以下示例显示了如何创建一个从明天这个时间点开始激活的缩短URL，然后在第二天停用。

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

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

使用自定义种子

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

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

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

门面

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

以下示例显示了如何使用facade创建缩短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方法。

例如，让我们看看这个在构建短URL时使用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();

使用短网址

默认路由和控制器

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

自定义路由

您可能希望为缩短的URL使用不同的路由结构，而不是默认创建的URL。例如，您可能希望使用https://webapp.com/s/{urlKey}或https://webapp.com/{urlKey}。您可以自定义它以满足您项目的需求。

要使用自定义路由，您只需要将一个web路由添加到您的项目中，指向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,

辅助方法

访问

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

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

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

按URL键查找

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

例如，要找到密钥为abc123的缩短URL的ShortURL模型，您可以使用以下代码

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

按目标URL查找

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

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

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

跟踪启用

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

以下示例显示了如何检查是否启用了缩短URL的跟踪

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

跟踪字段

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

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

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

$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();

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

'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