Aran Clary Deltac

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}; # bar

DESCRIPTION

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).

AUTHORS AND LICENSE

See "AUTHOR" in Starch, "CONTRIBUTORS" in Starch, and "LICENSE" in Starch.