scratch – Blame information for rev 58
?pathlinks?
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. |