scratch – Blame information for rev 58

Subversion Repositories:
Rev:
Rev Author Line No. Line
58 office 1 # Server-side integration
2  
3 There are some servers that are not compliant with the [RFC 6265](http://tools.ietf.org/html/rfc6265). For those, some characters that are not encoded by JavaScript Cookie might be treated differently.
4  
5 Here we document the most important server-side peculiarities and their workarounds. Feel free to send a [Pull Request](https://github.com/js-cookie/js-cookie/blob/master/CONTRIBUTING.md#pull-requests) if you see something that can be improved.
6  
7 *Disclaimer: This documentation is entirely based on community provided information. The examples below should be used only as a reference.*
8  
9 ## PHP
10  
11 In PHP, `setcookie()` function encodes cookie values using `urlencode()` function, which applies `%`-encoding but also encodes spaces as `+` signs, [for historical reasons](http://php.net/manual/en/function.urlencode.php#function.urlencode). When cookies are read back via `$_COOKIE` or `filter_input(INPUT_COOKIE)`, they would go trough a decoding process which decodes `%`-encoded sequences and also converts `+` signs back to spaces. However, the plus (`+`) sign is valid cookie character by itself, which means that libraries that adhere to standards will interpret `+` signs differently to PHP.
12  
13 This presents two types of problems:
14  
15 1. PHP writes a cookie via `setcookie()` and all spaces get converted to `+` signs. JavaScript Cookie read `+` signs and uses them literally, since it is a valid cookie character.
16 2. JavaScript Cookie writes a cookie with a value that contains `+` signs and stores it as is, since it is a valid cookie character. PHP read a cookie and converts `+` signs to spaces.
17  
18 To make both PHP and JavaScript Cookie play nicely together?
19  
20 **In PHP**, use `setrawcookie()` instead of `setcookie()`:
21  
22 ```php
23 setrawcookie($name, rawurlencode($value));
24 ```
25  
26 **In JavaScript**, use a custom converter.
27  
28 **Example**:
29  
30 ```javascript
31 var PHPCookies = Cookies.withConverter({
32 write: function (value) {
33 // Encode all characters according to the "encodeURIComponent" spec
34 return encodeURIComponent(value)
35 // Revert the characters that are unnecessarly encoded but are
36 // allowed in a cookie value, except for the plus sign (%2B)
37 .replace(/%(23|24|26|3A|3C|3E|3D|2F|3F|40|5B|5D|5E|60|7B|7D|7C)/g, decodeURIComponent);
38 },
39 read: function (value) {
40 return value
41 // Decode the plus sign to spaces first, otherwise "legit" encoded pluses
42 // will be replaced incorrectly
43 .replace(/\+/g, ' ')
44 // Decode all characters according to the "encodeURIComponent" spec
45 .replace(/(%[0-9A-Z]{2})+/g, decodeURIComponent);
46 }
47 });
48 ```
49  
50 Rack seems to have [a similar problem](https://github.com/js-cookie/js-cookie/issues/70#issuecomment-132503017).
51  
52 ## Tomcat
53  
54 ### Version >= 7.x
55  
56 It seems that there is a situation where Tomcat does not [read the parens correctly](https://github.com/js-cookie/js-cookie/issues/92#issue-107743407). To fix this you need to write a custom write converter.
57  
58 **Example**:
59  
60 ```javascript
61 var TomcatCookies = Cookies.withConverter({
62 write: function (value) {
63 // Encode all characters according to the "encodeURIComponent" spec
64 return encodeURIComponent(value)
65 // Revert the characters that are unnecessarly encoded but are
66 // allowed in a cookie value
67 .replace(/%(23|24|26|2B|3A|3C|3E|3D|2F|3F|40|5B|5D|5E|60|7B|7D|7C)/g, decodeURIComponent)
68 // Encode the parens that are interpreted incorrectly by Tomcat
69 .replace(/[\(\)]/g, escape);
70 }
71 });
72 ```
73  
74 ### Version >= 8.0.15
75  
76 Since Tomcat 8.0.15, it is possible to configure RFC 6265 compliance by changing your `conf/context.xml` file and adding the new [CookieProcessor](https://tomcat.apache.org/tomcat-8.0-doc/config/cookie-processor.html) nested inside the Context element. It would be like this:
77  
78 ```xml
79 <Context>
80 <CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor"/>
81 </context>
82 ```
83 And you're all done.
84  
85 Alternatively, you can check the [Java Cookie](https://github.com/js-cookie/java-cookie) project, which integrates nicely with JavaScript Cookie.
86  
87 ## JBoss 7.1.1
88  
89 It seems that the servlet implementation of JBoss 7.1.1 [does not read some characters correctly](https://github.com/js-cookie/js-cookie/issues/70#issuecomment-148944674), even though they are allowed as per [RFC 6265](https://tools.ietf.org/html/rfc6265#section-4.1.1). To fix this you need to write a custom converter to send those characters correctly.
90  
91 **Example**:
92  
93 ```javascript
94 var JBossCookies = Cookies.withConverter({
95 write: function (value) {
96 // Encode all characters according to the "encodeURIComponent" spec
97 return encodeURIComponent(value)
98 // Revert the characters that are unnecessarly encoded but are
99 // allowed in a cookie value
100 .replace(/%(23|24|26|2B|3A|3C|3E|3D|2F|3F|40|5B|5D|5E|60|7B|7D|7C)/g, decodeURIComponent)
101 // Encode again the characters that are not allowed in JBoss 7.1.1, like "[" and "]":
102 .replace(/[\[\]]/g, encodeURIComponent);
103 }
104 });
105 ```
106  
107 Alternatively, you can check the [Java Cookie](https://github.com/js-cookie/java-cookie) project, which integrates nicely with JavaScript Cookie.