Cookie Value Object

The Cookie Value Object provides an immutable representation of an HTTP cookie within the Hypervel Cookie library. This component extends Hyperf's base cookie implementation and adds fluent interface methods for modifying cookie properties while maintaining immutability. For information about how to use cookies in your application, see Usage Guide, and for details on how cookies are managed, see Cookie Manager.

Overview

The Cookie class is a value object that represents an HTTP cookie with various properties like name, value, expiration time, path, domain, and security settings. As a value object, it follows immutability principles - instead of modifying an existing cookie object, each modification method returns a new instance with the changed property.

Sources: src/Cookie.php7-12

Immutability Pattern

The Cookie class implements the immutability pattern, where objects cannot be modified after creation. Instead, methods that would traditionally modify the object return a new instance with the desired changes. This approach offers several benefits:

1. Thread safety - Immutable objects are inherently thread-safe
2. Predictable behavior - An object's state doesn't change unexpectedly
3. Simplified debugging - Object state remains constant throughout its lifecycle

Sources: src/Cookie.php18-24 src/Cookie.php31-37

Cookie Properties and Modification Methods

The Cookie value object contains several properties and provides methods to create new instances with modified properties:

Property	Description	Modification Method
name	Cookie name	(immutable after creation)
value	Cookie value	withValue()
domain	Domain the cookie is available to	withDomain()
expire	Expiration timestamp	withExpires()
path	Path on the server the cookie is available on	withPath()
secure	Whether cookie should only be sent over HTTPS	withSecure()
httpOnly	Whether cookie is accessible only through HTTP protocol	withHttpOnly()

Sources: src/Cookie.php11-112

Property Modification Flow

Sources: src/Cookie.php18-112

Method Details

withValue

Creates a new cookie instance with a modified value. This method accepts a string or null and returns a new Cookie instance.

Sources: src/Cookie.php18-24

withDomain

Creates a new cookie instance with a modified domain. The domain specifies which hosts the cookie is available to.

Sources: src/Cookie.php31-37

withExpires

Creates a new cookie instance with a modified expiration time. The expiration can be provided as:

• A DateTimeInterface object
• An integer (Unix timestamp)
• A string parsable by PHP's strtotime()

The method uses the private expiresTimestamp() helper method to convert various formats to a Unix timestamp.

Sources: src/Cookie.php46-73

withPath

Creates a new cookie instance with a modified path. The path indicates the server path on which the cookie will be available. If an empty string is provided, it defaults to "/".

Sources: src/Cookie.php80-86

withSecure

Creates a new cookie instance with a modified secure flag. When set to true, the cookie will only be transmitted over a secure HTTPS connection.

Sources: src/Cookie.php93-99

withHttpOnly

Creates a new cookie instance with a modified httpOnly flag. When set to true, the cookie will be accessible only through the HTTP protocol and not via JavaScript.

Sources: src/Cookie.php106-112

Integration with Cookie Manager

The Cookie value object is created and used by the CookieManager, which implements the CookieContract interface. The relationship is illustrated below:

Sources: src/Cookie.php11-113

Expires Timestamp Handling

The Cookie class includes a private helper method expiresTimestamp() that converts various time formats to a Unix timestamp:

Sources: src/Cookie.php59-73

This method provides flexibility for developers to specify expiration times in various formats while ensuring that internally the cookie always uses a consistent Unix timestamp format.