=====
CS 328 - Week 13 Lecture 1 - 2025-04-21
=====

=====
TODAY WE WILL
=====
*   announcements
*   intro PHP sessions
*   prep for next class

=====
*   should be working on Homework 10!
    *   at-least-first-attempts due by 11:59 pm Friday, April 25
    *   submit early, submit often!

=====
*   REMINDER: HTTP/HTTPS is STATELESS!
    *   A given request/response pair is INDEPENDENT of all others!

    *   in "plain" HTTP/HTTPS, there is no way to associate
        a request with a previous request

*   ...so to save STATE, for a more-than-two-logical-step application,
    you need to somehow KLUGE a way to save state between
    these otherwise-independent request/responses;

    *   numerous application-tier languages have devised
        ADD-ON means of saving application-state information
	BETWEEN request/response pairs;
        (for example, based on cookies)

        YES, PHP provides such support!

=====
*   PHP does provide some features to support SESSIONS (cookie-based
    sessions), an add-on to save useful state for an application;

    *********
*   IMPORTANT: if you wish for your PHP application to use sessions,
    *********
    CALL the function:

    session_start();

    EARLY in your PHP document;

    *   from the PHP Manual page for session_start(),
        https://www.php.net/manual/en/function.session-start.php

        "Note:
	To use cookie-based sessions, session_start() must be called before outputting
	anything to the browser."

        *   (because session_start() adds info to the header in the
            response)

    *   remembering that the PHP engine executes the PHP tags before sending the
        resulting HTML to the web server to send to the browser,
	
	it IS fine, then, to have a PHP tag calling session_start()
	before the HTML's document's document type definition in your .php document

=====
PHP's $_SESSION array
=====
*   once you have called session_start(), NOW you have access to yet
    another PHP superglobal associative array, $_SESSION

*   INTERESTING aspect of $_SESSION array:
    *   in your PHP code, you are NOT supposed to CHANGE the
        contents of $_GET, $_POST, $_SERVER ---

    *   BUT!!! in your PHP code, you CAN CHANGE the contents
        of $_SESSION as desired to maintain desired state information

        *   want to add a new key to $_SESSION?
	    just do it!
		
	    $_SESSION["moo"] = "cow sound";

        *   now "moo" is a key in $_SESSION,
	    and the value of the expression $_SESSION["moo"] is "cow sound"

        *   and it is fine to CHANGE the value for a particular key:

            $_SESSION["moo"] = "sound of cow";

            *   the value of the expression $_SESSION["moo"] is now "sound of cow"

        *   and of course you can reference what has been put there;

            $desired_variable = $_SESSION["moo"];

            *   the value of the expression $desired_variable is now "sound of cow"

=====
session_destroy() - when you are DONE with a logical session!
=====
*   it is considered good practice to explicitly request that the
    logical session be destroyed when it reaches its logical end:

    session_destroy();

=====
additional NOTES about PHP $_SESSION array!
=====
*   BECAUSE of the nature of session attributes and values,
    $_SESSION is not intended for long-term value storage!

    *   you should call session_destroy() when the logical session
        is done, BUT it WILL eventually time out if time passes;

    *   also note: do not try to save an OCI connection object
        in $_SESSION! (doesn't work, and is a bad idea anyway...)

        each call to a PHP postback should close any connections
        before it completes its response

=====
*   also (from Stepp et al "Web Programming Step by Step" 2nd ed.)
    if for some reason you want to get rid of the current and
    immediately begin a new session,
    you can do so by regenerating a new session ID and retarting:

    session_destroy();
    session_regenerate_id(TRUE);
    session_start();

=====
WHAT can go in a $_SESSION array?
=====
*   info from earlier in a session that you want later

*   info to keep track of the current or next state
    (helpful!)

=====
PHP SESSION-SANITY HELPERS
=====
*   draw a FINITE-STATE DIAGRAM to describe your desired web application's
    behavior!
    *   (see posted example for try-quad.php)

*   have a helper function for each state in your application
    logic
    *   have the first version of each be a STUB, a little
        working version of the function that just
        proclaims what you called
	*   (and including an anchor element to
	    your PHP to continue is also useful)

*   START the postback PHP for your application with an if-elseif 
    that just lays out the order these will be called,
    
    setting up the $_SESSION key to keep track of the current state

*   try-quad.php - by the end of class, this just has such stubs,
    and such setting up of a $_SESSION key "next_state",
    BUT note that you can try it out and "walk" through the expected
    logical session

    *   we'll REPLACE these stub functions with actual desired behavior
        next class!

    *   a USEFUL pattern we will be practicing as we do so:
        *   as you are writing the function FOR a state in your application:
	
	    *   IF this state responds to a submitted form whose method="post",
	        be sure to GRAB (and SANITIZE!!) what has JUST been submitted
		from $_POST

            *   IF what it has grabbed-and-sanitized from $_POST might be
	        USEFUL for a later state, ADD that information to $_SESSION

            *   IF this state needs something from a previous state (besides
	        the information from the JUST-submitted form), can hopefully
		GRAB that from $_SESSION

            *   IF something this state is doing might be needed in a LATER
	        state, ADD it or UPDATE it accordingly in $_SESSION