README

关于插件

根据GDPR法规，每个平台都必须允许用户决定他们希望允许哪些cookie类别，如果某个cookie类别不被允许，则应用程序不应使用与该cookie相关的功能。

此插件通过一个简单的cookie同意窗口提供，用户可以通过此窗口指定他们希望允许的cookie。

用户提交后，页面将重新加载，相关cookie将在浏览器中设置，并可以在前端使用。

功能

可定制的cookie类别
可定制的弹出视图和样式
可定制的显示/隐藏“阅读更多”链接
可定制的翻译（已包含6种语言）

安装

您可以通过composer安装此包

composer require scify/laravel-cookies-consent

请确保手动发布样式文件，运行以下命令：

php artisan vendor:publish \
--provider="SciFY\LaravelCookiesConsent\LaravelCookiesConsentServiceProvider" \
--tag="cookies-consent-assets"

这样做，资产文件将被复制到public/vendor/cookies_consent。

然后，您可以选择将public/vendor/cookies_consent/css/style.css文件添加到git（特别是如果您想先编辑它），或者将其添加到.gitignore，并确保在预发布/生产服务器上也要运行此命令。

接下来，您需要发布配置文件

php artisan vendor:publish \
--provider="SciFY\LaravelCookiesConsent\LaravelCookiesConsentServiceProvider" \
--tag="cookies-consent-config"

配置文件将发布到config/cookies_consent.php。

在配置文件中，您可以更改应用程序的cookie类别，设置必需和预选类别，以及添加新类别。

这是已发布配置文件的内容

return [
    'cookie_prefix' => '',
    'cookies' => [
        'strictly_necessary', 
        'targeting', 
        'performance', 
        'functionality'
    ],
    'enabled' => [
        'strictly_necessary', 
        'targeting', 
        'performance', 
        'functionality'
    ],
    'required' => ['strictly_necessary'],
    'cookie_lifetime' => 365 * 10,
];

cookie_prefix是可选的，如果设置，将应用于每个cookie。

如果设置，一个好的策略是在字段值和每个cookie之间添加一个尾随下划线 "_"。

例如，如果cookie_prefix设置为my_app_，则目标cookie的值将为my_app_cookies_consent_targeting。您可以通过简单地向cookies数组添加值来添加任意数量的cookie类别。

如果您想删除一个cookie类别，只需从数组中删除它。

您可以使用enabled数组设置预选的cookie类别，以及使用required数组设置用户无法取消选择的cookie。

如果您想更改cookie存储的时间长度，请编辑cookie_lifetime变量。

用法

当插件安装时，会自动注册一个名为laravel-cookies-consent的自定义Laravel视图组件。

这将渲染以下cookie同意，看起来将非常像这个。

然后您可以使用此组件在您想要显示cookie同意窗口的地方显示它。

通常，一个好的策略是将组件放在关闭<body>标签之前

<body>
    ...
    ...
    ...
    <x-laravel-cookies-consent></x-laravel-cookies-consent>
</body>

之后，您可以使用$_COOKIE全局对象来检查适当的cookie。

现在您可以在Blade文件中使用此对象，如下所示

$_COOKIE[config('cookies_consent.cookie_prefix') . {{ COOKIE_NAME }}]

例如，一个只想在用户同意《targeting》cookie类别的条件下加载Google Analytics脚本的程序，可能会执行以下操作：

google-analytics.blade.php

<!-- Check the 'targeting' cookie: -->
@if(isset($_COOKIE[config('cookies_consent.cookie_prefix') 
. 'cookies_consent_targeting']) && config('app.google_analytics_id'))
    
    <!-- Google Analytics -->
    <script defer async>
        (function (i, s, o, g, r, a, m) {
            i['GoogleAnalyticsObject'] = r;
            i[r] = i[r] || function () {
                (i[r].q = i[r].q || []).push(arguments)
            }, i[r].l = 1 * new Date();
            a = s.createElement(o),
                m = s.getElementsByTagName(o)[0];
            a.async = 1;
            a.src = g;
            m.parentNode.insertBefore(a, m)
        })(window, document, 'script', 'https://#/analytics.js', 'ga');

        window.ga('create', '{{ config('app.google_analytics_id') }}', 'auto');
        window.ga('set', 'anonymizeIp', true);
        window.ga('send', 'pageview');
    </script>
@endif

在这个例子中，我们检查了《$_COOKIE[config('cookies_consent.cookie_prefix') . 'cookies_consent_targeting']》键是否存在。

自定义

自定义组件文本

如果您想修改cookie对话框中显示的文本，可以使用以下命令发布语言资源文件：

php artisan vendor:publish \
--provider="SciFY\LaravelCookiesConsent\LaravelCookiesConsentServiceProvider" \
--tag="cookies-consent-translations"

这将把此文件发布到《resources/lang/vendor/cookies_consent/{{lang}}/messages.php》。

该插件附带6种内置语言。您可以更改特定语言的翻译，或自行添加其他语言。

自定义“阅读更多”链接

在cookie对话框中，还有一个可选的“阅读更多”链接。由于通常每种语言都会有一个不同的链接，因此该链接在语言翻译文件中指定。

示例（文件《lang/vendor/cookies_consent/en/messages.php》）

return [
    ...
    'read_more_link' => '',
    ...
];

如果链接留空（默认状态），则不会显示。

自定义组件内容

如果您需要完全控制cookie对话框的内容，您可以发布该软件包的视图

php artisan vendor:publish \
--provider="SciFY\LaravelCookiesConsent\LaravelCookiesConsentServiceProvider" \
--tag="cookies-consent-components"

这将把《resources/views/components/laravel-cookies-consent》视图文件复制到《resources/views/components/vendor/cookies_consent》目录。

开发

为了本地运行该软件包，您应该使用一个本地Laravel应用程序，并在其中安装它。

请确保Laravel应用程序的《composer.json》文件有如下条目：


"require": {
    "scify/laravel-cookies-consent": "@dev",
}
...
...
"repositories": [
        {
            "type": "path",
            "url": "../path/to/laravel-cookies-consent/",
            "options": {
                "symlink": true
            }
        }
    ]

这将告诉Composer该软件包的代码是“"@dev"”版本，并且它位于指定的路径。

然后运行

composer update scify/laravel-cookies-consent --prefer-source

以获取本地软件包。

测试

此项目使用《Pest》进行测试。要执行测试套件，请运行

composer test

常见问题解答

问题：这个插件免费使用吗？

答案：是的。此插件完全免费，并作为一个《开源项目》开发。

问题：cookie的有效期是多久？

答案：有效期以天为单位设置在《config/cookies_consent.php》文件中。要发布此文件，请运行

php artisan vendor:publish \
--provider="SciFY\LaravelCookiesConsent\LaravelCookiesConsentServiceProvider" \
--tag="cookies-consent-config"

配置文件将发布到config/cookies_consent.php。

然后，编辑《cookie_lifetime》字段（以天为单位）。

问题：cookie同意窗口会每次都显示吗？

答案：不会。一旦用户点击“接受全部”、“接受选择”或“拒绝全部”中的一个选项，选择将被存储在另一个cookie中，并且窗口不会再次弹出，直到该cookie过期或被删除。

问题：该插件支持哪些语言？

答案：该插件有6种内置语言：英语、希腊语、西班牙语、德语、意大利语和瑞典语。如果您想添加语言，可以通过运行以下命令发布翻译：

php artisan vendor:publish \
--provider="SciFY\LaravelCookiesConsent\LaravelCookiesConsentServiceProvider" \
--tag="cookies-consent-translations"

并添加/更改您自己的翻译。如果您添加了新语言，请考虑也提交一个《pull request》，以便将该语言包含在插件中。

问题：该插件是否与所有Laravel版本兼容？

答案：我们已经测试了该插件与Laravel 7、8和9的兼容性。插件的简洁性允许它与任何Laravel版本一起工作，但如果您尝试使用除已测试版本之外的版本，并且它无法工作，请在《GitHub》上提交问题。

问题：如果后来安装了新的cookie类别，如何强制插件“重置”并再次显示？

答案：最简单的方法是发布配置文件，并更改 cookie_prefix 字段。这将强制插件再次显示。

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关一般详细信息，请参阅贡献指南。

PHP 代码风格 - Laravel Pint

此应用程序使用 Laravel Pint 来执行代码风格检查。

要运行样式化工具，请运行

./vendor/bin/pint --test -v # the --test will not do any changes, it will just output the changes needed

./vendor/bin/pint -v # this command will actually perform the code style changes

发布新版本

提交更改后，创建一个新的 git 标签

git tag -a vx.y.z -m "This is a nice tag name"

然后，推送标签

git push origin vx.y.z

然后，在 GitHub 发布页面上创建一个新的发布版本 * 并关联您刚刚创建的标签。*

就这样！Packagist 将自动更新。

此外，.github/workflows/update-changelog.yml GitHub 动作将运行，并将更新 CHANGELOG.md 文件。

请确保之后运行 git pull 以获取更新。

鸣谢

SciFY 开发团队

许可证

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

scify / laravel-cookies-consent

维护者

详细信息