Skip to content

Commit

Permalink
Documentation
Browse files Browse the repository at this point in the history
PavlosIsaris committed Oct 10, 2024
1 parent 8dc3c19 commit 1f18cd5
Showing 4 changed files with 75 additions and 18 deletions.
72 changes: 62 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -86,28 +86,69 @@ php artisan vendor:publish \

The configuration file will be published to `config/cookies_consent.php`.

### Explanation of the configuration file

In the config file, you can change the cookie categories of your application, set the required and pre-selected
categories, as well as add new categories.

This is the contents of the published config file:

```bash
return [
/**
* This prefix will be applied when setting and getting all cookies.
* If not set, the cookies will not be prefixed.
* If set, a good strategy is to also add a trailing underscore "_", that will be added between the field value, and each cookie.
* For example, if `cookie_prefix` is set to `my_app_`, then the targeting cookie will have a value of `my_app_cookies_consent_targeting`.
* When using this plugin for multiple apps, it is a good strategy to set a prefix that is relevant to the app
* (for example "my_app_", in order for the cookies not to be mingled when running locally.
*/
'cookie_prefix' => '',
'display_floating_button' => true, // Set to false to display the footer link instead
'use_separate_page' => false, // Set to true to use a separate page for cookies explanation
/*
|--------------------------------------------------------------------------
| Editor
|--------------------------------------------------------------------------
|
| Choose your preferred cookies to be shown. You can add more cookies as desired.
| If, for example you add another cookie with the name "marketing", then you should also
| publish the translation files and add a "cookie_marketing" key in the translation file,
| since the plugin will try to display the cookie name by this convention.
|
| Built-in: "strictly_necessary"
|
*/
'cookies' => [
'strictly_necessary',
'targeting',
'performance',
'functionality'
'strictly_necessary' => [
[
'name' => 'cookieConsent',
'description' => 'This cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.',
'duration' => '2 years',
'policy_external_link' => null,
],
[
'name' => 'XSRF-TOKEN',
'description' => 'This cookie is set by Laravel to prevent Cross-Site Request Forgery (CSRF) attacks.',
'duration' => '2 hours',
'policy_external_link' => null,
],
[
'name' => 'laravel_session',
'description' => 'This cookie is set by Laravel to identify a session instance for the user.',
'duration' => '2 hours',
'policy_external_link' => null,
],
],
],
'enabled' => [
'strictly_necessary',
'targeting',
'performance',
'functionality'
'strictly_necessary',
],
'required' => ['strictly_necessary'],
'cookie_lifetime' => 365 * 10,
/*
* Set the cookie duration in days. Default is 365 days.
*/
'cookie_lifetime' => 365,
];
```
@@ -118,6 +159,17 @@ cookie.
For example, if `cookie_prefix` is set to `my_app_`, then the targeting cookie will have a value
of `my_app_cookies_consent_targeting`.
The `display_floating_button` field is optional and, if set to `true`, will display a floating button on the bottom right corner of the page.
If set to `false`, then you will need to add a relevant link in your footer, in order to show the cookies preferences page:
```html
<a href="#" onclick="toggleCookieBanner()">Cookies Preferences</a>
```
The `use_separate_page` field is optional and, if set to `true`, will display the cookies preferences in a separate page.
You can add as many cookie categories as you like, simply by adding values to the `cookies` array.
If you want to remove a cookie category, simply remove it from the array.
@@ -134,7 +186,7 @@ custom [Laravel View Component](https://laravel.com/docs/9.x/blade#components) i
This will render the following cookies consent that, will look very much like this one.
![dialog](https://github.com/scify/laravel-cookies-consent/blob/9c0ddafe15ad8118ab07979b72094799417f93db/images/dialog.png)
![dialog](readme-images/img2.png)
You can then use this component in order to display the cookies consent window, wherever you'd like.
4 changes: 2 additions & 2 deletions config/cookies_consent.php
Original file line number Diff line number Diff line change
@@ -10,8 +10,8 @@
* (for example "my_app_", in order for the cookies not to be mingled when running locally.
*/
'cookie_prefix' => '',
'display_floating_button' => false, // Set to false to display the footer link instead
'use_separate_page' => true, // Set to true to use a separate page for cookies explanation
'display_floating_button' => true, // Set to false to display the footer link instead
'use_separate_page' => false, // Set to true to use a separate page for cookies explanation
/*
|--------------------------------------------------------------------------
| Editor
17 changes: 11 additions & 6 deletions how-to-upgrade-to-v2.md
Original file line number Diff line number Diff line change
@@ -53,18 +53,23 @@ composer update scify/laravel-cookies-consent
1. Publish the new configuration file by running the following command:

```bash
php artisan vendor:publish --tag=cookies-consent-config
php artisan vendor:publish --tag=cookies-consent-config --force
```

2. Compare the new configuration file (`config/cookies-consent.php`) with your old configuration file. You should copy
**CAUTION**: The `--force` flag is necessary in order to overwrite the existing configuration file.

2. Go over the "Explanation of the configuration file" in the [README.md](README.md) file, in order to understand the new structure
of the configuration file.

3. Compare the new configuration file (`config/cookies-consent.php`) with your old configuration file. You should copy
the values from your old configuration file to the new one. Most importantly, you should migrate the `cookies` array
from the old configuration file to the new one, which contains the cookies that your website uses.

3. Make sure that the new configuration file is correct and that it contains all the necessary information about the
4. Make sure that the new configuration file is correct and that it contains all the necessary information about the
cookies and the cookie categories that your website uses.

4. Make sure that the `cookies` array in the new configuration file is structured correctly. The `cookies` array should
5. Make sure that the `cookies` array in the new configuration file is structured correctly. The `cookies` array should
contain the cookies that your website uses, grouped by category.

5. Make sure that the `cookies` array in the new configuration file contains the necessary information about each cookie
(e.g. name, description, duration, etc.).
6. Make sure that the `cookies` array in the new configuration file contains the necessary information about each cookie
(e.g. name, description, duration, etc.).
Binary file removed images/dialog.png
Binary file not shown.

0 comments on commit 1f18cd5

Please sign in to comment.