|
| 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 7.x |
| 53 | + |
| 54 | +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. |
| 55 | + |
| 56 | +**Example**: |
| 57 | + |
| 58 | +```javascript |
| 59 | +var TomcatCookies = Cookies.withConverter({ |
| 60 | + write: function (value) { |
| 61 | + // Encode all characters according to the "encodeURIComponent" spec |
| 62 | + return encodeURIComponent(value) |
| 63 | + // Revert the characters that are unnecessarly encoded but are |
| 64 | + // allowed in a cookie value |
| 65 | + .replace(/%(23|24|26|2B|3A|3C|3E|3D|2F|3F|40|5B|5D|5E|60|7B|7D|7C)/g, decodeURIComponent) |
| 66 | + // Encode the parens that are interpreted incorrectly by Tomcat |
| 67 | + .replace(/[\(\)]/g, escape); |
| 68 | + } |
| 69 | +}); |
| 70 | +``` |
| 71 | + |
| 72 | +Alternatively, you can check the [Java Cookie](https://github.com/js-cookie/java-cookie) project, which integrates nicely with JavaScript Cookie. |
| 73 | + |
| 74 | +## JBoss 7.1.1 |
| 75 | + |
| 76 | +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. |
| 77 | + |
| 78 | +**Example**: |
| 79 | + |
| 80 | +```javascript |
| 81 | +var JBossCookies = Cookies.withConverter({ |
| 82 | + write: function (value) { |
| 83 | + // Encode all characters according to the "encodeURIComponent" spec |
| 84 | + return encodeURIComponent(value) |
| 85 | + // Revert the characters that are unnecessarly encoded but are |
| 86 | + // allowed in a cookie value |
| 87 | + .replace(/%(23|24|26|2B|3A|3C|3E|3D|2F|3F|40|5B|5D|5E|60|7B|7D|7C)/g, decodeURIComponent) |
| 88 | + // Encode again the characters that are not allowed in JBoss 7.1.1, like "[" and "]": |
| 89 | + .replace(/[\[\]]/g, encodeURIComponent); |
| 90 | + } |
| 91 | +}); |
| 92 | +``` |
| 93 | + |
| 94 | +Alternatively, you can check the [Java Cookie](https://github.com/js-cookie/java-cookie) project, which integrates nicely with JavaScript Cookie. |
0 commit comments