README

该软件包允许您轻松创建指向命名路由的“签名”URL。这些URL在查询字符串中附加了一个“签名”哈希值，允许 Spiral 框架验证自创建以来该URL是否已被修改。

签名URL对于公开访问但需要防止URL篡改的路由特别有用。

要求

请确保您的服务器已配置以下PHP版本和扩展

• PHP 8.1+
• Spiral 框架 3.0+

安装

您可以通过composer安装该软件包

composer require spiral-packages/signed-urls

在安装软件包后，您需要从软件包中注册引导加载器。

protected const LOAD = [
    // ...
    \Spiral\SignedUrls\Bootloader\SignedUrlsBootloader::class,
];

注意如果您使用spiral-packages/discoverer，您无需自行注册引导加载器。

指定环境变量

# Secret key for generating the HMAC variant of the message digest.
# REQUIRED
SIGNED_URLS_KEY=secret

# Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
# OPTIONAL (sha256 by default)
SIGNED_URLS_ALGO=sha256

用法

例如，您可以使用签名URL来实现一个公开的“电子邮件验证”链接，该链接将发送给您的客户

class VerifyEmailNotification 
{
    public function __construct(
        private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls
        private readonly  \Spiral\Views\ViewInterface $view
    ) {}
    
    public function buildView(): string
    {
        return $this->view->render([
            'signed_url' => $this->urls->signedRoute(
                route: 'verify-email',
                parameters: ['user_id' => 100]
            )
        ]);
    }
}

如果您希望生成一个在指定时间后过期的临时签名路由URL，您可以在方法中传递过期日期。当 Spiral 框架验证临时签名路由URL时，它将确保编码到签名URL中的过期时间戳尚未过期

class VerifyEmailNotification 
{
    public function __construct(
        private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls
        private readonly  \Spiral\Views\ViewInterface $view
    ) {}
    
    public function buildView(): string
    {
        return $this->view->render([
            'signed_url' => $this->urls->signedRoute(
                route: 'verify-email',
                parameters: ['user_id' => 100],
                expiration: new \DateTime('...')
            )
        ]);
    }
}

您不仅可以对路由进行签名，还可以对URL进行签名

class VerifyEmailNotification 
{
    public function __construct(
        private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls
        private readonly  \Spiral\Views\ViewInterface $view
    ) {}
    
    public function buildView(): string
    {
        return $this->view->render([
            'signed_url' => $this->urls->signedUrl(
                uri: new \Nyholm\Psr7\Uri('http://site.com/verify-email/?user_id=1'),
                expiration: new \DateTime('...')
            )
        ]);
    }
}

验证签名URL

要验证URL是否具有有效的签名，应调用 hasValidSignature 方法

class EmailVerificationController
{
    public function __construct(
        private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls
    ) {}
    
    
    public function verify(\Psr\Http\Message\RequestInterface $request): string
    {
        if (!$this->urls->hasValidSignature($request->getUri())) {
            return 'ERROR';
        }
        
        return 'OK';
    }
}

您可以将 Spiral\SignedUrls\Middleware\ValidateSignature 中间件分配给路由，而不是使用传入的请求实例来验证签名URL

class EmailVerificationController
{
    public function __construct(
        private readonly \Spiral\SignedUrls\UrlGeneratorInterface $urls
    ) {}
    
    #[\Spiral\Router\Annotation\Route(
        name: 'verify-email',
        route: '...',
        middleware: \Spiral\SignedUrls\Middleware\ValidateSignature::class
    )]
    public function verify(\Psr\Http\Message\RequestInterface $request): string
    {
        return 'OK';
    }
}

测试

composer test

更新日志

请参阅 更新日志 了解最近更改的详细信息。

贡献

请参阅 贡献指南 了解详细信息。

安全漏洞

请审查 我们的安全策略 了解如何报告安全漏洞。

鸣谢

• Pavel Buchnev
• 所有贡献者

许可

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