NAME
Starch::State - The Starch state object.
SYNOPSIS
my $state = $starch->state();
$state->data->{foo} = 'bar';
$state->save();
$state = $starch->state( $state->id() );
print $state->data->{foo}; # barDESCRIPTION
This is the state class used by "state" in Starch::Manager.
REQUIRED ARGUMENTS
manager
The Starch::Manager object that glues everything together. The state object needs this to get at configuration information and the stores. This argument is automatically set by "state" in Starch::Manager.
OPTIONAL ARGUMENTS
id
The state ID. If one is not specified then one will be built and the state will be considered new.
ATTRIBUTES
original_data
The state data at the point it was when the state object was first instantiated.
data
The state data which is meant to be modified.
expires
This defaults to "expires" in Starch::Manager and is stored in the "data" under the "expires_state_key" in Starch::Manager key.
modified
Whenever the state is "save"d this will be updated and stored in "data" under the "modified_state_key" in Starch::Manager.
created
When the state is created this is set and stored in "data" under the "created_state_key" in Starch::Manager.
in_store
Returns true if the state is expected to exist in the store (AKA, if the "id" argument was specified or "save" was called).
Note that the value of this attribute may change after "data" is called which will set this to false if the store did not have the data for the state.
is_loaded
This returns true if the "original_data" has been loaded up from the store. Note that "original_data" will be automatically loaded if "original_data", "data", or any methods that call them, are called.
is_saved
Returns true if the state is "in_store" and is not "is_dirty".
is_deleted
Returns true if "delete" has been called on this state.
is_dirty
Returns true if the state data has changed (if "original_data" and "data" are different).
METHODS
save
Saves this state in the "store" in Starch::Manager if it "is_dirty" and not "is_deleted".
delete
Deletes the state from the "store" in Starch::Manager and sets "is_deleted".
reload
Clears "original_data" and "data" so that the next call to these will reload the state data from the store. This method is potentially destructive as you will loose any changes to the data that have not been saved.
rollback
Sets "data" to "original_data".
clear
Empties "data" and "original_data", and calls "mark_dirty".
mark_clean
Marks the state as not "is_dirty" by setting "original_data" to "data". This is a potentially destructive method as "save" will silentfly not save if the state is not "is_dirty".
mark_dirty
Increments the "dirty_state_key" in Starch::Manager value in "data", which causes the state to be considered dirty.
set_expires
# Extend this state's expires duration by two hours.
$state->set_expires( $state->expires() + (2 * 60 * 60) );Use this to set the state's expires to a duration different than the global expires set by "expires" in Starch::Manager. This is useful for, for example, to support a "Remember Me" checkbox that many login forms provide where the difference between the user checking it or not is just a matter of what the state's expires duration is set to.
Remember that the "expires" duration is a measurement, in seconds, of how long the state will live in the store since the last modification, and how long the cookie (if you are using cookies) will live since the last request.
The expires duration can be more than or less than the global expires, there is no artificial constraint.
reset_expires
Sets this state's expires to "expires" in Starch::Manager, overriding and custom expires set on this state.
reset_id
This re-generates a new "id" and marks the "data" as dirty. Often this is used to avoid session fixation as part of authentication and de-authentication (login/logout).
SUPPORT
See "SUPPORT" in Starch.
AUTHORS
See "AUTHORS" in Starch.