|
1 |
| - |
2 |
| - |
3 | 1 | # Caffeine for Laravel
|
4 | 2 | [](https://gitter.im/GeneaLabs/laravel-caffeine?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
5 | 3 | [](https://travis-ci.org/GeneaLabs/laravel-caffeine)
|
|
8 | 6 | [](https://github.com/GeneaLabs/laravel-caffeine)
|
9 | 7 | [](https://packagist.org/packages/genealabs/laravel-caffeine)
|
10 | 8 |
|
11 |
| -## Goal |
12 |
| -Prevent forms from timing out when submitting them after leaving them on-screen |
13 |
| - for a considerable amount of time. (Laravel defaults to 120 minutes, but that |
14 |
| - is configurable and could be different site-by-site.) |
15 |
| - |
16 |
| -## Implementation |
17 |
| -To achieve this, we are sending a caffeine-drip (a request at regular intervals) |
18 |
| - to keep the session from timing out. |
19 |
| -This is only implemented on pages with a `_token` field, so all other pages will |
20 |
| - time-out as normal. |
21 |
| - |
22 |
| -## Reasoning |
23 |
| -I chose this approach to keep the integrity of site-security, by avoiding the |
24 |
| - following: |
25 |
| -- exposing the CSRF Token on an unsecured endpoint. |
26 |
| -- eliminating CSRF Token validation on specific routes, or even altogether. |
27 |
| -- removing session-timeout on all pages. |
28 |
| - |
29 |
| -## Considerations |
30 |
| -### Routes |
31 |
| -This package adds the routes under `genealabs/laravel-caffeine`. |
32 |
| - |
33 |
| -### Dependencies |
34 |
| -- Your project must be running one of the following Laravel versions: |
35 |
| - - 5.1 (LTS) |
36 |
| - - 5.3 |
37 |
| - - 5.4 |
38 |
| - - 5.5 (LTS) |
39 |
| - - 5.6 |
40 |
| -- PHP 7.1.3 or higher. |
41 |
| - |
42 |
| -## Installation |
43 |
| -For Laravel 5.2, follow the directions here: https://github.com/GeneaLabs/laravel-caffeine/tree/166e2ca08af7cc62a59360f33e03d1cb8478df6a |
44 |
| - |
45 |
| -1. Install the package: |
46 |
| - ```sh |
47 |
| - composer require genealabs/laravel-caffeine |
48 |
| - ``` |
49 |
| - |
50 |
| -2. **This is only required for Laravel 5.4 or below:** |
51 |
| - Add the service provider entry in `config/app.php`: |
52 |
| - ```php |
53 |
| - // 'providers' => [ |
54 |
| - GeneaLabs\LaravelCaffeine\Providers\Service::class, |
55 |
| - // ], |
56 |
| - ``` |
57 |
| - |
58 |
| -3. If you are running 5.5 or above, remove the providers entry from `config/app.php`. |
59 |
| -4. If you have previously registered the middleware, please remove the following |
60 |
| - middleware from `app/Http/Kernel.php`: |
61 |
| - ```php |
62 |
| - // protected $middleware = [ |
63 |
| - GeneaLabs\LaravelCaffeine\Http\Middleware\LaravelCaffeineDripMiddleware::class, |
64 |
| - // ]; |
65 |
| - ``` |
66 |
| - |
67 |
| -## Upgrade Notes |
68 |
| -### 0.6.0 |
69 |
| -This update changes the config file setting names. Please delete the published |
70 |
| -config file `config/genealabs-laravel-caffeine.php` if it exists, and follow the |
71 |
| -configuration instructions below. |
72 |
| - |
73 |
| -## Configuration |
74 |
| -```php |
75 |
| -return [ |
76 |
| - /* |
77 |
| - |-------------------------------------------------------------------------- |
78 |
| - | Drip Interval |
79 |
| - |-------------------------------------------------------------------------- |
80 |
| - | |
81 |
| - | Here you may configure the interval with which Caffeine for Laravel |
82 |
| - | keeps the session alive. By default this is 5 minutes (expressed |
83 |
| - | in milliseconds). This needs to be shorter than your session |
84 |
| - | lifetime value configured set in "config/session.php". |
85 |
| - | |
86 |
| - | Default: 300000 (int) |
87 |
| - | |
88 |
| - */ |
89 |
| - 'drip-interval' => 300000, |
90 |
| - |
91 |
| - /* |
92 |
| - |-------------------------------------------------------------------------- |
93 |
| - | Domain |
94 |
| - |-------------------------------------------------------------------------- |
95 |
| - | |
96 |
| - | You may optionally configure a separate domain that you are running |
97 |
| - | Caffeine for Laravel on. This may be of interest if you have a |
98 |
| - | monitoring service that queries other apps. Setting this to |
99 |
| - | null will use the domain of the current application. |
100 |
| - | |
101 |
| - | Default: null (null|string) |
102 |
| - | |
103 |
| - */ |
104 |
| - 'domain' => null, |
105 |
| - |
106 |
| - /* |
107 |
| - |-------------------------------------------------------------------------- |
108 |
| - | Drip Endpoint URL |
109 |
| - |-------------------------------------------------------------------------- |
110 |
| - | |
111 |
| - | Sometimes you may wish to white-label your app and not expose the AJAX |
112 |
| - | request URLs as belonging to this package. To achieve that you can |
113 |
| - | rename the URL used for dripping caffeine into your application. |
114 |
| - | |
115 |
| - | Default: 'genealabs/laravel-caffeine/drip' (string) |
116 |
| - | |
117 |
| - */ |
118 |
| - 'route' => 'genealabs/laravel-caffeine/drip', // Customizable end-point URL |
119 |
| - |
120 |
| - /* |
121 |
| - |-------------------------------------------------------------------------- |
122 |
| - | Checking for Lapsed Drips |
123 |
| - |-------------------------------------------------------------------------- |
124 |
| - | |
125 |
| - | If the browser is put to sleep on (for example on mobil devices or |
126 |
| - | laptops), it will still cause an error when trying to submit the |
127 |
| - | form. To avoid this, we force-reload the form 2 minutes prior |
128 |
| - | to session time-out or later. Setting this setting to 0 |
129 |
| - | will disable this check if you don't want to use it. |
130 |
| - | |
131 |
| - | Default: 2000 (int) |
132 |
| - | |
133 |
| - */ |
134 |
| - 'outdated-drip-check-interval' => 2000, |
135 |
| - |
136 |
| - /* |
137 |
| - |-------------------------------------------------------------------------- |
138 |
| - | Use Route Middleware |
139 |
| - |-------------------------------------------------------------------------- |
140 |
| - | |
141 |
| - | Drips are enabled via route middleware instead of global middleware. |
142 |
| - | |
143 |
| - | Default: false (bool) |
144 |
| - | |
145 |
| - */ |
146 |
| - 'use-route-middleware' => false, |
147 |
| - |
148 |
| -]; |
149 |
| -``` |
150 |
| - |
151 |
| -___Only publish the config file if you need to customize it___: |
152 |
| -```sh |
153 |
| -php artisan caffeine:publish --config |
154 |
| -``` |
155 |
| - |
156 |
| -## Usage |
157 |
| -That was it! It will apply itself automatically where it finds a form with a |
158 |
| -`_token` field, or a meta tag named "csrf-token", while pages are open in |
159 |
| -browsers. |
160 |
| - |
161 |
| -### Prevent Caffeination |
162 |
| -There are two methods to prevent Caffeine for Laravel from dripping to keep the |
163 |
| -session alive: disabling it in Blade using the meta tag method, or enabling |
164 |
| -route-middleware mode, and then only enabling it on routes or route groups. |
165 |
| - |
166 |
| -#### Meta Tag Method |
167 |
| -If you would like to prevent a certain page from caffeinating your application, |
168 |
| -then add the following meta tag: |
169 |
| -```php |
170 |
| -<meta name="caffeinated" content="false"> |
171 |
| -``` |
172 |
| - |
173 |
| -#### Route Middleware Method |
174 |
| -To enable this mode, you need to publish the configuration file (see the |
175 |
| -configuration section above) and then set `use-route-middleware` to `true`. This |
176 |
| -will disable the default global middleware mode (which applies it to any page |
177 |
| -that has the CSRF token in it across your entire application). Now you need to |
178 |
| -selectively enable Caffeine on a given route or route group using route |
179 |
| -middleware: |
180 |
| - |
181 |
| -```php |
182 |
| -Route::any('test', 'TestController@test')->middleware('caffeinated'); |
183 |
| - |
184 |
| -Route::group(['middleware' => ['caffeinated']], function () { |
185 |
| - Route::any('test', 'TestController@test'); |
186 |
| -}) |
187 |
| -``` |
188 |
| - |
189 |
| -You can still use the route middleware method and apply it globally to all |
190 |
| -routes by editing `app/Http/Kernel.php` and adding it to the `web` middleware |
191 |
| -group. Although you should only use this option if you have a very specific use- |
192 |
| -case that prevents you from utilizing the default global middleware option. |
193 |
| - |
194 |
| -__This will only have effect if the page includes a form. If not, the page will |
195 |
| -not caffeinate your application anyway.__ |
196 |
| - |
197 |
| -# The Fine Print |
198 |
| -## Commitment to Quality |
199 |
| -During package development I try as best as possible to embrace good design and |
200 |
| -development practices to try to ensure that this package is as good as it can |
201 |
| -be. My checklist for package development includes: |
202 |
| - |
203 |
| -- ✅ Achieve as close to 100% code coverage as possible using unit tests. |
204 |
| -- ✅ Eliminate any issues identified by SensioLabs Insight and Scrutinizer. |
205 |
| -- ✅ Be fully PSR1, PSR2, and PSR4 compliant. |
206 |
| -- ✅ Include comprehensive documentation in README.md. |
207 |
| -- ✅ Provide an up-to-date CHANGELOG.md which adheres to the format outlined |
208 |
| - at <http://keepachangelog.com>. |
209 |
| -- ✅ Have no PHPMD or PHPCS warnings throughout all code. |
210 |
| - |
211 |
| -## Contributing |
212 |
| -Please observe and respect all aspects of the included Code of Conduct |
213 |
| -<https://github.com/GeneaLabs/laravel-caffeine/blob/master/CODE_OF_CONDUCT.md>. |
214 |
| - |
215 |
| -### Reporting Issues |
216 |
| -When reporting issues, please fill out the included template as completely as |
217 |
| -possible. Incomplete issues may be ignored or closed if there is not enough |
218 |
| -information included to be actionable. |
219 |
| - |
220 |
| -### Submitting Pull Requests |
221 |
| -Please review the Contribution Guidelines <https://github.com/GeneaLabs/laravel-caffeine/blob/master/CONTRIBUTING.md>. |
222 |
| -Only PRs that meet all criterium will be accepted. |
223 |
| - |
224 |
| -## ❤️ Open-Source Software - Give ⭐️ |
225 |
| -We have included the awesome `symfony/thanks` composer package as a dev |
226 |
| -dependency. Let your OS package maintainers know you appreciate them by starring |
227 |
| -the packages you use. Simply run `composer thanks` after installing this |
228 |
| -package. (And not to worry, since it's a dev-dependency it won't be installed in |
229 |
| -your live environment.) |
| 9 | +Documentation has moved to https://genealabs.com/docs/laravel-caffeine/. |
0 commit comments