1: <?php
  2: /**
  3:  * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
  4:  * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
  5:  *
  6:  * Licensed under The MIT License
  7:  * Redistributions of files must retain the above copyright notice.
  8:  *
  9:  * @copyright     Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
 10:  * @link          http://cakephp.org CakePHP(tm) Project
 11:  * @since         3.5.0
 12:  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
 13:  */
 14: namespace Cake\Http\Cookie;
 15: 
 16: /**
 17:  * Cookie Interface
 18:  */
 19: interface CookieInterface
 20: {
 21:     /**
 22:      * Expires attribute format.
 23:      *
 24:      * @var string
 25:      */
 26:     const EXPIRES_FORMAT = 'D, d-M-Y H:i:s T';
 27: 
 28:     /**
 29:      * Sets the cookie name
 30:      *
 31:      * @param string $name Name of the cookie
 32:      * @return static
 33:      */
 34:     public function withName($name);
 35: 
 36:     /**
 37:      * Gets the cookie name
 38:      *
 39:      * @return string
 40:      */
 41:     public function getName();
 42: 
 43:     /**
 44:      * Gets the cookie value
 45:      *
 46:      * @return string|array
 47:      */
 48:     public function getValue();
 49: 
 50:     /**
 51:      * Gets the cookie value as a string.
 52:      *
 53:      * This will collapse any complex data in the cookie with json_encode()
 54:      *
 55:      * @return string
 56:      */
 57:     public function getStringValue();
 58: 
 59:     /**
 60:      * Create a cookie with an updated value.
 61:      *
 62:      * @param string|array $value Value of the cookie to set
 63:      * @return static
 64:      */
 65:     public function withValue($value);
 66: 
 67:     /**
 68:      * Get the id for a cookie
 69:      *
 70:      * Cookies are unique across name, domain, path tuples.
 71:      *
 72:      * @return string
 73:      */
 74:     public function getId();
 75: 
 76:     /**
 77:      * Get the path attribute.
 78:      *
 79:      * @return string
 80:      */
 81:     public function getPath();
 82: 
 83:     /**
 84:      * Create a new cookie with an updated path
 85:      *
 86:      * @param string $path Sets the path
 87:      * @return static
 88:      */
 89:     public function withPath($path);
 90: 
 91:     /**
 92:      * Get the domain attribute.
 93:      *
 94:      * @return string
 95:      */
 96:     public function getDomain();
 97: 
 98:     /**
 99:      * Create a cookie with an updated domain
100:      *
101:      * @param string $domain Domain to set
102:      * @return static
103:      */
104:     public function withDomain($domain);
105: 
106:     /**
107:      * Get the current expiry time
108:      *
109:      * @return \DateTime|\DateTimeImmutable|null Timestamp of expiry or null
110:      */
111:     public function getExpiry();
112: 
113:     /**
114:      * Get the timestamp from the expiration time
115:      *
116:      * Timestamps are strings as large timestamps can overflow MAX_INT
117:      * in 32bit systems.
118:      *
119:      * @return string|null The expiry time as a string timestamp.
120:      */
121:     public function getExpiresTimestamp();
122: 
123:     /**
124:      * Builds the expiration value part of the header string
125:      *
126:      * @return string
127:      */
128:     public function getFormattedExpires();
129: 
130:     /**
131:      * Create a cookie with an updated expiration date
132:      *
133:      * @param \DateTime|\DateTimeImmutable $dateTime Date time object
134:      * @return static
135:      */
136:     public function withExpiry($dateTime);
137: 
138:     /**
139:      * Create a new cookie that will virtually never expire.
140:      *
141:      * @return static
142:      */
143:     public function withNeverExpire();
144: 
145:     /**
146:      * Create a new cookie that will expire/delete the cookie from the browser.
147:      *
148:      * This is done by setting the expiration time to 1 year ago
149:      *
150:      * @return static
151:      */
152:     public function withExpired();
153: 
154:     /**
155:      * Check if a cookie is expired when compared to $time
156:      *
157:      * Cookies without an expiration date always return false.
158:      *
159:      * @param \DateTime|\DateTimeImmutable $time The time to test against. Defaults to 'now' in UTC.
160:      * @return bool
161:      */
162:     public function isExpired($time = null);
163: 
164:     /**
165:      * Check if the cookie is HTTP only
166:      *
167:      * @return bool
168:      */
169:     public function isHttpOnly();
170: 
171:     /**
172:      * Create a cookie with HTTP Only updated
173:      *
174:      * @param bool $httpOnly HTTP Only
175:      * @return static
176:      */
177:     public function withHttpOnly($httpOnly);
178: 
179:     /**
180:      * Check if the cookie is secure
181:      *
182:      * @return bool
183:      */
184:     public function isSecure();
185: 
186:     /**
187:      * Create a cookie with Secure updated
188:      *
189:      * @param bool $secure Secure attribute value
190:      * @return static
191:      */
192:     public function withSecure($secure);
193: 
194:     /**
195:      * Returns the cookie as header value
196:      *
197:      * @return string
198:      */
199:     public function toHeaderValue();
200: }
201: