ASP.NET's strength lies in object oriented features, and it's flexibility. Because of the CLR you can have C# programmers and VB.NET programmers working on the same project, or switch languages half way through and not have to rewrite all of your old classes. The .NET class library is organized into inheritable classes based around particular tasks, such as working with XML or image manipulation, so a lot of the more common tasks have been already handled for you.

Visual Studio .NET is a massive development IDE that (as long as your computer is fast enough) will shave tons of time of your coding. It has built in debugging along with IntelliSense, which allows for auto-completion of methods and variables so you don't have to memorize everything.

On the down side, ASP.NET is expensive. One it uses tons more resources on the web server so you'll require either better server or more servers in the farm. Windows 2003 and Visual Studio .NET are pretty tough on the pocket book as well. It's extremely rare for an ASP.NET app not to be running on IIS. And if you pay attention to any of the bug reports, you'll notice that Windows and IIS have had a bit of a history with vulnerabilities being exploited.

PHP
PHP works in combination of HTML to display dynamic elements on the page. PHP only parses code within its delimiters, such as . Anything outside its delimiters is sent directly to the output and not parsed by PHP.

PHP strength lies mostly in LAMP. The LAMP architecture has become popular in the Web industry as a way of deploying inexpensive, reliable, scalable, secure web applications. PHP is commonly used as the P in this bundle alongside Linux, Apache and MySQL. PHP can be used with a large number of relational database management systems, runs on all of the most popular web servers and is available for many different operating systems. This flexibility means that PHP has a wide installation base across the Internet; over 18 million Internet domains are currently hosted on servers with PHP installed.

With PHP 5 finally came exception handling and true OOP, but it still lack namespacing to prevent class naming collisions. PHP's type checking is very loose, potentially causing problems. Another drawback is that variables in PHP are not really considered to have a type. Finally, for some reason big corporations feel that if they're not paying for something, then it's not worth buying. If that's you're company's mentality, they just need to wake up and check out all the awesome free software that's out there.

So Which Is Better?
We'll I have my opinions and you may have yours as well. But in general, PHP is cheap, secure, fast, and reliable, while ASP.NET has quicker development time and is easier due to its class library system can probably be maintained more easily. Both are great languages, and it's up to you to make the decision.

• How to create a discount code system
  1. How to offer different types of discounts
  2. How to take the discount into account at the shopping basket stage
• How to sell voucher codes on your store
• How to offer discounts to customers who bring us referral business

Discount codes

Discount codes are a great way to both entice new customers into a store, and also to help retain customers with special discounts. The discount code should work by allowing the customer to enter a code, which will then be verified by the store, and then a discount will be applied to the order.

The following are discount options we may wish to have available in our store:

• A fixed amount deducted from the cost of the order
• A fixed percentage deducted from the cost of the order
• The shipping cost altered, either to free or to a lower amount
• Product-based discounts (although we won't cover this one in the article)

It may also be useful to take into account the cost of the customer's basket; after all if we have a $5 discount code, we probably wouldn't want that to apply for orders of $5 or lower, and may wish to apply a minimum order amount.

Discount codes data

When storing discount codes in the framework, we need to store and account for:

• The voucher code itself, so that we can check that the customer is entering a valid code
• Whether the voucher code is active, as we may wish to prepare some voucher codes, but not have them usable until a certain time, or we may wish to discontinue a code
• A minimum value for the customer's basket, either as an incentive for the customer to purchase more or to prevent loss-making situations (for example a $10 discount on a $5 purchase!)
• The type of discount:
  1. Percentage: To indicate that the discount amount is a percentage to be removed from the cost
  2. Fixed amount deducted: To indicate that the discount amount is a fixed amount to be removed from the order total
  3. Fixed amount set to shipping: To indicate that the discount amount is to be the new value for the shipping cost
• Discount amount; that is, the amount of discount to be applied
• The number of vouchers issued, if we wish to limit the number of uses of a particular voucher code
• An expiry date, so that if we wish to have the voucher code expire, codes with a date after the stored expiry date would no longer work

Discount codes database

The following table illustrates this information as database fields within a table:

The default value for num_vouchers is -1, which we will use for vouchers that are not limited to a set number of issues.

The following code represents this data in our database:

CREATE TABLE `discount_codes` (
`ID` INT( 11 ) NOT NULL AUTO_INCREMENT ,
`vouchercode` VARCHAR( 25 ) NOT NULL ,
`active` TINYINT( 1 ) NOT NULL ,
`min_basket_cost` FLOAT NOT NULL ,
`discount_operation` ENUM( '-', '%', 's' ) NOT NULL ,
`discount_amount` FLOAT NOT NULL ,
`num_vouchers` INT( 11 ) NOT NULL DEFAULT '-1',
`expiry` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ,
PRIMARY KEY ( `ID` )
) ENGINE = INNODB DEFAULT CHARSET = latin1 AUTO_INCREMENT =1;

Discount codes functionality

The functionality for discount codes can be encapsulated into a single function; this function should be called when the basket is loaded and updated. (That is, if the customer changes the quantity of products in the basket, we must run this; also, if the customer adds a voucher code to their order, we must obviously call this function.)

The function needs to:

1. Check to see if the customer has entered a voucher code with their order.
2. If they have, it must look up the voucher code to see if it exists, or doesn't exist.
3. If the voucher code exists, it must check to see if the code has expired and is still able to be used (that is, that num_vouchers is greater than 0 or equal to -1).
4. Assuming this is the case, it must then check to see that the customer's basket cost is at least that of the minimum order amount in the discount codes record in the database.
5. If the voucher is able to be used, it must then determine the type of voucher, and make the relevant discount to either the basket cost, or the shipping costs.

The following code does all of this; some of the relevant sections described are highlighted within the code:

/**
  * Consider and apply voucher codes
  * Types of voucher code
  * - = FIXED AMOUNT OFF
  * % = PERCENTAGE OFF
  * s = SET NEW SHIPPING COST
  * @param voucherCode String
  * @return void
  */
  private function considerVouchers( $voucherCode )
  {
    //The voucher code value is checked to ensure it is not empty 
    // (as per point 1)
    if( $voucherCode != '' )
    {
      // we need the date, to see if the voucher has expired
      $cts = date('Y-m-d H:i:s');
      $voucher_sql = "SELECT *, if('{$cts}' > expiry, 1, 0)
                        AS expired FROM discount_codes
                      WHERE vouchercode='{$voucherCode}' LIMIT 1";
      $this->registry->getObject('db')->executeQuery( $voucher_sql );
      if( $this->registry->getObject('db')->numRows() == 0 )
      {
        $this->voucher_notice = 'Sorry, the voucher code you entered
            is invalid';
      }
      else
      {
        $voucher = $this->registry->getObject('db')->getRows();
        if( $voucher['active'] == 1 )
        {
          if( $voucher['expired'] == 1 )
          {
            $this->voucher_notice = 'Sorry, this voucher has
                expired';
            return false;
          }
          else
          {
            // check to see there are some vouchers, and customer
            // has enough in their basket (points 3 and 4)
            if( $voucher['num_vouchers'] != 0 )
            {
              if( $this->cost >= $voucher['min_basket_cost'] )
              {
                $this->discountCode = $voucherCode;
                $this->discountCodeId = $voucher['ID'];
                // If the discount operation is a percentage, then
                // the discount value is applied to the basket cost
                // to calculate that percentage. This amount is then
                // deducted from the order cost, giving a "discount
                // value"% discount from the order.
                if( $voucher['discount_operation'] == '%' )
                {
                  $this->cost = $this->
              cost - (($this->cost)/100)*$voucher['discount_amount'];
                  $this->voucher_notice = 'A '
                      . $voucher['discount_amount']
                      . '% discount has been applied to your order';
                  return true;
                  // If the discount operation is a subtraction, then
                  // the discount amount from the discount code is
                  // deducted from the order cost, and the order cost
                  // is updated to reflect this.
                }
                elseif( $voucher['discount_operation'] == '-' )
                {
                  $this->cost =
                      $this->cost - $voucher['discount_amount'];
                  $this->voucher_notice = 'A discount of £'
                      . $voucher['discount_amount']
                      . ' has been applied to your order';
                  return true;
                  // Finally, if the discount operation is set to s
                  // then, we set the shipping cost to the discount
                  // value. This could allow us to set free shipping,
                  // or just reduce shipping costs.
                }
                elseif( $voucher['discount_operation'] == 's' )
                {
                  $this->shipping_cost = $voucher['discount_amount'];
                  $this->voucher_notice = 'Your orders shipping cost
                      has been reduced to £'
                      . $voucher['discount_amount'];
                  return true;
                }
              }
              else
              {
                $this->voucher_notice = 'Sorry, your order total is
                    not enough for your order to qualify for this
                    discount code';
                return false;
              }
            }
            else
            {
              $this->voucher_notice = 'Sorry, this was a limited
                  edition voucher code, there are no more instances
                  of that code left';
              return false;
            }
          }
        }
        else
        {
          $this->voucher_notice = 'Sorry, the vocuher code you
              entered is no longer active';
          return false;
        }
      }
    }
  }

Now, we have the basis for our discount code feature. We can issue discount codes as an incentive to get new customers, or to encourage existing customers to make more purchases.

Reducing the number of codes available

One feature we added to the database structure for our discount codes was the ability to limit the number of times a voucher could be used, effectively allowing a code to be "issued" a set number of times. We need to take this into account, and reduce the number of vouchers in circulation, once one has been used.

This won't be done at this stage, but will need to be implemented at the final checkout stage when an order is updated to "paid", or the customer pays online. The following function will do this for us; it checks to see if a code is used, or if it's unlimited or has expired, and if it's not unlimited and hasn't already expired, it updates the code to decrement the number of uses remaining:

private function adjustDiscountCodeQuantities( $codeId )
{
$sql = "SELECT num_vouchers FROM discount_codes WHERE ID=" . $codeId;
$this->registry->getObject('db')->executeQuery( $sql );
if( $this->registry->getObject('db')->numRows() > 0 )
{
$codeData = $this->registry->getObject('db')->getRows();
if( $codeData['num_vouchers'] > 0 )
{
$sql = "UPDATE discount_codes SET num_vouchers=num_vouchers-1
WHERE ID=" . $codeId;
$this->registry->getObject('db')->executeQuery( $sql );
}
}
}

Purchasable voucher codes

Voucher codes work in the same way as discount codes, except that they are purchased for use by a customer, as opposed to given away for promotional reasons.

Existing functionality

The discount codes and product variation features already give us most of the functionality required for purchasable voucher codes.

Discount codes

As a voucher code has the same functionality as our discount codes, which we built earlier, we have a large portion of the functionality in place. When a voucher is purchased, a new record in the discount codes table will be made, with a num_vouchers value of 1.

Product variations

Let's say we have product variations feature built, which allows us to create a purchasable voucher code product, with variations that increase the price in increments, perhaps of $5.

Required additional functionality

We only need to add additional functionality to this if we wish to automate the process of generating a voucher code when a customer purchases a voucher code. Without additional functionality, we would simply notice a new order, manually create a new discount code, and then e-mail the customer with the code. However, automating this would save us quite a lot of time, so let's look at what would be involved in doing this:

1. First, we must wait until an order has its status updated to "paid". This would either be when a payment is made online by the customer, or when an offl ine payment is received and we, as the administrator, mark the order as "paid".
2. The order contents must be searched for anything that is a purchasable voucher code.
3. For each of these vouchers purchased, a new record must be automatically inserted into the voucher_codes table with the following values:
   • vouchercode: A randomly generated string
   • active: 1
   • min_basket_cost: The amount of the voucher purchased
   • discount_operation: (because we are subtracting an amount from the cost)
   • discount_amount: The amount of the voucher purchased
   • num_vouchers: 1
   • expiry: A year in the future would be a suitable validity period
4. These vouchers would then be sent through e-mail to the customer.

Referrals

To reward loyal customers, we may wish to offer referral discounts to them. This would work by encouraging our customers to introduce new customers, and giving them a credit based off a percentage of orders placed by customers they refer to our store. Customers referring other customers would be given a referral code, which could either be part of a link used to promote the site, or given to customers to enter somewhere on the order process.

The referral process should work like this:

1. Check for a referral code in the URL.
2. If a code is found in the URL, it should be stored in a cookie, unless a previous referral code is already being stored; in that case, the older code should be used.
3. At the checkout stage, this code should be looked up, to check if it is valid and to see the commission to be applied to the customer who passed the referral. The order number, commission value, and referring customer should be stored in a database table.
4. When the order is updated to "paid" or "paid online", the commission should be applied to the relevant customer's account.

Database changes

This requires a new database table, as well as some database alterations to work.

New table: Referrers

A referrers table is required to link customers to a unique referral code, and a commission percentage. It would require the following fields:

Changes

Customers should have a credit field, showing how much credit they have with the store based on referred customers. The orders table should also be altered to store a record of any referral code used.

Functionality

The workflow of this feature would work like this:

1. An order is placed, and a referral code is associated with it.
2. The order is marked as "paid".
3. A lookup is performed on the referrers table to find the customer and the percentage.
4. The commission value is calculated.
5. The referring customer's credit value is updated to include new commission earned.

We could extend this to record a list of transactions to a customer's credit, such as dates and amounts their account was credited by, and allow reports to be generated and sent to them. However, that could occupy several chapters itself!

Checkout process consideration

This requires an important consideration when we get to the checkout stage: we must take into account any credit stored on a customer's account. If they have credit, it should be deducted from any of their own orders, to ensure they can spend the commission they earned.

Summary

We now have a number of useful features to encourage new orders and customers to our store, as well as encouraging existing customers to promote our store through affiliate codes.

This included creating a voucher code system which supported vouchers that deducted a percentage from the order total, vouchers that deducted a fixed amount from the order total, and vouchers that altered the cost of shipping to the customer. These vouchers were able to take into account expiry dates, limited-use options, and the current cost of the customer's basket.

Taking this forward, we looked at how to extend our framework to allow customers to purchase vouchers as gifts for other customers, as well as how to extend our store to support referral bonuses and incentives for our customers.

• How to calculate shipping costs based on Product, Weight, Location, and "Shipping rules"
• About third-party shipping APIs
• How to integrate shipping and tracking notifications on orders
• How to integrate tax costs into our system

Shipping

Shipping is a very important aspect of an e-commerce system; without it customers will not accurately know the cost of their order. The only situation where we wouldn't want to include shipping costs is where we always offer free shipping. However, in that situation, we could either add provisions to ignore shipping costs, or we could set all values to zero, and remove references to shipping costs from the user interface.

Shipping methods

The first requirement to calculate shipping costs is a shipping method. We may wish to offer a number of different shipping methods to our customers, such as standard shipping, next-day shipping, International shipping, and so on.

The system will require a default shipping method, so when the customer visits their basket, they see shipping costs calculated based off the default method. There should be a suitable drop-down list on the basket page containing the list of shipping methods; when this is changed, the costs in the basket should be updated to reflect the selected method.

We should store the following details for each shipping method:

• An ID number
• A name for the shipping method
• If the shipping method is active or not, indicating if it should be selectable by customers
• If the shipping method is the default method for the store
• A default shipping cost, this would:
  • Be pre-populated in a suitable field when creating new products; however, when the product is created through the administration interface, we would store the shipping cost for the product with the product.
  • Automatically be assigned to existing products in a store when a new shipping method is created to a store that already contains products.

This could be suitably stored in our database as the following:

This can be represented in the database using the following SQL:

CREATE TABLE `shipping_methods` (
`ID` INT NOT NULL AUTO_INCREMENT PRIMARY KEY ,
`name` VARCHAR( 50 ) NOT NULL ,
`active` BOOL NOT NULL ,
`is_default` BOOL NOT NULL ,
`default_cost` DOUBLE NOT NULL ,
INDEX ( `active` , `is_default` )
) ENGINE = INNODB COMMENT = 'Shipping methods';

Shipping costs

There are several different ways to calculate the costs of shipping products to customers:

• We could associate a cost to each product for each shipping method we have in our store
• We could associate costs for each shipping method to ranges of weights, and either charge the customer based on the weight-based shipping cost for each product combined, or based on the combined weight of the order
• We could base the cost on the customer's delivery address

The exact methods used, and the way they are used, depends on the exact nature of the store, as there are implications to these methods. If we were to use location-based shipping cost calculations, then the customer would not be aware of the total cost of their order until they entered their delivery address. There are a few ways this can be avoided: the system could assume a default delivery location and associated costs, and then update the customer's delivery cost at a later stage. Alternatively, if we enabled delivery methods for different locations or countries, we could associate the appropriate costs to these methods, although this does of course rely on the customer selecting the correct shipping method for their order to be approved; appropriate notifications to the customer would be required to ensure they do select the correct ones.

For this article we will implement:

• Weight-based shipping costs: Here the cost of shipping is based on the weight of the products.
• Product-based shipping costs: Here the cost of shipping is set on a per product basis for each product in the customer's basket.

We will also discuss location-based shipping costs, and look at how we may implement it. To account for international or long-distance shipping, we will use varying shipping methods; perhaps we could use:

• Shipping within state X.
• Shipping outside of state X.
• International shipping. (This could be broken down per continent if we wanted, without imposing on the customer too much.)

Product-based shipping costs

Product-based shipping costs would simply require each product to have a shipping cost associated to it for each shipping method in the store. As discussed earlier, when a new method is added to an existing store, a default value will initially be used, so in theory the administrator only needs to alter products whose shipping costs shouldn't be the default cost, and when creating new products, the relevant text box for the shipping cost for that method will have the default cost pre-populated.

To facilitate these costs, we need a new table in our database storing:

• Product IDs
• Shipping method IDs
• Shipping costs

The following SQL represents this table in our database:

CREATE TABLE `shipping_costs_product` (
`shipping_id` int(11) NOT NULL, `product_id` int(11) NOT NULL,
`cost` float NOT NULL, PRIMARY KEY (`shipping_id`,`product_id`) )
ENGINE=InnoDB DEFAULT CHARSET=latin1;

Weight-based shipping costs

Depending on the store being operated from our framework, we may need to base shipping costs on the weights of products. If a particular courier for a particular shipping method charges based on weights, then there isn't any point in creating costs for each product for that shipping method. Our framework can calculate the shipping costs based on the weight ranges and costs for the method, and the weight of the product.

Within our database we would need to store:

• The shipping method in question
• A lower bound for the product weight, so we know which cost to apply to a product
• A cost associated for anything between this and the next weight bound

The table below illustrates these fields in our database:

The following SQL represents this table:

CREATE TABLE `shipping_costs_weight` (
`ID` int(11) NOT NULL auto_increment,
`shipping_id` int(11) NOT NULL,
`lower_weight` float NOT NULL,
`cost` float NOT NULL,
PRIMARY KEY (`ID`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1 AUTO_INCREMENT=1 ;

To think about: Location-based shipping costs

One thing we should still think about is location-based shipping costs, and how we may implement this. There are two primary ways in which we can do this:

• Assign shipping costs or cost surpluses/reductions to delivery addresses (either countries or states) and shipping methods
• Calculate costs using third-party service APIs

These two methods have one issue, which is why we are not going to implement them—that is the costs are calculated later in the checkout process. We want our customers to be well informed and aware of all of their costs as early as possible.

As mentioned earlier, however, we could get round this by assuming a default delivery location and providing customers with a guideline shipping cost, which would be subject to change based on their delivery address. Alternatively, we could allow customers to select their delivery location region from a drop-down list on the main "shopping basket" page. This way they would know the costs right away.

Regional shipping costs

We could look at storing:

• Shipping method IDs
• Region types (states or countries)
• Region values (an ID corresponding to a list of states or countries)
• A priority (in some cases, we may need to only consider the state delivery costs, and not country costs; in others cases, it may be the other way around)
• The associated costs changes (this could be a positive or negative value to be added to a product's delivery cost, as calculated by the other shipping systems already)

By doing this, we can then combine the delivery address with the products and lookup a price alteration, which is applied to the product's delivery cost, which has already been calculated. Ideally, we would use all the shipping cost calculation systems discussed, to make something as flexible as possible, based on the needs of a particular product, particular shipping method or courier, or of a particular store or business.

Third-party APIs

The most accurate method of charging delivery costs, encompassing weights and delivery addresses is via APIs provided by couriers themselves, such as UPS. The following web pages may be of reference:

• http://www.ups.com/onlinetools
• http://answers.google.com/answers/threadview/id/429083.html

Using such an API, means our shipping cost would be accurate, assuming our weight values were correct for our products, and we would not over or under charge customers for shipping costs. One additional consideration that third-party APIs may require would be dimensions of products, if their costs are also based on product sizes.

Shipping rules

Hopefully by using product and/or weight-based shipping methods, we can provide accurate shipping costs; however, some couriers cap their shipping costs for dispatches, or we may wish to offer incentives such as free shipping on certain orders. We may also find that we need to charge more for shipping, depending on the customer's location.

To store these rules, we need to record:

• A name for the rule
• The shipping method the rule is associated with
• The order of the rule, so if more than one rule were applicable, they would be applied in order
• The type of match to perform, either against total product cost, or the shipping cost (product cost would allow us to offer free shipping for orders over $X, and against shipping costs allow us to cap the costs at $Y)
• The amount to match against
• The operator to compare the match amount against the product or basket cost (this would be an operator such as greater than, less than, less than or equal to, greater than or equal to, not equal to, or equal to)
• The rule amount; this would be a value that would be applied to the shipping cost by a rule operator
• The rule operator, to determine how the rule amount would be applied to the shipping cost (this would be an operator such as plus, minus, divide by, multiply by, or set value to)

The following SQL represents this in our database:

CREATE TABLE ` shipping_rules` (
`ID` int(11) NOT NULL auto_increment,
`shipping_id` int(11) NOT NULL,
`match_amount` float NOT NULL,
`match_type` enum('shipping','products') NOT NULL,
`match_operator` enum('<','>','<=','>=','<>','==') NOT NULL,
`rule` varchar(255) NOT NULL,
`rule_amount` float NOT NULL,
`rule_operator` enum('+','-','=','*','/') NOT NULL,
`order` int(11) NOT NULL,
PRIMARY KEY (`ID`),
KEY `shipping_id` (`shipping_id`,`order`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1 AUTO_INCREMENT=1 ;

Let's look at some example shipping rules, and potential values for these.

Free shipping

If we wished to offer free shipping to all customers whose orders were greater than or equal to $50, we would use the following values:

• Name: Free Shipping
• Order: 2 (assuming we use both this and the following rule)
• Type of match: Product
• Match amount: 50
• Match comparison operator: Greater than or equal to
• Rule amount: 0
• Rule operator: Set equal to

Capped shipping

If we wished to cap shipping costs to $20, to ensure no customer paid more than that, we would use the following values:

• Name: Max shipping cost
• Order: 1
• Type of match: Shipping
• Match amount: 20
• Match comparison operator: Greater than
• Rule amount: 20
• Rule operator: Set equal to

Of course we can also use these rules to do all sorts of calculations, such as discounted shipping for bulk orders, and so on. We could also extend these rules to take into account delivery locations.

Tracking

When products are shipped to customers, they may wish to be informed about tracking information. It may be possible for us to integrate with shipping provider APIs to do this. However, the simplest method (which could also eventually be integrated with such an API) is to allow store administrators to supply a message to the customer when they update an order's status to "dispatched".

Integrating shipping costs into the basket

We should integrate these shipping cost systems into our framework in the following stages:

1. Prepare list of shipping methods and a default method.
2. Calculate product-based shipping costs.
3. Calculate weight-based shipping costs.
4. Consider shipping rules and adjust shipping costs accordingly.

Shipping methods and a default

We can store a default shipping method in the framework's settings. When a customer selects an alternative shipping method, we should store that in an appropriate session variable. At this stage, all we need to do is check if the session variable is set. If the session variable is set, then that is the shipping method we must use; if it is not, then we must use the default shipping method.

// get the shipping method
if( isset( $_SESSION['shipping_method'] ) )
{
// user-selected
$this->shippingMethodID = intval( $_SESSION['shipping_method'] );
}
else
{
// system default
$this->shippingMethodID = $this->registry->
getSetting('default_shipping_method');
}

Calculating shipping costs based on products

To calculate shipping costs based on products, we need to lookup the shipping cost for each product in the basket associated with the current shipping method.

// shipping costs: product based
$shippingCosts = $this->getShippingProductCosts( $this->productIDs );

Once we have these shipping costs, it is a case of looking up the product ID in the $shippingCosts array to get the shipping cost, and multiplying this by the quantity of the product in the basket.

$this->shippingCost = $this->shippingCost + ( $shippingCosts[
$contents['product_id'] ] * $contents['product_quantity'] );

Calculating shipping costs based on product weights

To calculate shipping costs based on product weight, we must build an array of shipping costs based on weight ranges.

// shipping costs: weight based
$weightCosts = $this->getShippingWeightCosts();

Once we have our array of shipping weight costs, while iterating through products in the basket, we then iterate through the ordered weights until we find an upper limit to the product in question. Once found, we get our shipping cost. This cost is then multiplied by the quantity of the product in the basket, and added to the rolling shipping cost.

// shipping costs: weight based
$currentWeight = 0;
while( $weightFound == false )
{
if( $contents['product_weight'] >=
$weightCosts[$currentWeight]['weight'] )
{
$weightFound = true;
$this->shippingCost = $this->shippingCost +
( $weightCosts[$currentWeight]['cost'] *
$contents['product_quantity'] );
}
else
{
if( count( $weightCosts ) == $currentWeight )
{
// we don't want to do this forever!
$weightFound = true;
}
else
{
$currentWeight++;
}
}
}

Considering shipping rules, and adjusting prices accordingly

The final shipping feature is shipping rules; this requires us looking up the shipping rules from the database, and iterating through them. For each rule, we need to check the type of rule, then check if the shipping cost or the basket cost is at least that of the rule amount; if it is, then we perform our rule calculation.

/**
* Takes any shipping rules into account with regards to the shipping
costs
* @return void
*/
private function considerShippingRules()
{
// get the rules
$rules_sql = "SELECT * FROM shipping_rules
WHERE shipping_id={$this->shippingMethodUD}
ORDER BY `order`";
$this->registry->getObject('db')->executeQuery( $rules_sql );
// go through them
while( $rule = $this->registry->getObject('db')->getRows() )
{
// rule depends on the shipping cost

Here we have established that the current rule is based on shipping cost, which means we then check to see if the shipping cost meets the rule.

if( $rule['match_type'] == 'shipping' )
{
$match = false;
$match_operator = $rule['match_operator'];
// check to see our shipping cost meets the rule
if( $match_operator == '==' )
{ if( $this->shippingCost == $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '<>' )
{ if( $this->shippingCost <> $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '>=' )
{ if( $this->shippingCost >= $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '<=' )
{ if( $this->shippingCost <= $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '>' )
{ if( $this->shippingCost > $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '<' )
{ if( $this->shippingCost < $rule['match_amount'] )
{ $match = true; } }

If a rule match was found, we then take the rule into account.

if( $match == true )
{
// set the shipping cost based on the rule operator and
// the rule amount
$rule_operator = $rule['rule_operator'];
if( $rule_operator == '=' )
{ $this->shippingCost = $rule['rule_amount']; }
elseif( $rule_operator == '+' )
{ $this->shippingCost = $this->shippingCost
+ $rule['rule_amount']; }
elseif( $rule_operator == '-' )
{ $this->shippingCost = $this->shippingCost
- $rule['rule_amount']; }
elseif( $rule_operator == '*' )
{ $this->shippingCost = $this->shippingCost
* $rule['rule_amount']; }
elseif( $rule_operator == '/' )
{ $this->shippingCost = $this->shippingCost
/ $rule['rule_amount']; }
}
}

If the product is based on the basket cost, we then do the same as before, except that the rule matching depends on the cost of the shopping basket.

elseif( $rule['match_type'] == 'products' )
{
// rule depends on the basket cost
$match = false;
$match_operator = $rule['match_operator'];
// check to see our basket cost meets the rule
if( $match_operator == '==' )
{ if( $this->shippingCost == $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '<>' )
{ if( $this->cost <> $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '>=' )
{ if( $this->cost >= $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '<=' )
{ if( $this->cost <= $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '>' )
{ if( $this->cost > $rule['match_amount'] )
{ $match = true; } }
elseif( $match_operator == '<' )
{ if( $this->cost < $rule['match_amount'] )
{ $match = true; } }
if( $match == true )
{
// set the shipping cost based on the rule operator
// and the rule amount
$rule_operator = $rule['rule_operator'];
if( $rule_operator == '=' )
{ $this->shippingCost = $rule['rule_amount']; }
elseif( $rule_operator == '+' )
{ $this->shippingCost = $this->shippingCost
+ $rule['rule_amount']; }
elseif( $rule_operator == '-' )
{ $this->shippingCost = $this->shippingCost
- $rule['rule_amount']; }
elseif( $rule_operator == '*' )
{ $this->shippingCost = $this->shippingCost
* $rule['rule_amount']; }
elseif( $rule_operator == '/' )
{ $this->shippingCost = $this->shippingCost
/ $rule['rule_amount']; }
}
}
}
}

CREATE TABLE `tax_codes` (
`ID` INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
`tax_code` varchar(255) NOT NULL,
`calculation_value` DOUBLE NOT NULL,
`calculation_operation` ENUM( '+', '-', '*', '/', '=' ) NOT NULL,
INDEX ( `tax_code` )
) ENGINE = INNODB;

In this recipe, I discuss all the code necessary to use Ajax to go from a simple Web page to a JavaScript function to an XMLHttpRequest to a PHP script and, finally, to an Oracle database. Along with the code, I do talk about the individual pieces with respect to the whole picture: what each chunk does and why it's important. By reading this HowTo, you will acquire not only some sample code but also, hopefully, a broader understanding of the whole Ajax concept.

Background

The example I'll be working with will be a registration form (or a minimal part of it, anyway). The theory is that I must confirm unique email addresses in the users table so that people cannot register multiple times using the same address. This is normally part of the validation process that comes after the user submits the form to the handling PHP script. But why should the user have to wait until then for this piece of validation? Instead, as soon as the user enters their email address and goes to the next form field, the email address will be immediately validated. But to do so, I still need to query the database, which is where Ajax comes in.

The simplified table structure for this example could be created with the following SQL statement (without the presence of the other tables, I've done away with identifying keys and such).

CREATE TABLE users (
	email VARCHAR2(60)
)

Obviously you could expand on this in many ways. For now, though, the important thing is that the sample code assumes you have established such a table and can connect to it from a PHP script. Some records must be in this table for the example to fully function, so you should populate it like so:

INSERT INTO users (email) VALUES ('this@that.com')
INSERT INTO users (email) VALUES ('me@school.edu')
INSERT INTO users (email) VALUES ('fake@address.net')

After you've created and populated the table, you can begin coding. As I mentioned, there are two scripts involved. To develop and test everything, you will:

1. Create the PHP script that queries the Oracle database.
2. Manually test the PHP script to see how it works.
3. Write the JavaScript code that interacts with the PHP script.
4. Make the HTML form that ties into the JavaScript.
5. Test the entire process.

Step 1: Programming the Database Query

The entire PHP script is called ajax.php. (See sample code zip.) The purpose of this script is to run a query in Oracle and print a message based upon the results of the query. This is all very basic Oracle, SQL, and PHP, but I'll run through it to clarify what's happening.

The script expects to receive an email address in the URL, which is available in the variable $_GET['email']. Then the script connects to the Oracle database. The query itself counts how many records in the users table have that email address:

SELECT COUNT(*) AS NUM_ROWS FROM users WHERE email='{$_GET['email']}'

This should return either 0 or 1 (or nothing at all). The query is executed in Oracle and the results are bound to the PHP $rows variable. Now $rows represents how many records in the database have that email address. With respect to Ajax, the important part of the script is shown below.

if ($rows > 0) {
	echo 'Email address has already been registered!';
} else {
	echo 'Email address is available!';
}

One of those two messages will be printed, based upon the value of $rows. That's all there is to this page! Absolutely no HTML is needed as this script won't be used like a standard Web page.

If you want to improve this script, you can confirm that the email address matches a regular expression pattern for email addresses. If so, execute the query like normal; if not, echo a statement saying that it's not a valid email address. At the very least, you'd likely want to prevent SQL injection attacks. (I.e., avoid using the $_GET variable in your query without some assurances of its validity.)

Step 2: Testing the PHP Script

Because this entire Ajax process involves several technologies—HTML, JavaScript, PHP, SQL, and Oracle—you'll be best off testing each piece as you go. If you don't, you can easily get lost trying to find where a problem exists. Testing this PHP script should be fairly easy:

1. Make sure you've created the table in Oracle and populated it.
2. Edit ajax.php so that it uses valid connection parameters for your Oracle installation.
3. Save the script as ajax.php.
4. Place it in the proper directory for your Web server.
5. Go to http://yoururl/ajax.php?email=X in your Web browser.

In place of X, use one of the email addresses that's already in the database (e.g., http://yoururl/ajax.php?email=this@that.com). You should see the "Email address has already been registered!" message. Then use an email address that has not been stored. You should see the "Email address is available!" text. Once you have that working, you can move on to the actual Ajax aspect of this example.

Step 3: Programming the JavaScript

This section of the process is probably the most difficult unless you've done tons of JavaScript already. In any case, the JavaScript code is the heart of the Ajax process, as it performs and handles the request from the PHP page. I'll go through this code in detail.

The JavaScript code will define three functions. The first creates a request object variable:

function createRequestObject() {
	var ro;
	if (navigator.appName == "Microsoft Internet Explorer") {
		ro = new ActiveXObject("Microsoft.XMLHTTP");
	} else {
		ro = new XMLHttpRequest();
	}
	return ro;
}

You should be able to use this code for any Ajax application without modification. If the Web browser being used is Microsoft Internet Explorer, then the ro variable is initialized as an ActiveXObject of type Microsoft.XMLHTTP. For all other browsers, ro is a straightforward XMLHttpRequest type of object. That's really nothing else to it. The ro variable is now an object with all the necessary functionality to perform an asynchronous request. After creating the request object variable, this function then returns it.

This function is immediately called by the JavaScript code when the page is first loaded:

var http = createRequestObject();

Now http represents the object and is globally available in the other functions.

Next up is the function that calls the PHP script:

function sendRequest(email) {
	http.open('get', 'ajax.php?email=' + encodeURIComponent(email));
	http.onreadystatechange = handleResponse;
	http.send(null);
}

This function takes one argument, which is the email address to be verified. Then it opens a connection to the PHP script. As the first argument in the open() method indicates, the request will be of type get, as opposed to post. The email address is appended to the URL, resulting in a page request like ajax.php?email=this@that.com. As you already know, this is how the PHP script is properly called. The encodeURIComponent() function just encodes the submitted value to make it URL-safe. The third line within the function tells the object what JavaScript function to call after the request has been made. The final line actually makes the request.

To recap, the first function, createRequestObject(), makes the object variable that's needed. The second function, sendRequest(), makes the actual request of the PHP script. Now we need a function that handles that request:

function handleResponse() {
	if (http.readyState == 4) {
		document.getElementById('email_label').innerHTML = http.responseText;
	}
}

The previous function told the request object to call this function after the request has been made. This function first checks that the request was successfully made. If so, then http.readyState will be equal to 4. It could also be equal to 0 through 3 (you can search online for their actual meanings, if you care), but being equal to 4 means the request worked. The results of the request will be stored in the http.responseText attribute, the results being either of the two messages echoed by the PHP script. To be clear, if the request worked, then http.responseText will either be "Email address has already been registered!" or "Email address is available!".

At this point, the JavaScript knows what the result of the PHP script was. All you need to do is get the JavaScript to notify the user of that result. An easy option would be to use an alert() box:

alert(http.responseText);

If you put this within the conditional, you'll see the result when you test the whole application. (In fact, alert() is a great debugging tool to confirm what's going on in your JavaScript code.) However, I find these alerts to be annoying as an end user and would rather print the message next to the form's email input. To do so, I refer to the DOM (Document Object Model). Specifically, I assign the http.responseText to an element in my page called email_label. You'll see this in Step 4.

Whew! Hopefully you followed all that. To repeat, this is the most important and most complex part of this sequence. The JavaScript uses three functions to do three things: define a browser-specific request object; make a request to the PHP script; and, do something with the results of the request. If you're confused by any of this, or when it comes time to make a more complex Ajax application, you'll likely want to do a little research on JavaScript and DOM.

Step 4: Making a JavaScript-functional HTML Form

As I wrote previously, the premise behind this example is a registration form that takes, at the least, an email address. The minimal form would be:

<form action="somepage.php" method="post">
Email Address: <input name="email" type="text" size="30" maxlength="60" /><br />
First Name: <input name="first_name" type="text" size="20" maxlength="20" /><br />
(Rest of the form...)
</form>

That's it! Well, not quite. You'd want more inputs (a "submit" button, and so on). But for the purposes of this example, that's all you need. To avoid confusion, note that the action and method attributes here have nothing to do with the ajax.php script (which doesn't handle this form's submission).

Two more things are required, though. First, this form must somehow call the JavaScript code that makes the request. You could use several tricks to do that: make a clickable link, wait for the submit button to be clicked, and so on. I've decided that once the user has entered an email address and has gone on to the next form element, the JavaScript should be called. This requires the onchange() method, which I'll add to the email input:

Email Address: <input name="email" type="text" size="30" maxlength="60"

onchange="sendRequest(this.form.email.value)" />

As soon as the user changes the value in this input, including entering anything for the first time, and then tabs or clicks to another input, the JavaScript sendRequest() function will be called. It is fed one argument, the value of the email form input. If you look back at the JavaScript code, you can see how the value typed here gets sent to that function, which in turn is sent to the PHP script.

The second thing the HTML form needs is a place where JavaScript can "write" the received message so that it's visible to the user. As the handleResponse() function dictates, that message will be assigned to the innerHTML of an element called email_label. For this I add a span with that ID after the email address input:

<span id="email_label"></span>

That's it for tying the HTML form to the JavaScript. (See Listing 1 in the sample code zip for the final code.) Now it's time to see how it works!

Step 5: Testing the Ajax Process

Having completed the HTML and JavaScript, you should save that as ajax.html (or anything, really), then place it in the same directory as the PHP script. Load the form by running it in your Web browser, through a URL, not by opening it from the file system (i.e, go to http://yoururl/ajax.html). Type an unused email address in the proper input, then tab or click on the next input. Repeat using a stored email address.

The two screenshots below show the results you should see. Absolute magic!

Conclusion

In this article you've seen how you can easily implement an Ajax process using PHP and Oracle. By doing so, server side validation is being accomplished within the client (although you should still keep server side validation as well, in case JavaScript is disabled). This particular example, in my opinion, demonstrates a nice feature for an end user, saving them from having to:

• Submit the form
• See that the email address has already been registered
• Return to the form
• Repeat

Also, I think this example and the concept in general is kind of cool. And on the Web, that's not an insignificant factor.

Of course, there's tons more you can do with Ajax, PHP, and Oracle. The example in this article sent only one piece of data to the PHP script and retrieved just a string. You can send much more back and forth. If you have a significant amount of data to be returned to the calling page, you can have PHP return it in XML format, then use JavaScript to parse and display it. If you search online, you'll find many different examples.

Larry Ullman

Foreword

As you read on you'll see that I advocate the use of a hashing algorithm called Secure Hashing Algorithm 1 (or SHA-1). Since I wrote this article, a team of researchers – Xiaoyun Wang, Yiqun Lisa Yin, and Hongbo Yu – have shown SHA-1 to be weaker than was previously thought. This means that for certain purposes such as digital signatures, stronger algorithms like SHA-256 and SHA-512 are now being recommended. For generating password hashes, SHA-1 still provides a more than adequate level of security for most applications today. You should be aware of this issue however and begin to think about using stronger algorithms in your code as they become more readily available.

For more information please see Bruce Schneier's analysis of the issue at http://www.schneier.com/blog/archives/2005/02/cryptanalysis_o.html

What Is A Hash?

A hash (also called a hash code, digest, or message digest) can be thought of as the digital fingerprint of a piece of data. You can easily generate a fixed length hash for any text string using a one-way mathematical process. It is next to impossible to (efficiently) recover the original text from a hash alone. It is also vastly unlikely that any different text string will give you an identical hash – a 'hash collision'. These properties make hashes ideally suited for storing your application's passwords. Why? Because although an attacker may compromise a part of your system and reveal your list of password hashes, they can't determine from the hashes alone what the real passwords are.

So How Do I Authenticate Users?

We've established that it's incredibly difficult to recover the original password from a hash, so how will your application know if a user has entered the correct password or not? Quite simply – by generating a hash of the user-supplied password and comparing this 'fingerprint' with the hash stored in your user profile, you'll know whether or not the passwords match. Let's look at an example:

User Registration And Password Verification

During the registration process our new user will provide their desired password (preferably with verification and through a secure session). Using code similar to the following, we store their username and password hash in our database:

Figure 1. Our user enters their preferred access details

<?php

/* Store user details */

$passwordHash = sha1($_POST['password']);

$sql = 'INSERT INTO user (username,passwordHash) VALUES (?,?)';
$result = $db->query($sql, array($_POST['username'], $passwordHash));

?>

The next time our user logs in, we check their access credentials using similar code as follows:

Figure 2. Logging back in

<?php

/* Check user details */

$passwordHash = sha1($_POST['password']);

$sql = 'SELECT username FROM user WHERE username = ? AND passwordHash = ?';
$result = $db->query($sql, array($_POST['username'], $passwordHash));
if ($result->numRows() < 1)
{
    /* Access denied */
    echo 'Sorry, your username or password was incorrect!';
}
else
{
    /* Log user in */
    printf('Welcome back %s!', $_POST['username']);
}

?>

Types Of Hashes

There are a number of strong hashing algorithms in use, the most common of which are MD5 and SHA-1. Older systems – including many Linux variants – used Data Encryption Standard (DES) hashes. With only 56 bits this is no longer considered an acceptably strong hashing algorithm and should be avoided.

Examples

In PHP you can generate hashes using the md5() and sha1 functions. md5() returns a 128-bit hash (32 hexadecimal characters), whereas sha1() returns a 160-bit hash (40 hexadecimal characters). For example:

<?php

$string = 'PHP & Information Security';
printf("Original string: %s\n", $string);
printf("MD5 hash: %s\n", md5($string));
printf("SHA-1 hash: %s\n", sha1($string));

?>

This code will output the following:

Original string: PHP & Information Security
MD5 hash: 88dd8f282721af2c704e238e7f338c41
SHA-1 hash: b47210605096b9aa0129f88695e229ce309dd362

In MySQL you can generate hashes internally using the password(), md5(), or sha1 functions. password() is the function used for MySQL's own user authentication system. It returns a 16-byte string for MySQL versions prior to 4.1, and a 41-byte string (based on a double SHA-1 hash) for versions 4.1 and up. md5() is available from MySQL version 3.23.2 and sha1() was added later in 4.0.2.

mysql> select PASSWORD( 'PHP & Information Security' );
+------------------------------------------+
| PASSWORD( 'PHP & Information Security' ) |
+------------------------------------------+
| 379693e271cd3bd6                         |
+------------------------------------------+
1 row in set (0.00 sec)

mysql> select MD5( 'PHP & Information Security' );
+-------------------------------------+
| MD5( 'PHP & Information Security' ) |
+-------------------------------------+
| 88dd8f282721af2c704e238e7f338c41    |
+-------------------------------------+
1 row in set (0.01 sec)

Note: Using MySQL's password() function in your own applications isn't recommended – the algorithm used has changed over time and prior to 4.1 was particularly weak.

You may decide to use MySQL to calculate your hash rather than PHP. The example of storing our user's registration details from the previous section then becomes:

<?php

/* Store user details */

$sql = 'INSERT INTO user (username, passwordHash) VALUES (?, SHA1(?))';
$result = $db->query($sql, array($_POST['username'], $_POST['password']));

?>

Weaknesses

As a security measure, storing only hashes of passwords in your database will ensure that an attacker's job is made that much more difficult. Let's look at the steps they'll now take in an effort to compromise your system. Assuming that they've managed to access your user database and list of hashes, there's no way that they can then recover the original passwords to your system. Or is there?

The attacker will be able to look at your hashes and immediately know that any accounts with the same password hash must therefore also have the same password. Not such a problem if neither of the account passwords is known – or is it? A common technique employed to recover the original plain text from a hash is cracking, otherwise known as 'brute forcing'. Using this methodology an attacker will generate hashes for numerous potential passwords (either generated randomly or from a source of potential words, for example a dictionary attack). The hashes generated are compared with those in your user database and any matches will reveal the password for the user in question.

Modern computer hardware can generate MD5 and SHA-1 hashes very quickly – in some cases at rates of thousands per second. Hashes can be generated for every word in an entire dictionary (possibly including alpha-numeric variants) well in advance of an attack. Whilst strong passwords and longer pass phrases provide a reasonable level of protection against such attacks, you cannot always guarantee that your users will be well informed about such practices. It's also less than ideal that the same password used on multiple accounts (or multiple systems for that matter) will reveal itself with an identical hash.

Making It Better

Both of these weaknesses in the hashing strategy can be overcome by making a small addition to our hashing algorithm. Before generating the hash we create a random string of characters of a predetermined length, and prepend this string to our plain text password. Provided the string (called a "salt") is of sufficient length – and of course sufficiently random – the resulting hash will almost certainly be different each time we execute the function. Of course we must also store the salt we've used in the database along with our hash but this is generally no more of an issue than extending the width of the field by a few characters.

When we validate a user's login credentials we follow the same process, only this time we use the salt from our database instead of generating a new random one. We add the user supplied password to it, run our hashing algorithm, then compare the result with the hash stored in that user's profile.

<?php

define('SALT_LENGTH', 9);

function generateHash($plainText, $salt = null)
{
    if ($salt === null)
    {
        $salt = substr(md5(uniqid(rand(), true)), 0, SALT_LENGTH);
    }
    else
    {
        $salt = substr($salt, 0, SALT_LENGTH);
    }

    return $salt . sha1($salt . $plainText);
}

?>

Note: The function above is limited in that the maximum salt length is 32 characters. You may wish to write your own salt generator to overcome this limit and increase the entropy of the string.

Calling generateHash() with a single argument (the plain text password) will cause a random string to be generated and used for the salt. The resulting string consists of the salt followed by the SHA-1 hash – this is to be stored away in your database. When you're checking a user's login, the situation is slightly different in that you already know the salt you'd like to use. The string stored in your database can be passed to generateHash() as the second argument when generating the hash of a user-supplied password for comparison.

Using a salt overcomes the issue of multiple accounts with the same password revealing themselves with identical hashes in your database. Although two passwords may be the same the salts will almost certainly be different, so the hashes will look nothing alike.

Dictionary attacks with pre-generated lists of hashes will be useless for the same reason – the attacker will now have to recalculate their entire dictionary for every individual account they're attempting to crack.

Summary

We've seen now what hashes are and why you should store them instead of the plain text passwords they represent in your database. The examples above are a starting point and will get you on the right track with using hashes in your PHP applications. A little bit of work now may well mean much less of a headache further down the track!

Since Oracle8i, Oracle Database has included a security feature known as Virtual Private Database (VPD). A VPD lets you define, build and apply security policies. These security policies can restrict user access to specific tables or parts of tables. The policies let you manage access privileges for scheme by examining session level data, which the database creates when a user connects to an Oracle instance. VPD implementation requires a common repository schema that grants privileges to distinct scheme. Your user-defined database design must also provide a striping column in common repository tables. The access to these tables is then managed by the VPD policies.

VPD technology relies on the connection data stored in the database catalog. The connection data identifies and tracks activities of a schema (user). All but one field of this connection metadata is defined and managed by the Oracle database. The CLIENT_INFO column is available for developers to use when building user-defined applications. You can combine the session CLIENT_INFO column with a database column to stripe data at a granularity below schema and support multiple users in a single schema. Oracle E-Business 11i Suite stripes multiple organizations and currencies through views using the CLIENT_INFO column.

The combination of these technologies let you implement fine grained access privileges and roles through security policies. Alternatively, you can manage fine grained access by bundling the CLIENT_INFO column into your authentication model.

Oracle Database Connection Architecture

The Oracle Database connection architecture has two facets that you should understand as a PHP programmer. First, the actual database connection is known as a database event and has a unique internally maintained numeric value. Every database connection creates a row of metadata in the system catalog. The row exists for the length of the connection and can be queried by any user with DBA role privileges from the V$SESSION view. The value of the SESSIONID in the database is unique and unrelated to the PHP session_id() function return value. Second, you have only one database SESSIONID value when you open a persistent connection with the oci_pconnect() function, while you can have more than one SESSIONID value when opening non-persistent connections.

The oci_connect() and oci_new_connect() functions create new SESSIONID values each time they run. Only the first oci_pconnect() function call creates a SESSIONID value but subsequent oci_pconnect() function calls reuse the open session. This reduces the dynamic marshalling expense required to build a new connection and enables preservation of state information between web pages and the database server. It is also possible for you to have two or more open non-persistent connections in the scope of a single PHP session or response-acknowledgment request cycle.

Virtual Private Database Architecture

The VPD architecture works by combining the connection metadata and user-defined security policies in a separate security schema. Security policies are procedural programming instructions written in PL/SQL stored functions. The policy functions have two formal parameters by default — one is a string representing an Oracle schema (also known as a user account), and the other is a table name. These policy functions return a variable length string that is appended to a WHERE clause for any SQL statement against the table. The WHERE clause lets you restrict the rows your users can query and transact against. You restrict access by filtering data on a qualifying column like an organization unit or security group role. Filtered tables are known as striped tables or views.

You implement a VPD by creating a schema/user, like SECURITY_ADMIN, and granting the schema access to the SYS.DBMS_RLS stored package. The DBMS_RLS package lets you add, maintain, and remove security policies. Then you can define policy stored functions in the SECURITY_ADMIN schema and add them as policies using the DBMS_RLS package.

The policies maintain a barrier around the data, which is typically located in another schema. The schema that owns the tables then grants access and transaction privileges to one or more other schemas. This configuration structure is similar to the default definer rights model for stored procedures in an Oracle database. Stored procedures act by default with the privileges of the schema where they are created.

In a classic definer rights model, the owning schema does not typically grant access and transaction rights to tables and views to other users. The schema grants only execute privileges on their stored procedures. The stored procedures guarantee that users access and transact against the data in a planned way. Unfortunately, the definer rights model does not enable slicing the data into roles based on the accessing source — user or schema.

Combining the policies of VPDs with the definer rights model lets you slice the data into pieces based on assigned roles and privileges. It does this because the tables are now accessed like subsets, by effectively creating views.

Figure 1 illustrates the idea that four users see different slices or views data.

Figure 1 Definer Rights Model

Dividing data into views is done by adding a striping column to a table. You can map striping columns against a schema name in the VPD security policy function. You can also stripe the table on a column value other than database schema names.

Figure 2 illustrates how a numeric pseudo key column, SYSTEM_USER_GROUP_ID in the SYSTEM_USER table, lets you group users by a common value.

Figure 2 A Striped Table

The 0 or 1 allows you to distinguish between and group by super and end users respectively. The SYSTEM_USER_GROUP_ID column values are pseudo keys, or numeric sequence values that typically map to descriptions found in another table. This striping model works well when users are not database scheme.

Schema-level security is a common approach that is consistent with traditional approaches to definer rights data models. This user level security approach lets you map non-scheme user accounts as striping column values. You can implement a VPD either way. The next two subsections describe the basic mechanics for both security approaches.

Schema Level Security Model

The schema level security model is straightforward to implement. It requires that all users are scheme. This is typically an undesirable business model and poses significant administrative burdens because of the expense associated with grants and synonym maintenance activities.

In this model, your policy functions secure the schema by querying the context information from the stored session metadata. Only the SYS_CONTEXT() function can secure the connection schema name. You call the SYS_CONTEXT() function inside your policy function as shown in the following sample pseudo code:

CREATE OR REPLACE FUNCTION policy_user_maintenance
( schema           VARCHAR2
, tab              VARCHAR2 )
RETURN VARCHAR2 IS

  -- Define local variables.
  schema_name      VARCHAR2(30);
  where_clause     VARCHAR2(100);

BEGIN
  -- Get schema name.
  schema_name := SELECT SYS_CONTEXT('userenv ','session_user ') FROM dual;

  CASE schema_name
    WHEN user_a THEN
       ... qualifying logic ...
    WHEN user_b THEN
       ... qualifying logic ...
    WHEN user_c THEN
       ... qualifying logic ...
    ELSE
       ... qualifying logic ...
  END CASE;

  -- Return where clause.
  RETURN where_clause;

END policy_user_maintenance;
/

An implementation of a real POLICY_USER_MAINTENANCE() function like the example shell works only when users are scheme. Your PHP programs would require authentication, then each connect statement would become dynamic. This means that each PHP connection function call would need to have access to various scheme credentials. While this is an ugly solution, it is doable–albeit not likely a production solution that qualifies you for a bonus.

A better solution is possible. You achieve it by supplementing the context information stored in the session metadata. This is done by writing information to the CLIENT_INFO column in the V$SESSION view as discussed in the next subsection. The CLIENT_INFO column is a 64 character user-defined string in the session metadata.

User Level Security Model

The user level security model requires more effort to implement than the schema level model. You implement user level security by a three step process. You (a) authenticate credentials against your ACL, (b) write your authenticated credentials to the context information stored in the session metadata, and (c) write your profile stored functions to validate against the user defined context information stored in the session metadata.

Authenticating Credentials. While you have discretion as to how you implement your authentication, you should keep it simple. Assuming that you have adopted a similar SYSTEM_USER table as your ACL, you can authenticate against the user name and password in the table. Then, you can get a copy of the primary key column value, and use the primary key value as your context identifier in the session metadata. This eliminates upper, lower and mixed case validations but it can also appear as a magic number solution.

Reading and Writing Credentials to Session Metadata

The process of writing to and reading from the session CLIENT_INFO column requires you to use the DBMS_APPLICATION_INFO package. You use the SET_CLIENT_INFO procedure in the DBMS_APPLICATION_INFO package to write data into the 64 character CLIENT_INFO column found in the V$SESSION view. The following anonymous PL/SQL block assumes that the SYSTEM_USER_ID column value is 1:

BEGIN
   -- Write value to V$SESSION.CLIENT_INFO column.
   DBMS_APPLICATION_INFO.SET_CLIENT_INFO('1 ');
END;
/

You can now read this value by calling the READ_CLIENT_INFO() procedure. You should enable SERVEROUTPUT using SQL*Plus to see the rendered output when you run the following program:

DECLARE
  client_info      VARCHAR2(64);
BEGIN
   -- Read value from V$SESSION.CLIENT_INTO column.
   DBMS_APPLICATION_INFO.READ_CLIENT_INFO(client_info);

   -- Print it to console.
   DBMS_OUTPUT.PUT_LINE('[ '||client_info||']');
END;
/

User-defined session columns let you store unique information related to user credentials from your ACL. You assign a session column value during user authentication. Then, the session CLIENT_INFO column allows you to manage multiple user interactions in a single schema. Authenticated users can access whole or partial rows from tables when their session CLIENT_INFO column value matches a striping column values in the table.

Writing a Security Profile Stored Procedure. Your policy functions secure the user-defined CLIENT_INFO column value by querying the context information from the stored session metadata. Both the USERENV() and SYS_CONTEXT() functions can secure the user-defined column value.

You can use the USERENV() or SYS_CONTEXT() function to query database session metadata. You can also use these functions when you are unsure if your user account has the DBA role privilege. The SYS_CONTEXT() function is more flexible and provides greater access to the session metadata, and you should use it in lieu of the older USERENV() function. The following demonstrates how you check whether you have the DBA role by using the SYS_CONTEXT() function:

SELECT   sys_context('userenv ', 'isdba ')
FROM     dual;

The query will return a Boolean true when you have the DBA role and false when you do not have the role. The SYS_CONTEXT() function provides an alternative to querying the V$SESSION view for connection information, and is available to restricted permission scheme.

You change the previously discussed policy function by replacing the SCHEMA_NAME variable with the CLIENT_INFO variable. Then, you use the SYS_CONTEXT function to select the current CLIENT_INFO column value from the session metadata. All remaining logic in the security policy procedure would also require changes from the schema name to the user-defined CLIENT_INFO column value. The following shows a revised pseudo-code security policy function for a user-level security management procedure:

CREATE OR REPLACE FUNCTION policy_user_maintenance
( client_info      VARCHAR2
, tab              VARCHAR2 )
RETURN VARCHAR2 IS

  -- Define local variables.
  client_info_name VARCHAR2(64);
  where_clause     VARCHAR2(100);

BEGIN
  -- Get schema name.
  client_info_name := SELECT SYS_CONTEXT('userenv ','client_info ') FROM dual;

  CASE client_info_name
    WHEN user_a THEN
       ... qualifying logic ...
    WHEN user_b THEN
       ... qualifying logic ...
    WHEN user_c THEN
       ... qualifying logic ...
    ELSE
       ... qualifying logic ...
  END CASE;

  -- Return where clause.
  RETURN where_clause;

END policy_user_maintenance;
/

Authentication Process Model

This section provides an authentication solution that uses the CLIENT_INFO session column and striped tables. Rather then introduce the complexity of setting up a security administration schema and policy function, the solution uses a striped view. Striped views contain WHERE clauses that join user session data values to the striping column values. This approach mimics the dynamic WHERE clauses built by VPD security functions. Oracle E-Business Suite uses this technique to access dynamic views containing user specific organization and reporting currency data.

The authentication process model depends on the same two tables introduced in Part 1. These tables are shown in Figure 3.

Figure 3 Basic Authentication Data Model

While there is no change in the definition of the tables, this authentication model implements programming logic that takes advantage of data striping provided by the SYSTEM_USER_GROUP_ID column in the SYSTEM_USER table.

The authentication model stripes only for super and end users, which are the administration and employee groups respectively. You can identify super users by querying the database and checking the SYSTEM_USER_GROUP_ID column for a value of one. End users will have a value greater than or equal to 1. The PHP scripts read the SYSTEM_USER_GROUP_ID to set the form session as a super or end user; and they set the CLIENT_INFO column values using the DBMS_APPLICTION_INFO package to read data from striped views.

The balance of this section discusses how to setup and experiment with the test application before analyzing the code and identify management solution. The sample schema and code differ from that in Part 1 and they use a different database schema. This enables you to have both sample code trees up and running on your system for comparison purposes.

Setup Test Application. The demonstration application uses an Oracle schema named IDMGMT2, and the password is the same as the schema. You can create the user and environment by following these steps:

1. Log into the database as the privileged SYSTEM user and run the following commands. You must explicitly grant the CREATE ALL VIEWS permission when using Oracle 10g due to changes in how the RESOURCE role works:

SQL> CREATE USER IDMGMT2 IDENTIFIED BY IDMGMT2;
SQL> GRANT CONNECT, RESOURCE TO IDMGMT2;
SQL> GRANT CREATE ALL VIEWS TO IDMGMT2;

2. Connect to the new user schema:

SQL> CONNECT IDMGMT2/IDMGMT2@XE

3. Run the create_identity_db2.sql script in the IDMGMT2 schema to create all necessary objects and seed the SYSTEM_USER table:

SQL> @create_identity_db2.sql

4. Place the following files in your htdocs directory or a subdirectory of the htdocs directory:

 • SignOnUserAdmin.php
 • UserAdmin.php
 • UserView.php

These steps complete the setup necessary for our purposes here. You can now experiment with either the realm or session identification management examples.

Experiment with Session Authentication. You can experiment with the realm identity management by following these steps:

1. Open the realm identification management examples by using the following URL:

http://localhost/SignOnUserAdmin.php

2. You can use either of the following seeded accounts as valid credentials using Basic HTTP/HTTPS authentication. Make sure you don't have the cap lock enabled because they are case sensitive.

Figure 4 Cookie and Session Login page

You will be presented with the following page, where you should login as a privileged user in this test system, using the "administrator" user name and "welcome" password credentials, and not the restricted privilege "guest" user.

After authenticating your credentials, the program transfers you to the New User (UserAdmin.php) form. You should notice that there are changes from the prior New User (AddDBUser.php) form. The form now supports entering new users as belonging to either the administration or employee group, and the form provides a view to see entered users. The administration group members have privileges to add new users while the employee group's privileges are restricted and unable to add new users.

3. You can now enter a user in both the administration or employee groups. The administration group is a super user group and the employee group is for end users. You should enter both of the following users:

Make sure you don't have the cap lock enabled because entries are case sensitive. If the Administration Group radio button is not clicked, you should click it when entering Indiana Jones. Click the Employee Group radio button before entering Marion Ravenwood. You will use both accounts in subsequent navigation steps.

Figure 5 Cookie and Session Login Page

The administrative group is the default for the New User (UserAdmin.php) form. When you create an administrative group user, the SYSTEM_USER_GROUP_ID column gets a 0 value. Creating a new user in the employee group inserts a value of 1 in the same column. Users who are defined in the administration group have the privilege to create other users, while those in the employee group cannot create new users.

After you enter Indiana Jones and Marion Ravenwood, you will see the New User form, as shown in Figure 6. This form acknowledges that you've entered a new user. If your credentials fail to meet set conditions the same line would explain why.

Figure 6 Main Administration page with a confirmation message

4. After you enter both Indiana Jones and Marion Ravenwood as the "administrator" user, you can view your user ACL members by clicking the View User button.

Figure 7 User Account View from an Administration Group user

4. After you have confirmed entry Indiana Jones as a system administrator and Marion Ravenwood as a system user, you should click the Log Out button. Then, you should log in as a system user by using the guest or Marion Ravenwood credentials. Figure 8 shows how the New User form looks to an employee group user.

Figure 8 Main Administration page for a Restricted User Account

5. When you click the View User button as Marion Ravenwood, only your account is displayed. This behavior works because the form returns a striped view of data.

Figure 9 User Account View from a Employee Group User

You have now experimented with the striped user authentication forms. The next section analyzes how identity management works to support these forms.

Analyze the UserAdmin.php Session Authentication Code. Several changes to prior version of the AddDBUser.php program presented in the earlier paper make this striped behavior possible. The AddDBUser.php program has been changed to the UserAdmin.php script with the following changes:

• Modify the get_session() function to get and set proper user-defined session metadata variable values.
• Modify the create_new_db_user() function to verify whether the current authenticated user is a privileged user or not.
• Modify the get_message() function and the base form logic to provide confirmation of user entry.
• Disable the text entry fields, Add User button and Administration/Employee group radio buttons unless the user is a privileged user.
• The base code of the verify_db_login() function now captures the group value and assigns it to a $_SESSION variable.

You will build striped web applications by implementing similar coding changes in your applications. Each of the five business logic changes are examined individually.

Modify the get_session() Function. The get_session() function has changed between the AddDbUser.php and UserAdmin.php versions to enable separate request handling based on a user's group assignment. The select statement now returns two additional columns — they are the SYSTEM_USER_ID and SYSTEM_USER_GROUP_ID values. The get_session() function evaluates whether the SYSTEM_USER_GROUP_ID value is 0, which is the administration group in this application. When the user has administration privileges, the function assigns the group value to the $_SESSION['client_info'] value. When the user does not have administration privileges, the function assigns the individual's record identifier as the $_SESSION['client_info'] value.

You can then use the $_SESSION['client_info'] value to control future connections in the scope of the currently running script file. You maintain a $_SESSION['client_info'] value in your PHP program scope when you're using non-persistent connections to the Oracle database. You can avoid this by simply setting the CLIENT_INFO column value in the session metadata, provided you made all persistent connections — using oci_pconnect() function.

The modified get_session() function is shown below with the changes highlighted by bold text:

function get_session($sessionid,$userid = null,$passwd = null)
{
  // Attempt connection and evaluate password.
  if ($c = @oci_connect(SCHEMA,PASSWD,TNS_ID))
  {
    // Assign metadata to local variable.
    $remote_address = $_SERVER['REMOTE_ADDR'];

    // Return database UID within 5 minutes of session registration.
    $s = oci_parse($c,"SELECT   su.system_user_id
                       ,        su.system_user_name
                       ,        su.system_user_group_id
                       ,        ss.system_remote_address
                       ,        ss.system_session_id
                       FROM     system_user su JOIN system_session ss
                       ON       su.system_user_id = ss.system_user_id
                       WHERE    ss.system_session_number = :sessionid
                       AND     (SYSDATE - ss.last_update_date) <=
                                  .003472222");

    // Bind the variables as strings.
    oci_bind_by_name($s,":sessionid",$sessionid);

    // Execute the query and raise missing table message on failure.
    if (@oci_execute($s,OCI_DEFAULT))
    {
      // Check for a validated user, also known as a fetched row.
      if (oci_fetch($s))
      {
        // Assign unqualified values.
        $_SESSION['userid'] = oci_result($s,'SYSTEM_USER_NAME');

        // Assign the privileged group or user primary key column value.
        if (oci_result($s,'SYSTEM_USER_GROUP_ID') == 0)
          $_SESSION['client_info'] = oci_result($s,'SYSTEM_USER_GROUP_ID');
        else
          $_SESSION['client_info'] = oci_result($s,'SYSTEM_USER_ID');

        // Check for same remote address.
        if ($remote_address == oci_result($s,'SYSTEM_REMOTE_ADDRESS'))
        {
          // Refresh last update timestamp of session.
          update_session($c,$sessionid,$remote_address);
          return (int) oci_result($s,'SYSTEM_SESSION_ID');
        }
        else
        {
          // Log attempted entry.
          record_session($c,$sessionid);
          return 0;
        }
      }
      else
      {
        // Record when not first login.
        if (!isset($userid) && !isset($passwd))
          record_session($c,$sessionid);
        return 0;
      }
    }
    else
    {
      // Set error message.
      set_error(__FUNCTION__,array('SYSTEM_USER','SYSTEM_SESSION'));
    }

    // Close the connection.
    oci_close($c);
  }
  else
  {
    $errorMessage = oci_error();
    print htmlentities($errorMessage['message'])."<br />";
  }
}

Modify the create_new_db_user() Function. The create_new_db_user() function now returns a Boolean variable as opposed to a void. This change lets the UserAdmin.php program call the function inside a control structure, as shown below:

if (create_new_db_user($_SESSION['db_userid']
                      ,$newuserid
                      ,$newpasswd
                      ,$fname
                      ,$lname
                      ,$usergroup))
{
  // Set code to successful.
  $code = USER_VALID;

  // Render new form with successful acknowledgement.
  userAdminForm(array("code"=>$code
                     ,"form"=>"UserAdmin.php"
                     ,"userid"=>$newuserid));
}

The change lets you append a success message to the next rendered copy of the New User form. The function also guards against an unauthorized user adding a new user. While the functionality to add a new user is restricted by conditional rendering of the form based on the privileges of authenticated users, it should also be protected in the function. The precautions create a good design model that does not exclusively rely on tightly coupled behaviors. Functional coupling can get lost during maintenance coding and you should ensure independence of action for all functions. Functions can then be used by different user interfaces (UIs).

This application UI takes the approach to prevent an unauthorized attempt to create a new user, but another may enable the attempt but report back to the user that they are unauthorized. Functions supporting UIs should be flexible enough to handle both approaches, like this one.

The create_new_db_user() function now sets a $written control variable to false on entry. Then, it checks whether the active user is authorized to add a new user. It does this by reading the $_SESSION['client_info'] value set by the get_session() function. The control variable is reset to true when a new user is successfully added to the database. The complete function follows below:

// Add a new user to the authorized control list.
function create_new_db_user($userid,$nuserid,$npasswd,$fname,$lname
                           ,$ugroup)
{
  // Set control variable.
  $written = false;

  // Attempt connection and evaluate password.
  if ($c = @oci_connect(SCHEMA,PASSWD,TNS_ID))
  {
    // Check for prior insert, possible on web page refresh.
    if (!is_inserted($c,$nuserid) && ($_SESSION['client_info'] == 0))
    {
      // Return database UID.
      $s = oci_parse($c,"INSERT INTO system_user
                         ( system_user_id
                         , system_user_name
                         , system_user_password
                         , first_name
                         , last_name
                         , system_user_group_id
                         , system_user_type
                         , start_date
                         , created_by
                         , creation_date
                         , last_updated_by
                         , last_update_date )
                         VALUES
                         ( system_user_s1.nextval
                         , :newuserid
                         , :newpasswd
                         , :firstname
                         , :lastname
                         , :usergroup
                         , 1
                         , SYSDATE
                         , :userid1
                         , SYSDATE
                         , :userid2
                         , SYSDATE)");

      // Bind the variables as strings.
      oci_bind_by_name($s,":newuserid",$nuserid);
      oci_bind_by_name($s,":newpasswd",sha1($npasswd));
      oci_bind_by_name($s,":firstname",$fname);
      oci_bind_by_name($s,":lastname",$lname);
      oci_bind_by_name($s,":usergroup",$ugroup);
      oci_bind_by_name($s,":userid1",$userid);
      oci_bind_by_name($s,":userid2",$userid);

      // Execute the query print error handling for missing table.
      if (@oci_execute($s,OCI_COMMIT_ON_SUCCESS))
      {
        // Update control variable for insert.
        $written = true;
      }
      else
      {
        // Set error message.
        set_error(__FUNCTION__,array('SYSTEM_USER'));
      }
    }

    // Close the connection.
    oci_close($c);

    // Return control variable.
    return $written;
  }
  else
  {
    $errorMessage = oci_error();
    print htmlentities($errorMessage['message'])."<br />";
  }
}

Modify the get_message() Function. The only change to the get_message() function is the addition of two criteria. One acknowledges successful entry of a new user, and the other supports an unauthorized access message. You should also note that the previous magic numbers have been converted to constants, which improves the readability of the code.

Disable Conditionally the Add User and Group Radio Buttons. The userAdminForm() function now conditionally renders the text entry fields, Add User and Administration/Employee group radio buttons. This change implements the UI discussed earlier and prevents unauthorized attempts to add new users. While the text entry fields and Administration/Employee group radio buttons have no utility when the submission button is disabled, they are likewise disabled to avoid end-user confusion. They are disabled when the following conditional statement is not met:

if ((!@$_SESSION['client_info']) && (@$_SESSION['client_info'] == 0))

The statement checks whether the session level variable is both set and equal to 0, which is the only authorized or privileged account in the application. In a real implementation, you would probably have a list of authorized account privileges in an array. Assuming that you initialize a privileged ACL in a $authorized_list array variable, you would most likely use a conditional expression like this:

if ((!@$_SESSION['client_info']) &&
    (array_search(@$_SESSION['client_info'],$authorized_list)))

Modify the verify_db_login() Function. The application design enables a session to be updated when a user log out and back in using the same credentials within a timeout window. This design requires you to update the behavior of the verify_db_login() function. You change the function by enabling it to capture and set the $_SESSION['client_info'] value, as shown below in the function implementation:

function verify_db_login($userid,$passwd)
{
  // Attempt connection and evaluate password.
  if ($c = @oci_connect(SCHEMA,PASSWD,TNS_ID))
  {
    // Return database UID.
    $s = oci_parse($c,"SELECT   system_user_id
                       ,        system_user_group_id
                       FROM     system_user
                       WHERE    system_user_name = :userid
                       AND      system_user_password = :passwd
                       AND      SYSDATE BETWEEN start_date
                                        AND NVL(end_date,SYSDATE)");

    // Assign encryted value to variable, avoiding E_STRICT error.
    $newpassword = sha1($passwd);

    // Bind the variables as strings.
    oci_bind_by_name($s,":userid",$userid);
    oci_bind_by_name($s,":passwd",$newpassword);

    // Execute the query and raise missing table message on failure.
    if (@oci_execute($s,OCI_DEFAULT))
    {
      // Check for a validated user, also known as a fetched row.
      if (oci_fetch($s))
      {
        // Confirm session and collect foreign key reference column.
        if ((!isset($_SESSION['session_id'])) ||
            (!isset_sessionid($c,$_SESSION['sessionid'])))
        {
          $_SESSION['db_userid'] = oci_result($s,'SYSTEM_USER_ID');
          $_SESSION['client_info'] = oci_result($s,'SYSTEM_USER_GROUP_ID');
          register_session($c,(int) $_SESSION['db_userid']
                          ,$_SESSION['sessionid']);
        }

        // User verified.
        return true;
      }
      else
      {
        // User not verified.
        return false;
      }
    }
    else
    {
      // Set error message.
      set_error(__FUNCTION__,array('SYSTEM_USER'));
    }

    // Close the connection.
    oci_close($c);
  }
  else
  {
    $errorMessage = oci_error();
    print htmlentities($errorMessage['message'])."<br />";
  }
}

The five analyses have reviewed the changes to UserAdmin.php script. The next section will examine the new UserView.php program.

Analyze the UserView.php Session Authentication Code. The UserView.php program is new but is an outgrowth of the business logic found in the UserAdmin.php program. The development of the new form required three new functions and allowed the removal of several functions. It also required the development of a striped AUTHORIZED_USER view in the database.

By synchronizing the functions, you are positioned to remove them from the individual script files and place them in a single shared library to support the application. This is the next recommended step in building your own identity management solution.

The three new functions added are:

• The return_users() function that gets the results from a striped view.
• The set_client_info() function that sets a user-defined session metadata value in the database.
• The strip_special_characters() function that lets you use otherwise unsupported formatting characters in your PL/SQL program statements, like line returns.

Before examining how the PHP code in the UserView.php form implements the architecture and design, you should first understand how the striped view works. The following is the view definition provided in the create_identity_db2.sql script:

CREATE OR REPLACE VIEW authorized_user AS
  SELECT   su.system_user_id AS user_id
  ,        su.system_user_name AS user_name
  ,        cl.common_lookup_meaning AS user_privilege
  ,        CASE
             WHEN su.first_name IS NOT NULL AND  su.last_name IS NOT NULL
             THEN su.first_name||' '|| su.last_name
             ELSE NULL
           END AS employee_name
  ,        su.system_user_group_id AS group_id
  FROM     system_user su JOIN common_lookup cl
  ON       su.system_user_group_id = cl.common_lookup_id
  WHERE    TO_NUMBER(NVL(SYS_CONTEXT('userenv','client_info'),-1)) = 0
  OR       su.system_user_id =
             TO_NUMBER(NVL(SYS_CONTEXT('userenv','client_info'),-1))
  ORDER BY CASE
             WHEN first_name IS NULL
             THEN 0
             ELSE 1
           END
  ,        su.last_name
  ,        su.first_name
  ,        su.system_user_id;

The WHERE clause requires resolution of the call to the SYS_CONTEXT() function. When the function fails to return a value, the null value substitution is -1, which should return no rows by design. Therefore, this striped view only works when the user-defined database session metadata CLIENT_INFO column value is set to a matching value by the web application.

The return_users() Function.The return_users() function gets the results from a striped view and formats them for display. The function calls the set_client_info() function before querying the data. The set_client_info() function sets the server session CLIENT_INFO value by calling the DBMS_APPLICATION_INFO() procedure. This limits the view to seeing only those records consistent with the end-user permissions.

The view returns information about all ACL users when the active user is in the Administration group, and only information about the active user when the active user is in the Employee group. This is clearly a limitation of trying to keep the example short and an opportunity for improvement when you implement your own identity management system. The complete return_user() function follows for your reference:

function return_users($userid)
{
  // Attempt connection and evaluate password.
  if ($c = @oci_connect(SCHEMA,PASSWD,TNS_ID))
  {
    // Set the connection striping.
    set_client_info($c,$userid);

    // Return database UID.
    $s = oci_parse($c,"SELECT   user_id
                       ,        user_name
                       ,        user_privilege
                       ,        employee_name
                       FROM     authorized_user");

    // Execute the query, error handling should be added.
    if (@oci_execute($s,OCI_DEFAULT))
    {
      // Set a first row control variable.
      $no_row_fetched = true;

      // Initialize the return variable in case no rows are found.
      $out = '';

      // Check for a validated user, also known as a fetched row.
      while (oci_fetch($s))
      {
        if ($no_row_fetched)
        {
          $out .= '<tr>';
          $out .= '<td align="center"><b>User ID</b></td>';
          $out .= '<td align="center"><b>User Name</b></td>';
          $out .= '<td align="center"><b>User Privilege</b></td>';
          $out .= '<td align="center"><b>Employee Name</b></td>';
          $out .= '</tr>';
          $no_row_fetched = false;
        }

        $out .= '<tr>';

        for ($i = 1;$i <= oci_num_fields($s);$i++)
          if (!is_null(oci_result($s,$i)))
          {
            if ($i == 1)
              $out .= '<td align="right">'.oci_result($s,$i).'</td>';
            else
              $out .= '<td>'.oci_result($s,$i).'</td>';
          }
          else
            $out .= '<td> </td>';
        $out .= '</tr>';
      }
    }
    else
    {
      // Set error message.
      set_error(__FUNCTION__,array('AUTHORIZED_USER'));
    }

    // Close the connection.
    oci_close($c);

    // Return formatted string.
    return $out;
  }
  else
  {
    $errorMessage = oci_error();
    print htmlentities($errorMessage['message'])."<br />";
  }
}

The set_client_info() Function.The set_client_info() function calls a PL/SQL procedure inside an anonymous PL/SQL block.

// Strip special characters, like carriage or line returns and tabs.
function set_client_info($c,$userid)
{
  // Declare a PL/SQL execution command.
  $stmt = "BEGIN
             dbms_application_info.set_client_info(:userid);
           END;";

  // Strip special characters to avoid ORA-06550 and PLS-00103 errors.
  $stmt = strip_special_characters($stmt);

  // Parse a query through the connection.
  $s = oci_parse($c,$stmt);

  // Map the local variable to a bind variable.
  oci_bind_by_name($s,':userid',$userid);

  // Run the procedure.
  if (oci_execute($s))
    return true;
  else
    return false;
}

The strip_special_characters() Function. The strip_special_characters() function removes tabs and line returns that cause problems with the PL/SQL parser. This enables you use whitespace and line returns to make your code more readable. The function is:

function strip_special_characters($str)
{
  $out = "";
  for ($i = 0;$i < strlen($str);$i++)
    if ((ord($str[$i]) != 9) && (ord($str[$i]) != 10) &&
        (ord($str[$i]) != 13))
      $out .= $str[$i];
  // Return pre-parsed SQL statement.
  return $out;
}

Conclusion

You have now learned how identity management works in the context of virtual private databases for scheme, and how to configure the application for individual users found in an ACL within a single schema. The code examples and analyses show how you can operate selectively based striping values of authenticated users. The users can be stored in an ACL table that resides in a single schema. You can now extend the provided solution into a VPD model by simply building the policy functions against the session CLIENT_INFO column value.

Authentication systems contain an Access Control List (ACL) that lists your user credentials and matches them to your assigned system privileges. Credentials are typically a user name and password pair. Credentials link your users to system privileges. System privileges let your accounts access or modify data, and enable your accounts to execute subsystems or subroutines. Your accounts can be users, groups, or systems.

In this article, you will learn how to implement this concept in PHP-based Web applications. You will learn how to design and implement an authentication database model, and plan and manage all aspects of user interactions in a browser-hosted application.

In Part 2 of this article, you will explore different methods of database access and how authentication systems can leverage security policies in an Oracle Virtual Private Database (VPD), as well as with the built-in DBMS_APPLICATION_INFO package.

Architecture, Authentication, and Encryption

Architecture. When Web applications request information from the Apache HTTP server, they send information from the client to the server. Users view this process as submitting a URL and receiving a Web page in reply. A URL is only the exposed part of the URI; the URI contains HTTP headers, cookies, and a URL. The information is transmitted as an encoded name and value pair in the URI.

Cookies are small text files containing clear or encrypted text. Cookies contain the current transaction state of communication between the browser and server application. The content of cookies was once frequently attached to the URI to help maintain transaction state. A single session cookie now sends a numeric reference that enables the prior name and value cookie pairs to be stored securely on the server. The numeric reference is known as a Web session ID.

When using Web application sessions, the session ID and expiration information about the session are sent as a special session cookie. When client browsers disallow cookies, Web applications may default to URL rewriting, which redirects the session cookie from the undisclosed URI to the disclosed URL. You recognize two benefits by leaving the data on the server and storing it by a unique session ID — you minimize the size of the URL, and you secure the internal details of user interactions.

Although keeping session information on the server is more secure, you must guard against session hijacking. A malicious user can hijack a session by (a) stealing a session cookie, (b) copying a URL that includes the session ID or (c) snatching it through a man-in-the-middle attack. Modern browsers make this more difficult, and PHP does not write the physical session cookies to a file system.

A benefit of the cookie and session architecture is that you can mine historical session data, provided you store data in a normalized data model. The data let you discover how customers use your Web applications. The data also let you discover customer browsing patterns and purchasing trends. This type of information enables businesses to target marketing to individuals as opposed to groups.

Authentication. You will use one of two authentication models to verify users in your Web applications. Your choice is between the basic HTTP/HTTPS authentication, and the cookie and session authentication models. A third authentication model, a digest HTTP authentication, is under development but appears likely to remain an incomplete solution for a few more years.

Both of the first two authentication models let you take credentials from a Web page and validate them against an ACL. They also let you work successfully whether or not the browser accepts cookies. The basic HTTP/HTTPS and digest HTTP methods validate against a realm without using a cookie, while the session management writes at least a session ID cookie.

URL rewriting presents some security risks when you send the session ID as part of the URL because some users instant message the URL to someone else. That other person may hijack the authorization to access or compromise confidential data. An alternative to URL rewriting is placing the session ID into the rendered Web page as a hidden field. While this does create vulnerability, it is less risky than appending the session to the URL.

Your PHP authentication script takes a name and value pair for the user name and password. The script then compares the pair against data stored in your ACL. This is the same process in either the discussed authentication models. While it is customary to store server-side passwords in encrypted forms, you should recognize that any compromise of the clear text user and password values compromises your system security.

Therefore, you should not force users to create complex passwords because they aren't easily remembered. Users write hard-to-remember passwords on notepads or yellow sticky pads. Written passwords are security risks to your Web application because hackers might find and misuse them.

Encryption. Encryption is always a hot topic in Web application development, deployment, and management.

There are two encryption techniques in PHP Web applications. The first involves encrypting your protocol. Encrypted protocols, like HTTPS, protect you from man-in-the-middle attacks using network analyzers, commonly known as packet sniffers. The second involves encrypting your user password from exposure to prying eyes on the server.

Password encryption protects your system from attacks best when the encrypted passwords are stored separately from the source code. When the ACL is a file on the file system, both the method of encryption and encrypted values can be compromised by a single server hack. You reduce the risk of compromising the encrypted passwords by storing your ACL in a database.

Identity Management Data Modeling

Building an identity management data model can vary from the simple to the complex. The simplest model is a single table containing the ACL for your application. Unfortunately, this model only works with basic HTTP/HTTPS authentication.

The simplest way to implement cookie and session authentication requires at least two tables. One table contains the ACL, and the other contains the session data. The following depicts a basic model:

Figure 1 Basic authentication data model

A more effective solution for authentication would support capturing and mining user interactions. These vary from the list of Web pages called to individual events, like mouse clicks. Figure 2 shows a data model that can capture user navigation and both successful and unsuccessful logins. For our example, this data model is created by the create_identity_db.sql script (see sample code zip).

Figure 2 Detailed authentication data model

The larger model lets you track versions of defined modules against runtime calls to modules. Actual parameters map to catalog items, like books on Amazon.com. An access log is added to track multiple connections made during a single session. The full details of how you implement your model can vary based on your goals. Figure 2 also shows an example model that supports version control in a catalog ordering application. At present, the sample code only captures invalid log in attempts and the ACCESS_LOG table is renamed to reflect that difference as INVALID_SESSION table.

Authentication Process Models

Basic HTTP/HTTPS authentication operates by establishing a browser's credentials in a realm. Browsers can concurrently support many realms. Realms are set in the header of XHTML documents. They can be manually coded in the form, or set in the AuthName directive of the httpd.conf file. Realms act as guards over protected server areas, and they can apply to one or more protected server areas. One advantage of basic HTTP/HTTPS authentication is that you don't have to code a login or logout facility. Browsers provide the login forms and you logout by closing all open browser windows.

A major downfall of the basic HTTP/HTTPS authentication method is you must close all browser windows to end active realm authorizations. This means that a user can authenticate, walk away from the terminal while leaving an open browser, and enable someone to compromise their confidential data by hijacking their identity.

Cookie and session authentication operates by checking user credentials against your ACL. When the ACL is stored in a file, this means reading the file and comparing the name value pairs of a user name and password against a submitted clear text user name and encrypted password.

When the ACL is stored in a database, this means one thing on initial login and another on subsequent connections. On initial login, you connect to the database, read the user name and encrypted password values from a database table; and compare the results against the submitted clear text user name and encrypted password. On subsequent Web requests, you connect to the database, read the session ID, and compare results against the submitted session ID. Unlike basic HTTP/HTTPS authentication, you can successfully logout while leaving the Web browser open.

While the session ID becomes a potential security risk because of session hijacking, some reasonable precautions can minimize this risk. The biggest security gap can be closed by implementing your login page as a PHP script instead of a simple text XHTML form. The sample cookie and session code demonstrates this approach. It ensures that a second user on a shared machine doesn't gain entry from the prior credentials. The implementation details are found in the following Cookie and Session Authentication Model section.

Basic HTTP/HTTPS Authentication Model. The basic HTTP/HTTPS authentication model authorizes once for a realm and revokes the realm authentication only when all browser windows are closed. The activity diagram representing the model from within the browser context is shown in Figure 3. Microsoft Internet Explorer provides three attempts before failing authentication but you can simply refresh the page to get another three successive attempts. The Firefox browser differs by prompting until the user cancels the authentication process.

Figure 3 Basic HTTP/HTTPS authentication activity diagram

You start a Web application session by entering a URL for the login form, which then posts to the server and sends a message back to the browser requesting that it collect and send for validation the user's credentials. When you submit the credentials to the SignOnDB.php program, the code attempts to validate your log credentials. When it works you can then use any Web pages in the realm. Authentication failure re-prompts with the browser login form as noted previously.

When implementing basic HTTP/HTTPS authentication, PHP uses three predefined variable names in the $_SERVER array. Basic HTTP/HTTPS authentication puts the user ID and the password in the $_SERVER['PHP_AUTH_USER'] and $_SERVER['PHP_AUTH_PW'] respectively. When the third, HTTP_AUTHORIZATION, is not set, you submit these two $_SERVER values to your authentication function. After your server-side program authenticates the user, subsequent reads of the $_SERVER array HTTP_AUTHORIZATION name let the browser access to the realm until it is closed.

An easy way to protect your pages in the basic HTTP/HTTPS authentication model is to include a Boolean control variable that is false until authentication is verified. You display content only when the Boolean control variable becomes true. Your code should check for authentication, and prompt for credentials when you are not authenticated in the realm. This code should be found in all pages on your secure Web site.

You trigger HTTP header validation in your server-side script by checking the values of these predefined $_SERVER variables. The request to the SignOnRealm.php page places these values in the returned header, which instructs the browser to prompt with a credential entry dialog box. Clicking the credentials OK button sends a new request to the server-side script. The server-side script then attempts to validate the submitted credentials unless a user cancels the process. These realm sign in scripts typically return a failure message when the user cancels the process. Some sites also shut user accounts when there are three or four consecutive authentication failures because someone may be attempting to hack into the system through a known user name.

Setup Test Application. The demonstration application uses an Oracle schema named IDMGMT1, and the password is the same as the schema. You can create the user and environment by following these steps:

1. Log into the database as the privileged SYSTEM user and run the following commands:

SQL> CREATE USER IDMGMT1 IDENTIFIED BY IDMGMT1;
SQL> GRANT CONNECT, RESOURCE TO IDMGMT1;

2. Connect to the new user schema:

SQL> CONNECT IDMGMT1/IDMGMT1@XE

3. Run the create_identity_db1.sql script in the IDMGMT1 schema to create all necessary objects and seed the SYSTEM_USER table:

SQL> @create_identity_db1.sql

4. Place the following files in your htdocs directory or a subdirectory of the htdocs directory:

 • SignOnRealm.php
 • SignOnDB.php
 • AddDbUser.php

These steps complete the setup required for our purposes here. You can now experiment with either the realm or session identification management examples.

Experiment with Basic HTTP/HTTPS Authentication. You can experiment with the realm identity management by following these steps:

1. Open the realm identification management examples by using the following URL:

http://localhost/SignOnRealm.php

2. You can use either of the following seeded accounts as valid credentials using Basic HTTP/HTTPS authentication. Make sure you don't have the cap lock enabled because they are case sensitive.

Figure 4 Basic HTTP/HTTPS authentication dialog box

After you successfully enter your credentials you will be presented with the following page that echoes back the plain text credentials and encrypted password:

Figure 5 Basic HTTP/HTTPS credential validation acknowledgment

Analyze the Basic HTTP/HTTPS Authentication Code. After you enter your user name and password, your script will call the verify_db_login() function. The following PHP code demonstrates how you begin the authentication of users in your realm:

// Declare control variable.
$valid_user = false;

// Authenticate user.
if ((isset($_SERVER['PHP_AUTH_USER'])) && (isset($_SERVER['PHP_AUTH_PW'])))
  if (verify_db_login($_SERVER['PHP_AUTH_USER'],$_SERVER['PHP_AUTH_PW']))
    $valid_user = true;

This function opens a connection to the Oracle database and checks whether the credentials are valid. The verify_db_login() function returns true when credentials are valid and false when not. When the SYSTEM_USER table is missing, the code tells you to check for the missing table. The main code for the Web page is shown in the function:

// Check for authorized account.
function verify_db_login($userid,$passwd)
{
  // Attempt connection.
  if ($c = @oci_connect(SCHEMA,PASSWD,TNS_ID))
  {
    // Return a row.
    $s = oci_parse($c,"SELECT   NULL
                       FROM     system_user
                       WHERE    system_user_name = :userid
                       AND      system_user_password = :passwd
                       AND      SYSDATE BETWEEN start_date
                                        AND NVL(end_date,SYSDATE)");

    // Encrypt password.
    $newpassword = sha1($passwd);
    // Bind variables as strings.
    oci_bind_by_name($s,":userid",$userid);
    oci_bind_by_name($s,":passwd", $newpassword));

      // Execute the query.
      if (@oci_execute($s,OCI_DEFAULT))
      {
        // Check for a validated user, also known as a fetched row.
        if (oci_fetch($s))
           return true;
        else
          return false;
      }
      else
      {
        // Print error when execution fails.
        $errorMessage = "Check for a missing SYSTEM_USER table.<br />";
        print $errorMessage;
      }

    // Close connection.
    oci_close($c);
  }
  else
  {
    $errorMessage = oci_error();
    print htmlentities($errorMessage['message'])."<br />";
  }
}

There are two things to note about the verify_db_function() function. First, the query returns a null value, which eliminates processing any unnecessary return values. Second, the clear text password is encrypted using the sha1() function and assigned to a local variable.

You now know how to build the required components for basic HTTP/HTTPS authentication. The two caveats associated with this authentication model are that you: (1) have complete access to the realm once you authenticate your credentials in a browser; and (2) can only log out by closing all browser windows.

Cookie and Session Model. The cookie and session model is popular because you can let users login and logout of Web applications without requiring them to shutdown all of their browser windows. This authentication model is also more complex than the basic HTTP/HTTPS model. There are different ways that you can implement cookie and session authentications.

The login and logout operations operate inside active browsers. This operating context adds more complexity to the cookie and session model. For example, the browser backward, forward, and refresh buttons require special handling in your code. A refresh button shouldn't attempt to send a new user authentication more than once. Likewise, a refresh button should not trigger new authentication requests after a user has logged out of an application. Unfortunately, they do unless the program prevents it.

Calling a login PHP script, not an XHTML Web page is the most direct way to guarantee a complete logout operation in your Web application. A PHP script can reset the session value whereas an XHTML Web page cannot because it passes the prior session value when submitting missing or new credentials to a target page.

There are several predefined variables in PHP that you can use to store globally scoped variables. One is the $_SESSION array. It lets you add any name-value pair, where the name becomes the index value to the actual data value. The advantages of using the $_SESSION array are simplicity and flexibility but the disadvantages can involve conflicts with other libraries.

The session_start() function returns the active PHP session ID value. You must call the session_start() function before the session_regenerate_id() function because it actually calls the session_destroy() function. The session_destroy() depends on the existence of a PHP session ID and will raise an error when one doesn't exist before you call it. Your call to the session_regenerate_id() function with an actual true parameter will reset the PHP session ID. You use runtime error suppression to guarantee that calling the session_regenerate_id() function doesn't raise an error when no prior session exists in the context of the browser.

<?php
  // Start and regenerate session.
  session_start();
  @session_regenerate_id(true);
  $_SESSION['sessionid'] = session_id();
?>

The preceding scriptlet alters the session value in the browser, and it will force new authentication with the next click of the Login button. It does this by replacing the previously authenticated PHP session ID with a new session ID. The new PHP session ID is transmitted as part of the URL to the next form.

There are two ways to manage database connections once you establish your PHP session: One uses a persistent connection between the PHP module and the database and the other uses a non-persistent connection between the two. Persistent connections let you start a transaction scope that can span several Web requests, and they end only when you issue a database commit command. During the scope of a persistent connection, you can run SQL and PL/SQL statements that lock rows pending change or after an uncommitted change. Non-persistent connections let you run SQL or PL/SQL statements to query or change data between opening and closing a connection, which occurs in a single Web request. Data transactions limited by a single connection are also known as autonomous transactions because their duration is limited to the duration of the connection.

These sample programs use non-persistent database connections to query and transact against the Oracle database. Consequently, all database transactions perform as autonomous transactions.

The SignOnDB.php Web page, shown in Figure 5, implements this type of PHP scriptlet before the XHTML page. The XHTML rendering found in the SignOnDB.php form is also found in the AddDbUser.php page as the signOnForm() function.

You will put the PHP authentication logic in all Web pages called after a user logs into the application. At present all programming logic is in the AddDbUser.php page, shown in Figure 6, but you can move the twelve functions into one authentication library.

Your browser must accept cookies for these programs to work. When cookies are disabled, all you can do is login, logout, and fail to enter a new user because the session values are lost between pages.

Experiment with Session Authentication. You can experiment with the session identity management by following these steps:

1. Open the session identification management examples by using the following URL, assuming that you placed the code in the htdocs directory:

http://localhost/SignOnDB.php

2. You can use either of the seeded accounts presented in the Basic HTTP/HTTPS authentication:

Figure 6 Cookie and Session Login page

3. You can now enter a new user into your credential repository in the New User form, which requires user name to be a string that is 6 to 10 characters long and starts with a letter:

Figure 7 Cookie and session Add New User page

4. After you add the new user, the AddDBUser.php script will present you with a new copy of the New User form. It will acknowledge whether you successfully added a new user or explain what rule the entry violated. You can connect to the IDMGMT1 schema and run the following query to inspect a new user entry:

SELECT system_user_name, system_user_password FROM system_user;

Analyze the Session Authentication Code

The PHP program's logic accounts for the typical nuances of the forward, backward and refresh browser buttons. Figure 7 displays the rendered Web page. When you call or refresh the form by using the browser navigation buttons, the program determines whether (a) the session is registered in the database model to the current user, (b) the remote address is the same client IP address from authentication, and (c) the session is current. A session is current when the last related database activity of the session occurred within the last five minutes.

Both the initial sign on form and add user forms check and verify a registered session before the program logic looks for new user credentials and attempts to authenticate the user. When the credentials are authenticated, the SignOnDB.php script registers the new session and calls the AddDbUser.php script. A refresh of the AddDbUser.php script calls the signOnForm() function that mimics the SignOn.php form's behavior. When the AddDbUser.php script authenticates credentials, it renders a page using the addUserForm() and when either script repudiates credentials, they log a failed login attempt and render a new sign on page.

Figure 8 Cookie and session authentication activity diagram

The Web page contains two XHTML forms. One form lets you enter a new user, validate that the credentials meet guidelines (e.g., 6 to 10 character strings starting with a letter), and inserts the credentials into the database. The other form lets you opt to log out of the application by calling the SignOnDB.php script, which resets the session to prevent it appearing authenticated in the database after a user logged out.

The Web page starts the session and assigns it to the $_SESSION array, assigns any submitted credentials to local variables, and then checks to see whether a current authenticated session is available. This is done by the following code:

  // Check for valid session and regenerate when session is invalid.
  if ((get_session($_SESSION['sessionid'],$userid,$passwd) == 0) ||
      (($_SESSION['userid'] != $userid) && ($userid)))
  {
    // Regenerate session ID.
    session_regenerate_id(true);
    $_SESSION['sessionid'] = session_id();
  }
  else
  {
    $authenticated = true;
  }

The get_session() function opens a connection to the database and queries a result set from the join of the SYSTEM_USER and SYSTEM_SESSION tables. The results from the query determine whether or not the session is authenticated. Part of this verification process checks to make sure that the request originates from the same IP address. When authenticated, Web page variables are assigned values from the query to process the page request. At the same time, the LAST_UPDATE_DATE column timestamp is updated by the update_session() function. The attempt is logged by the record_session() function to the OBSOLETE_SESSION table in the database when authentication fails.

// Get a valid session.
  function get_session($sessionid,$userid = null,$passwd = null)
  {
    // Attempt connection and evaluate password.
    if ($c = @oci_connect(SCHEMA,PASSWD,TNS_ID))
    {
      // Assign metadata to local variable.
      $remote_address = $_SERVER['REMOTE_ADDR'];

      // Return database UID within 5 minutes of session registration.
      // The Oracle DATE data type is a timestamp where .003472222 is
      // equal to 5 minutes.
      $s = oci_parse($c,"SELECT   su.system_user_name
                         ,        ss.system_remote_address
                         ,        ss.system_session_id
                         FROM     system_user su JOIN system_session ss
                         ON       su.system_user_id = ss.system_user_id
                         WHERE    ss.system_session_number = :sessionid
                         AND     (SYSDATE - ss.last_update_date) <=
                                    .003472222");

      // Bind the variables as strings.
      oci_bind_by_name($s,":sessionid",$sessionid);

      // Execute the query, error handling should be added.
      if (@oci_execute($s,OCI_DEFAULT))
      {
        // Check for a validated user, also known as a fetched row.
        if (oci_fetch($s))
        {
           // Assign unqualified values.
          $_SESSION['userid'] = oci_result($s,'SYSTEM_USER_NAME');

          // Check for same remote address.
          if ($remote_address == oci_result($s,'SYSTEM_REMOTE_ADDRESS'))
          {
            // Refresh last update timestamp of session.
            update_session($c,$sessionid,$remote_address);
            return (int) oci_result($s,'SYSTEM_SESSION_ID');           }
           else
           {
             // Log attempted entry.
             record_session($c,$sessionid);
             return 0;
           }
        }
        else
        {
          // Record when not first login.
          if (!isset($userid) && !isset($passwd))
            record_session($c,$sessionid);

          // Return a zero.
          return 0;
        }
      else
      {
        // Print error when oci_execute() fails.
        $errorMessage = "Check for a missing SYSTEM_USER or ";
        $errorMessage .= "SYSTEM_SESSION tables.<br />";
        print $errorMessage;
        return 0;
      }

      // Close the connection.
      oci_close($c);
    }
    else
    {
      $errorMessage = oci_error();
      print htmlentities($errorMessage['message'])."<br />";
      return 0;
    }
  }

You should note that the functions called from the get_session() function share the database connection opened to confirm an existing session. This goal is accomplished by passing the connection as an actual parameter to the other two functions. Managing the database transaction scope in a single database connection lets you manage multiple SQL and PL/SQL statements as components of a transaction. This enables functions to contain single subjects of your data abstraction layer and lets you treat nested function calls as subroutines.

Figure 9 Cookie and session Add New User Bad Credential page

The next section of primary code in the Web page renders different versions of the form because it serves multiple purposes. Figure 6 shows the form rendered on initial login to the application. Figure 9 demonstrates the form rendered after attempting to enter a null user name. The code calls the create_new_db_user() function when appropriate to add new users to the ACL in the SYSTEM_USER table, as shown:

  // Check whether the program should:
  // -----------------------------------------------------------------
  //  Action #1: Verify new credentials and start a database session.
  //  Action #2: Continue a session on refresh button.
  //  Action #3: Provide a new form after adding a user.
  //  Action #4: Provide a new form after failing to add a user.
  // -----------------------------------------------------------------
  if (($authenticated) || (authenticate($userid,$passwd)))
  {
    // Assign inputs to variables.
    $newuserid = @$_POST['newuserid'];
    $newpasswd = @$_POST['newpasswd'];

    // Set message and write new credentials.
    if ((isset($newuserid)) && (isset($newpasswd)) &&
        (($code = verify_credentials($newuserid,$newpasswd)) !== 0))
    {
      // Render empty form with error message from prior attempt.
      addUserForm(array("code"=>$code
                       ,"form"=>"AddDbUser.php"
                       ,"userid"=>$newuserid));
    }
    else
    {
      // Create new user only when authenticated.
      if (!(isset($userid)) && (isset($_SESSION['userid'])))
       create_new_db_user($_SESSION['db_userid'],$newuserid,$newpasswd);

      // Render fresh empty form.
      addUserForm(array("form"=>"AddDbUser.php"));
    }
  }
  else
  {
    // Destroy the session and force re-authentication.
    session_destroy();

    // Redirect to the login form.
    signOnForm();
  }

The nested if statement filters calls to the create_new_db_user() function by ensuring that $newuserid and $newpasswd variables are set. These two variables can only be set in the AddDbUser.php Web page, which means these cannot be called until after your user has authenticated. This works on a subsequent call to the AddDbUser.php Web page because clicking the Add User button recursively calls the same Web page.

  // Add a new user to the authorized control list.
  function create_new_db_user($userid,$newuserid,$newpasswd)
  {
    // Attempt connection and evaluate password.
    if ($c = @oci_connect(SCHEMA,PASSWD,TNS_ID))
    {
      // Check for prior insert, possible on Web page refresh.
      if (!is_inserted($c,$newuserid))
      {
        // Encrypt password.
        $newpassword = sha1($passwd);

        // Return database UID.
        $s = oci_parse($c,"INSERT INTO system_user
                           ( system_user_id
                           , system_user_name
                           , system_user_password
                           , system_user_group_id
                           , system_user_type
                           , created_by
                           , creation_date
                           , last_updated_by
                           , last_update_date )
                           VALUES
                           ( system_user_s1.nextval
                           , :newuserid
                           , :newpasswd
                           , 1
                           , 1
                           , :userid1
                           , SYSDATE
                           , :userid2
                           , SYSDATE)");

        // Bind the variables as strings.
        oci_bind_by_name($s,":newuserid",$newuserid);
        oci_bind_by_name($s,":newpasswd", $newpassword);
        oci_bind_by_name($s,":userid1",$userid);
        oci_bind_by_name($s,":userid2",$userid);

        // Execute the query, error handling should be added.
        if (!@oci_execute($s,OCI_COMMIT_ON_SUCCESS))
        {
          // Print error when oci_execute() fails.
          $errorMessage = "Check for a missing SYSTEM_USER table.<br />";
          print $errorMessage;
        }
      }

      // Close the connection.
      oci_close($c);

    }
    else
    {
      $errorMessage = oci_error();
      print htmlentities($errorMessage['message'])."<br />";
    }
  }

Inside of the create_new_db_user() function, the function makes a call to the is_inserted() function. This checks to make sure that the user does not already exist before attempting to insert one into the SYSTEM_USER table. Like the earlier nested function examples, the is_inserted() function shares the local connection for transaction control purposes. Also, the sha1() function converts the clear text password to an encrypted string before binding the user password to the data manipulation variable.

After successfully inserting the new user, the New User form renders itself again waiting for you to insert another user or to click the Log Out button. The Log Out button returns you to the login screen, which resets your session identifier.

Conclusion

Now that you have learned how identity management works and how you can implement a basic identity management solution, you should be comfortable with the terminology, architecture, and approach to authenticating your users.

You can now manage user authentication and access equally, but all users are not equal. Some may have unrestricted access, while most others have restricted access privileges. Part 2 of this article shows you how to link identity management with two technologies that enable fine-grained access control.

Although the VPD feature is the "state of the art," the older technology, DBMS_APPLICATION_INFO, also works in Oracle8i, Oracle9i, and Oracle Database 10g Release 1. It is also the core utility supporting Oracle E-Business 11i Suite authentication. Both these technologies let you implement fine grained access privileges and roles.

This article describes a makeover of a typical database-backed web form. We'll show some old code – a mixture of HTML, JavaScript, and PHP – and rebuild it with modern web techniques like Ajax, and modern tools like jQuery. The benefits will include:

• Separating dynamic content from static content.
• Separating content, style, and processing.
• Web client-server communication via function calls.
• Partial page updates instead of flash-bang page reloads.
• Faster development and more maintainable code.
• Faster load times and improved caching.

The Old Grey Web

In the beginning was HTML, shortly followed by forms, client-side JavaScript, and server-side CGI scripts. You would fill in form variables and submit the form to the CGI script, or generate a long GET-style URL in JavaScript. JavaScript was close to undebuggable. Core variables like window were not part of the language, and the Microsoft-Netscape browser wars introduced gratuitous differences that continue to plague us. Things got a little better over time, as the W3C defined the DOM and developers built cross-platform DHTML libraries.

Some dynamic pages are easy, you query the database once and dump some nicely formatted HTML, but most are harder. Database values populate pull-down menus (HTML select and option tags) and choices (radio and checkbox tags). Some forms cover multiple pages, and the logic for maintaining overall state gets trickier. Every form submission returns a fully regenerated page, maintaining all the state of the previous submissions.

Traditional options on how to structure the application include:

• Put everything in a single script. On the first call, query the database and generate HTML and form elements. On subsequent calls, the form passes a command (such as add, change, or delete) and any arguments (such as the person's ID, if change or delete). The script modifies the database and again rewrites the page's content. The form elements must reflect the database changes.
• Use two scripts. The first queries the database and generates the HTML, with two differences from the previous example:
  • The form has an iframe for displaying dynamic contents.
  • The form's action is the second script.
  • The form's target is the name of the iframe.

  Now the form is generated once and its elements maintain their values across form submissions. The output of the second script is displayed in the iframe.

The second option sounds better, but it still has problems: if an action changed the data underlying the form elements in the enclosing page, the whole page needs to be regenerated. We need a third option.

The New Toolbox

The common restriction is the whole-page design. No matter what you do, no matter how small the change, you submit it to the server and get back a brand new page (an iframe is like a mini-page, and its size can't be changed). A variety of JavaScript remoting techniques have tried to make the web client-server connection work more like a procedure call. I think the most useful contributions are:

• innerHTML
• XMLHttpRequest
• Ajax
• JSON
• New JavaScript libraries

innerHTML

This DOM attribute, introduced by Microsoft in IE4, is a de facto (not official W3C) standard supported by all modern browsers. With it, you get and set the contents between any HTML start and end tags, without a page refresh. This chunk of HTML:

<p id="changeme">Now you see it.</p>

can be modified by this chunk of JavaScript:

var obj = document.getElementById("changeme");
obj.innerHTML = "Now you don't";

to produce this:

<p id="changeme">Now you don't</p>

Although the DOM has functions to change page elements dynamically, innerHTML is simpler and faster. Unfortunately, innerHTML is a read-only attribute for many table elements in IE, forcing use of alternatives.

 

XMLHttpRequest

This is an API to send client requests to the server and receive the server responses. Microsoft invented it to make Outlook Web Access work more like a desktop application. It was included in IE5 and is supported by all modern browsers. Combined with innerHTML, you can call a server script and use the data returned to update any element on the page. Despite its utility, this function was hidden in plain sight for years (you wouldn't find it in JavaScript or DHTML books). Things changed when Google Mail, Maps, and Suggest demonstrated its responsiveness and introduced a new web application model.

 

Ajax

The dam burst in 2005, when Jesse James Garrett named the new model Ajax (Asynchronous JavaScript and XML), comprising XMLHttpRequest, the DOM, and other techniques. The brand and its timing were perfect, rejuvenating web development and rehabilitating JavaScript.

 

JSON

The old remoting frameworks used various formats for the client-server data stream, and XMLHttpRequest, as the name suggested, used XML. Doug Crockford designed the light and simple JSON (JavaScript Object Notation) format. It's trivial to parse JSON into JavaScript data structures (just eval(json_string)), and faster than deconstructing XML.

 

JavaScript libraries

High-quality JavaScript libraries have been developed to simplify new-model web development and bridge the inevitable cross-browser issues. I've chosen John Resig's jQuery over worthy competitors like Prototype, Dojo, or YUI for a number of reasons:

• Compactness: About 19KB compressed
• Chainability: Calls can be chained for more compact code
• Support: Good documentation and development community
• Flexibility: Its selector syntax includes CSS 1-3 and XPath phrases to select page elements
• Architecture: Easy to extend through add-ons and plugins

The Makeover

History class is over, and beauty class begins.

To make the presentation clear and short, our code examples ignore errors and possible security issues. The purpose is to show how jQuery and Ajax techniques can improve an old script. For production use, you would check function error returns, untaint input data, and follow the other rules of good web hygiene. With the new Ajax methods, an error in the client or server code can cause a silent failure. FireBug is a very handy tool for developing and debugging Ajax applications. The full-featured version is a Firefox plugin, but a light version is available for IE and other browsers.

Let's define our form's requirements:

1. Get data from a people table in a database. The id column is the primary key.
2. Display the names in a pull-down menu (a form select element).
3. Let the user select a person from the menu.
4. Display information about that person in a table: first name, last name, favorite dance, and favorite pie.

This example assumes the number of people will fit in an HTML select element without killing the browser. Larger data would require a paged table or something similar. The page should look something like this:

People

Version 1: Original Code

In the original version we do everything in a single PHP script: write the static HTML, create the original list of people, and fill in the lower table if a person had been selected.

people1.php:
<?php
$cmd    = @$_REQUEST["cmd"];
$id     = @$_REQUEST["id"];
mysql_connect($server, $user, $password);
mysql_select_db("test");
?>
<html>
<head><title>Old Form</title>
<script>
// Get the selected user and retrieve his/her info
function user_info(sel)
        {
        var opt    = sel.options;
        var user_id    = opt[sel.selectedIndex].value;
        // Construct a GET URL, or create a hidden field for "cmd"
        var url  =  "people1.php?cmd=info&id=" + user_id;
        window.location.href = url;
        }
</script>
</head>
<body>
<form action="people1.php" method="post">
People<br>
<select name="people" onchange="user_info(this)">
<option value="">(select a person)
<?php
// Get all users and display every time script is called
$result = mysql_query("select id, fname, lname from people");
while ($row = mysql_fetch_array($result, MYSQL_ASSOC))
        echo "<option value='$row[id]'",
                $row["id"] == $id ? " selected" : "",
                ">$row[fname] $row[lname]\n";
?>
</select>
<?php
if ($cmd == "info")
        {
    $id     = mysql_real_escape_string($id);
        $result = mysql_query("select * from people where id='$id'");
        $info = mysql_fetch_array($result, MYSQL_ASSOC);
        }
else
        $info = array("fname"=>" ", "lname"=>" ", "dance"=>" ", "pie"=>" ");
echo <<< END
<br>
<table border=1>
<tr>
<td>First Name</td><td>Last Name</td><td>Dance</td><td>Pie</td></tr>
<tr>
<td>$info[fname]</td>
<td>$info[lname]</td>
<td>$info[dance]</td>
<td>$info[pie]</td>
</tr>
</table>

END;
?>
</form>
</body>

New Design

Here's the plan:

1. Split the initial script into three files: static content (HTML), client-side processing (JavaScript), and server-side processing (PHP).
2. Include jquery.js and the new JavaScript file in the HTML file.
3. Add a unique id attributes to all dynamic content tags.
4. Define JavaScript functions to make Ajax-style server calls and update page elements.

We can merge the dynamic and static content in one of two ways:

• PHP returns the dynamic content as HTML, and JavaScript stuffs it into a page element with innerHTML.
• PHP returns the dynamic content in a JSON-format data array, and JavaScript builds and inserts the HTML into the target page element.

Let's try both.

Version 2: Ajax Submit, HTML Return

In this method, PHP generates the HTML for the option tags, and we just stuff the HTML into the enclosing select. Now we start with an HTML file, and it's just a container:

people2.html:
<html>
<head><title>New Form Version 1</title>
<script src="jquery.js"></script>
<script src="people2.js"></script>
</head>
<body>
People<br>
<select id="people">
</select>
<br>
<table border=1>
<thead>
<tr><td>First Name</td><td>Last Name</td><td>Dance</td><td>Pie</td></tr>
</thead>
<tbody id="info">
<tr>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</body>
</html>

Now let's look at the JavaScript file. jQuery's central function is $(), which returns a jQuery object. Its arguments may have many forms, but we'll use these now:

• $(document): Selects the DOM document object.
• $("#myid"): Selects the element with id="myid".

The jQuery call $(document).ready replaces window.onload. It's called when the DOM is ready, instead of waiting for all images to load. This avoids synchronization problems. All of the JavaScript functions that work with form elements can be in here.

The load() function calls the server script people.php and inserts its output into the select element with id people. This is the equivalent of the first chunk of the original version. It makes an Ajax connection to the server, and inserts the returned HTML into the element with id people:

(I've spread out the formatting to help distinguish the parentheses and curly brackets.)

people2.js:
$(document).ready
    (
    function()
        {
        // Call this when the DOM is ready:
        $("#people").load("people2.php?cmd=init");
        // Call this when a person is selected:
        $("#people").change(function()
            {
            // get the user's id from the selected option:
            var user_id = $(":selected").val();
            $("#info").load("people2.php?cmd=info&id=" + user_id);
            });
        }
    );

For this version, that's all the JavaScript we need. By the way, this approach has been called AHAH (Asynchronous HTML and HTTP). Now we'll look at the PHP script it calls. This version is like the original, but it only prints the HTML fragment for the current query:

people2.php:
  <?php

  $cmd    = @$_REQUEST["cmd"];
  $id    = @$_REQUEST["id"];
  mysql_connect($server, $user, $password);
mysql_select_db("test");
if ($cmd == "init")
        {
        $result = mysql_query("select id, fname, lname from people");
        echo "<option value=''>(select a person)\n";
        while ($row = mysql_fetch_array($result, MYSQL_ASSOC))
                echo "<option value='$row[id]'>$row[fname] $row[lname]\n";
        }
elseif ($cmd == "info")
        {
        $id     = mysql_real_escape_string($id);
        $result = mysql_query("select * from people where id='$id'");
        $info = mysql_fetch_array($result, MYSQL_ASSOC);
        echo <<< END
<tr>
<td>$info[fname]</td>
<td>$info[lname]</td>
<td>$info[dance]</td>
<td>$info[pie]</td>
</tr>

END;
        }
?>

Although you could call this approach AJAJ, thankfully no one does.

Version 3: Ajax Submit, JSON Return

In this alternative, PHP builds a data array from the database query and returns it to JavaScript in JSON format. jQuery converts this JSON string into a jQuery object and passes it to a callback function, which builds the HTML for the options and inserts it into the appropriate page element. This example is the same as people2.html, except it calls people3.js:

people3.html:
<html>
<head><title>New Form Version 1</title>
<script src="jquery.js"></script>
<script src="people3.js"></script>
</head>
<body>
People<br>
<select id="people">
</select>
<br>
<table border=1>
<thead>
<tr><td>First Name</td><td>Last Name</td><td>Dance</td><td>Pie</td></tr>
</thead>
<tbody id="info">
<tr>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
</body>
</html>

We're just going to fill the container in a different way. In this version, we call getJSON with three arguments:

• The URL
• A dictionary of name:value pairs
• A JavaScript callback function.

A GET URL will be built from the URL and name:value arguments, and the returned JSON string will be converted into a JavaScript object and passed to the callback function.

people3.js:
 $(document).ready
        (
        function()
                {
        // Call this when the DOM is ready:
                $.getJSON("people3.php",
                        { cmd : "init" },
                        make_menu);
        // Call this when a person is selected:
                $("#people").change(function()
                        {
                        var user_id = $(":selected").val();
                        $.getJSON("people3.php",
                                { cmd : "info", id: user_id  },
                                make_info);
                        });
                }
        );
function make_menu(obj)
        {
        var str = "";
        var len = obj.length;
        str += "<option value=''>(select a person)\n";
        for (var i = 0; i < len; i++)
                {
                var user = obj[i];
                str += "<option value='" + user["id"] + "'>" +
                        user["fname"] + " " +
                        user["lname"] + "\n";
                }
        $("#people").html(str);
        }
function make_info(info)
        {
        var str = "<tr>";
    // You can get each value as info.name or info["name"].
    // Let's get the first name using the first way.
        str += "<td>" + info.fname + "</td>";
        str += "<td>" + info["lname"] + "</td>";
        str += "<td>" + info["dance"] + "</td>";
        str += "<td>" + info["pie"] + "</td>";
        str += "</tr>\n";
        $("#info").html(str);
        }

This version of the PHP script is even simpler than people2.php. Instead of creating HTML from the database return values, we just encode the PHP data array in JSON format and send it off:

people3.php:
<?php
$cmd    = @$_REQUEST["cmd"];
$id     = @$_REQUEST["id"];
mysql_connect($server, $user, $password);
mysql_select_db("test");
if ($cmd == "init")
        {
        $result = mysql_query("select id, fname, lname from people");
        $user_array = array();
        while($row = mysql_fetch_array($result, MYSQL_ASSOC))
                $user_array[] = $row;
        echo json_encode($user_array);
        }
elseif ($cmd == "info")
        {
        $id = mysql_real_escape_string($id);
        $result = mysql_query("select * from people where id='$id'");
        $info = mysql_fetch_array($result, MYSQL_ASSOC);
        echo json_encode($info);
        }
?>

The json_encode function is included with standard PHP starting with version 5.2. For earlier versions, see the PHP JSON manual section.

If you chose our friend Alfredo from the menu, the JSON returned would look like this:

{"id":"1","fname":"Alfredo","lname":"de Darc","dance":"tango","pie":"blueberry"}

That JSON string is converted to a JavaScript object by jQuery and passed to the make_menu function as the info argument.

Judging the Makeover

The main choice between these new versions is where to do the output formatting: in PHP (version 2) or in JavaScript (version 3). Another factor might be what other plans you have for the data. Instead of throwing info away after generating the HTML in version 3, you could save it in a global JavaScript variable and use it for other purposes later.

Are these new versions better than the original? Let's see if our original promises were kept:

Separating dynamic content from static content.

All the static content is in the HTML file, and the dynamic data from the PHP script are processed in JavaScript for page placement.

 

Separating content, style, and processing.

We didn't show it here, but a separate CSS file would be a nice orthogonal addition.

 

Web client-server communication via function calls.

Good old Ajax.

 

Partial page updates instead of flash-bang page reloads.

Ajax again.

 

Faster development and more maintainable code.

PHP now just gets data from the database and returns output chunks (HTML or JSON) rather than whole pages.

 

Faster load times and improved caching.

people2.html, people2.js, people3.html, and people3.js are static files that will be cached by the browser (and the web server, which will make the application more scalable). The whole output page is also cached, the only changes being performed by JavaScript within the browser. Finally, we avoid a database lookup in every call to people2.php or people3.php after the first one.

The most important benefit is that the new approach will scale much better with future requirements, such as adding a new person or editing the data of an existing person. And new requirements are as sure as death and taxes.

This article covers the implementation of a system that lets you easily define the order of such a list.

Traditionally, implementations of such functionality involve you clicking a “move up”, “move down”, “move to top”, or “move to bottom” button that switches the order the items (one item at a time). Or perhaps each item has a text box with a number in it, that by changing the numbers you can change the order of the list.

In any case, these methods are much more difficult to use than they should be. In this article, we’ll create a drag drop system using JavaScript that will let you drag an item to its new position, and then save the new order as soon as you drop the item.

To achieve the Ajax effects (that is, the drag/drop effect, and the seamless saving of ordering data), we will be using the Prototype and Scriptaculous libraries.

Firstly, we will create a database table (compatible with MySQL and PostgreSQL) and populate it with data. Then we will output our list and apply the drag and drop effects to it. Finally, we will deal with the saving of the new ordering data.

For our example, we will use a list of “favourite movies”, and implement functionality to change the order of our movies.

Creating Our Database And Populating It

We will now create the database table we need in order to create this example. We won’t be writing all the code for inserting, editing and deleting of data, as it is beyond the scope of this example. As such, we will simply provide insert statements to create a static list of data.

The examples below are for PostgreSQL and MySQL.

Create your database

First up, you need to create a database for this article. This may be in either PostgreSQL or MySQL. Additionally, you may need to setup a username and password to access the database, depending on your system setup.

MySQL database schema

create table movies (
    movie_id    int             not null    auto_increment,
    title       varchar(255)    not null,
    ranking     int,

    primary key (movie_id)
);

PostgreSQL database schema

create table movies (
    movie_id    serial          not null,
    title       varchar(255)    not null,
    ranking     int,

    primary key (movie_id)
);

Database data

insert into movies (title) values ('American Pie');
insert into movies (title) values ('Die Hard');
insert into movies (title) values ('Clerks');
insert into movies (title) values ('Air Force One');
insert into movies (title) values ('Titanic');
insert into movies (title) values ('The Shawshank Redemption');
insert into movies (title) values ('Gone In 60 Seconds');

About the schema

The database table is fairly simple, it just consists of an ID, a movie title, and a field to store the ordering. There’s no particular reason why the ranking field is allowed to be null, other than the values won’t be set when we initially insert our data.

If we were being really tricky, we would write a trigger on the database that would assign the next ranking value when a row is inserted, but that is beyond the scope of this article.

Outputting The Database Data

Now that we’ve made and populated our database, we’re going to write a PHP script to connect to this database and select all of this data. Because we are making both a MySQL version and a PostgreSQL version, some of this code will be implemented twice (once for each).

Hopefully you are using database abstraction in your web applications, but for the purpose of this article we’ll assume that you aren’t.

database.php for MySQL

<?php
    function dbConnect()
    {
        $link = mysql_connect('localhost', 'username', 'password');
        if (!$link)
            return false;

        return mysql_select_db('phpriot');
    }
?>

database.php for PostgreSQL

<?php
    function dbConnect()
    {
        $str = sprintf('host=%s user=%s password=%s dbname=%s',
                       'localhost',
                       'username',
                       'password',
                       'phpriot');
        $link = pg_connect($str);

        return (bool) $link;
    }
?>

movies.php for MySQL

<?php
    function getMovies()
    {
        $query = 'select movie_id, title from movies order by ranking, lower(title)';
        $result = mysql_query($query);

        $movies = array();
        while ($row = mysql_fetch_object($result)) {
            $movies[$row->movie_id] = $row->title;
        }

        return $movies;
    }
?>

movies.php for PostgreSQL

<?php
    function getMovies()
    {
        $query = 'select movie_id, title from movies order by ranking, lower(title)';
        $result = pg_query($query);

        $movies = array();
        while ($row = pg_fetch_object($result)) {
            $movies[$row->movie_id] = $row->title;
        }

        return $movies;
    }
?>

index.php for MySQL and PostgreSQL

Here’s the main script that displays the list of movies. It is the same for both MySQL and PostgreSQL, as it will include the necessary code. At this point it is not styled and it is not yet possible to change the ordering. We’ll be adding each of those things in next.

<?php
    require_once('database.php');
    require_once('movies.php');

    if (!dbConnect()) {
        echo 'Error connecting to database';
        exit;
    }

    $movies = getMovies();
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html>
    <head>
        <title>phpRiot Sortable Lists</title>
    </head>
    <body>
        <h1>phpRiot Sortable Lists</h1>

        <ul id="movies_list">
            <?php foreach ($movies as $movie_id => $title) { ?>
                <li><?= $title ?></li>
            <?php } ?>
        </ul>
    </body>

.sortable-list {
    list-style-type : none;
    margin : 0;
}
.sortable-list li {
    border : 1px solid #000;
    cursor : move;
    margin : 2px 0 2px 0;
    padding : 3px;
    background : #f7f7f7;
    border : #ccc;
    width : 400px;
}

Sortable.create('movies_list');

<?php
    require_once('database.php');
    require_once('movies.php');

    if (!dbConnect()) {
        echo 'Error connecting to database';
        exit;
    }

    $movies = getMovies();
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html>
    <head>
        <title>phpRiot Sortable Lists</title>
        <link rel="stylesheet" type="text/css" href="styles.css" />

        <script type="text/javascript" src="scriptaculous-js-1.5.3/lib/prototype.js"></script>
        <script type="text/javascript" src="scriptaculous-js-1.5.3/src/scriptaculous.js"></script>
    </head>
    <body>
        <h1>phpRiot Sortable Lists</h1>

        <ul id="movies_list" class="sortable-list">
            <?php foreach ($movies as $movie_id => $title) { ?>
                <li id="movie_<?= $movie_id ?>"><?= $title ?></li>
            <?php } ?>
        </ul>

        <script type="text/javascript">
            Sortable.create('movies_list');
        </script>
    </body>

<?php
    function processMoviesOrder($key)
    {
        if (!isset($_POST[$key]) || !is_array($_POST[$key]))
            return;

        $movies = getMovies();
        $queries = array();
        $ranking = 1;

        foreach ($_POST[$key] as $movie_id) {
            if (!array_key_exists($movie_id, $movies))
                continue;

            $query = sprintf('update movies set ranking = %d where movie_id = %d',
                             $ranking,
                             $movie_id);

            mysql_query($query);
            $ranking++;
        }
    }
?>

<?php
    function processMoviesOrder($key)
    {
        if (!isset($_POST[$key]) || !is_array($_POST[$key]))
            return;

        $movies = getMovies();
        $queries = array();
        $ranking = 1;

        foreach ($_POST[$key] as $movie_id) {
            if (!array_key_exists($movie_id, $movies))
                continue;

            $query = sprintf('update movies set ranking = %d where movie_id = %d',
                             $ranking,
                             $movie_id);

            pg_query($query);
            $ranking++;
        }
    }
?>

<?php
    require_once('database.php');
    require_once('movies.php');

    if (!dbConnect())
        exit;

function updateOrder()
{
    var options = {
                    method : 'post',
                    parameters : Sortable.serialize('movies_list')
                  };

    new Ajax.Request('processor.php', options);
}

Sortable.create('movies_list', { onUpdate : updateOrder });

<?php
    require_once('database.php');
    require_once('movies.php');

    if (!dbConnect()) {
        echo 'Error connecting to database';
        exit;
    }

    $movies = getMovies();
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html>
    <head>
        <title>phpRiot Sortable Lists</title>
        <link rel="stylesheet" type="text/css" href="styles.css" />

        <script type="text/javascript" src="scriptaculous-js-1.5.3/lib/prototype.js"></script>
        <script type="text/javascript" src="scriptaculous-js-1.5.3/src/scriptaculous.js"></script>
    </head>
    <body>
        <h1>phpRiot Sortable Lists</h1>

        <ul id="movies_list" class="sortable-list">
            <?php foreach ($movies as $movie_id => $title) { ?>
                <li id="movie_<?= $movie_id ?>"><?= $title ?></li>
            <?php } ?>
        </ul>

        <script type="text/javascript">
            function updateOrder()
            {
                var options = {
                                method : 'post',
                                parameters : Sortable.serialize('movies_list')
                              };

                new Ajax.Request('processor.php', options);
            }

            Sortable.create('movies_list', { onUpdate : updateOrder });
        </script>
    </body>

function updateOrder()
{
    // turn on update message here

    var options = {
                    method : 'post',
                    parameters : Sortable.serialize('movies_list'),
                    onComplete : function(request) {
                        // turn off update message here
                    }
                  };

    new Ajax.Request('processor.php', options);
}

As a PHP programmer I had run into a problem where a client needed a form to upload more than one file at a time. So one night I sat down and spent an hour figuring out the best and easiest way to do this. In this tutorial, the for loop is going to be your best friend.