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