Overview of VarManager for PHP-[3,4,5].

Written by David Horner. (website)

I don't know your name, but lets talk about VarManager.

Basic URI generation

Default Link (this has no forwarding or overrides) [/personal/code/varmanager/latest/example.php]
The whole idea of VarManager is to get rid of the requirement to hand create HREFs and FORMs. Clicking the above link will bring you right back to this page. Notice that since the VarManager object used to print the URI didn't have any forwards or overrides it doesn't add any variables to the URI string.

Overrides

The most basic operation for the VarManager is something called 'overrides'. Overrides allow you to add variables to the VarManager object state.
Overridden Link (this has overrides but no forwarding) [/personal/code/varmanager/latest/example.php?firstname=Dave&single=good&evenarrays[]=array&evenarrays[]=of&evenarrays[]=stuff]
As you can see, the above link now contains variables that will be passed along when the user clicks on the link. NOTE: You can unset an override by calling the var_unoverride() method.

Forwarding

Forwarding is where VarManager becomes very very handy. Forwarding tells the VarManager object that you would like to resend the existing variables in the environment if they exist. The link below forwards firstname so if you click the link in the overrides section, you'll see that the link below includes the information from the override link.
Forward Link (just forwarding) [/personal/code/varmanager/latest/example.php]
Forwarding can make your life very easy and there are many ways to forward variables. You can forward variables in the ENV by calling methods like: forwardall(),forwardall_except(),forward_beginswith(),forward_beginswith_except,forward(string),forward(array of strings), and others. NOTE: You can unset a forward by calling the var_unforward() method.

URI Location

So far all the generated URIs have been relative. Meaning the VarManager automatically references the special variable $PHP_SELF which isn't an absolute URL. Creating absolute URIs is as simple as passing a true flag to the second param of the replace_uri method.
Here is an example [http://dave.thehorners.com/personal/code/varmanager/latest/example.php]
This absolute URI is automagically created by VarManager as well.

But what do we do if we want to point to a location other than the current page? Thats simple, simply update the location property on your VarManager object! set_location(string) sets the location of the absolute generated URIs. Printing the URI forwards and overrides just as if you were pointing to the current page.
This example points to yahoo. Absolute: http://www.yahoo.com

Forms? You promised forms state management help!

Forms are not so different from plain jane HREFS. The syntax is not the same but we are dealing with the same variables and state information.Forms are handled in VarManager by two simple functions. print_form() and print_hidden(). To create a form that posts back to the current location simply call: print_form() which in turn prints the form tag with the action attribute set to the relative or absolute location.Then call print_hidden() which prints out hidden inputs for the variables which are overridden and forwarded. That is it!

For example here is a form asking for your first name. If you clicked on the overridden link you'll see Dave within the textbox. Fill out your name and click the Go! button. The page will refresh and all the forwarding links above will display your input.
First name:

Debugging The State of VarManager

For simplicity, VarManager includes a method called dumpinfo() that displays the current state of the object. This is very handy in trouble shooting problems.[Show Debug]

Some suggestions

Access all variables through the VarManager. This allows you to steer clear of issues in the future if PHP moves where variables are stored. It also enforces programming practices that allow you to operate with register_globals turned off (if you know what I mean by this, then you've probably been bitten.) As more people become aware of VarManager, the hope is that more and more PEAR packages will incorporate VarManager so they can forward and read state information stored within VarManager.

Try to minimize the number of hand coded URLs. If you use forwarding correctly, you will be able to restructure variable names and locations without having to change underlying code.

Advanced Usage

There is much more than can be done with VarManager. Read the class documentation for now [here].... I'll have more examples to come on my website. Hope you like VarManager!


Here is the code that created this page.
<?php
  
/**
    * VarManager Example - Simple example of how to use it.
    *
    * For the latest release and information visit
    * {@link http://dave.thehorners.com http://dave.thehorners.com}
    *
    * @copyright David Horner 2004-2005
    * @license http://www.gnu.org/copyleft/lesser.html LGPL License
    * @version 1.05
    * @author David A. Horner
    * {@link http://dave.thehorners.com Homepage}
    * @package VarManager
    * @filesource
    */
   
  // include the implementation
  
require_once("varmanager.php");

  
$vars=new VarManager;

  echo 
"<html>";
  echo 
"<head><title>Overview of VarManager</title></head>";
  echo 
"<body>";
  echo 
"<h1>Overview of VarManager for PHP-[3,4,5].</h1>";
  echo 
"<h5>Written by David Horner. (";
  echo 
"<a href=\"http://dave.thehorners.com/?example=VarManager\" target=_blank>";
  echo 
"website</a>)</h5>";

  if(
$vars->var_exists("firstname")) {
      echo 
"<h4>Welcome back ".$vars->var_val("firstname").".</h4>";
  } else {
      echo 
"<h4>I don't know your name, but lets talk about VarManager.</h4>";
  }


  echo 
"<h3>Basic URI generation</h3>";
  echo 
$vars->replace_uri("<a href=\"{URI}\">Default Link</a> ");
  echo 
$vars->replace_uri("(this has no forwarding or overrides) [{URI}]<br>");
  
  echo 
"The whole idea of VarManager is to get rid of the requirement to hand";
  echo 
" create HREFs and FORMs.  Clicking the above link will bring you right";
  echo 
" back to this page.  Notice that since the VarManager object used to";
  echo 
" print the URI didn't have any forwards or overrides it doesn't add ";
  echo 
" any variables to the URI string.";
  echo 
"<br>";
  

  echo 
"<h3>Overrides</h3>";
  echo 
"The most basic operation for the VarManager is something called ";
  echo 
"'overrides'.  Overrides allow you to add variables to the VarManager ";
  echo 
"object state.";
  echo 
"<br>";
  
// forward incoming request vars.
  
$tmp=$vars->makedup();
  
$tmp->override(array("firstname"=>"Dave","single"=>"good"));
  
$tmp->override(array("evenarrays"=>array("array","of","stuff")));
  echo 
$tmp->replace_uri("<a href=\"{URI}\">Overridden Link</a> ");
  echo 
$tmp->replace_uri("(this has overrides but no forwarding) [{URI}]<br>");
  echo 
"As you can see, the above link now contains variables that will be ";
  echo 
"passed along when the user clicks on the link. NOTE: You can unset ";
  echo 
" an override by calling the var_unoverride() method.";
  
  echo 
"<h3>Forwarding</h3>";
  echo 
"Forwarding is where VarManager becomes very very handy.";
  echo 
" Forwarding tells the VarManager object that you would like to resend ";
  echo 
"the existing variables in the environment if they exist.";
  echo 
" The link below forwards firstname so if you ";
  echo 
" click the link in the overrides section, you'll see that the link ";
  echo 
"below includes the information from the override link.<br>";
  
$vars->forward("firstname");
  echo 
$vars->replace_uri("<a href=\"{URI}\">Forward Link</a> ");
  echo 
$vars->replace_uri("(just forwarding) [{URI}]<br>");
  echo 
"Forwarding can make your life very easy and there are many ways to ";
  echo 
" forward variables.  You can forward variables in the ENV by calling ";
  echo 
"methods like: forwardall(),forwardall_except(),forward_beginswith(),";
  echo 
"forward_beginswith_except,forward(string),";
  echo 
"forward(array of strings), and others. NOTE: You can unset a forward ";
  echo 
" by calling the var_unforward() method.";

  echo 
"<h3>URI Location</h3>";
  echo 
"So far all the generated URIs have been relative.  Meaning the ";
  echo 
"VarManager automatically references the special variable \$PHP_SELF ";
  echo 
" which isn't an absolute URL.  Creating absolute URIs is as simple as";
  echo 
" passing a true flag to the second param of the replace_uri method.<br>";
  echo 
$vars->replace_uri(
  
"Here is an <a href=\"{URI}\">example</a> [{URI}]<br>",true); 
  echo 
" This absolute URI is automagically created by VarManager as well.<br>";
  echo 
"<br>";
  echo 
"But what do we do if we want to point to a location other than";
  echo 
" the current page?  Thats simple, simply update the location property";
  echo 
" on your VarManager object!  set_location(string) sets the location of";
  echo 
" the absolute generated URIs.  Printing the URI forwards and overrides";
  echo 
" just as if you were pointing to the current page.<br>";
  echo 
"This example points to yahoo. ";
  
//set server location for all absolute links(absolute and without program) 
  
$vars->set_location("http://www.yahoo.com");
  
//print href based on forward env.  
  
echo $vars->replace_uri("Absolute: <a href=\"{URI}\">{URI}</a><br>",true);


  echo 
"<h3>Forms?  You promised forms state management help!</h3>";
  echo 
"Forms are not so different from plain jane HREFS.  The syntax is not ";
  echo 
"the same but we are dealing with the same variables and state information.";
  echo 
"Forms are handled in VarManager by two simple functions. print_form()";
  echo 
" and print_hidden(). To create a form that posts back to the current ";
  echo 
"location simply call: print_form() which in turn prints the form tag ";
  echo 
"with the action attribute set to the relative or absolute location.";
  echo 
"Then call print_hidden() which prints out hidden inputs for the variables";
  echo 
" which are overridden and forwarded.  That is it!<br><br>";
  
  echo 
"For example here is a form asking for your first name.";
  echo 
" If you clicked on the overridden link you'll see Dave within the textbox.";
  echo 
" Fill out your name and click the Go! button.  The page will refresh ";
  echo 
"and all the forwarding links above will display your input.";
  
$vars->print_form();
  
$vars->print_hidden();
  echo 
"First name: <input type=text name=firstname value=\"";
  echo 
$vars->var_val("firstname")."\">";
  echo 
"<input type=submit name=submitted value=\"Go!\">";
  echo 
"</form>";

  echo 
"<h3>Debugging The State of VarManager</h3>";
  echo 
"For simplicity, VarManager includes a method called dumpinfo() that";
  echo 
" displays the current state of the object.  This is very handy in ";
  echo 
"trouble shooting problems.";
  if(
$vars->var_issent("debug")) {
    
$tmp=$vars->makedup();
    
$tmp->var_unset("debug");
    echo 
$tmp->replace_uri("[<a href=\"{URI}\">Hide Debug</a>]<br>");
    
$vars->dumpinfo();
  } else {
    
$tmp=$vars->makedup();
    
$tmp->override(array("debug"=>"true"));
    echo 
$tmp->replace_uri("[<a href=\"{URI}\">Show Debug</a>]<br>");
  }

  echo 
"<h3>Some suggestions</h3>";
  echo 
"Access all variables through the VarManager.  This";
  echo 
" allows you to steer clear of issues in the future if PHP moves where ";
  echo 
"variables are stored.  It also enforces programming practices that ";
  echo 
"allow you to operate with register_globals turned off (if you know ";
  echo 
"what I mean by this, then you've probably been bitten.)";
  echo 
" As more people become aware of VarManager, the hope is that more and ";
  echo 
"more PEAR packages will incorporate VarManager so they can forward and";
  echo 
" read state information stored within VarManager.<br><br>";
  echo 
"Try to minimize the number of hand coded URLs.  If you use forwarding";
  echo 
" correctly, you will be able to restructure variable names and locations";
  echo 
" without having to change underlying code.";

  echo 
"<h3>Advanced Usage</h3>";
  echo 
"There is much more than can be done with VarManager.  Read the class";
  echo 
" documentation for now ";
  echo 
"[<a target=_blank href=\"http://dave.thehorners.com/personal/code/varmanager/latest/docs/\">here</a>]....";
  echo 
" I'll have more examples to come on my ";
  echo 
"<a href=\"http://dave.thehorners.com/?example=VarManager\" target=_blank>";
  echo 
"website</a>.  Hope you like VarManager!";

  
  echo 
"<br><br><hr>";
  echo 
"Here is the code that created this page.";
  echo 
"<hr>";
  echo 
highlight_file("example.php");
  echo 
"</body>";
  echo 
"</html>";
?>

1