• Submission and Late Policy: Programming work submitted after the deadline but less than 24 hours late (i.e., by Friday 11:59 PM) will be accepted but penalized 10%, and programming work submitted more than 24 hours but less than 48 hours late (i.e., by Saturday 11:59 PM) will be penalized 30%. No programming work will be accepted more than 48 hours late. Since emergencies do arise, each student is allowed a total of four unpenalized late days (four periods up to 24 hours each) for challenge problems, query assignments, and programming work, but no single assignment may be more than two days late. See the Assigned Work page for more information.

• Honor Code reminder: For more detailed discussion of the Stanford Honor Code as it pertains to CS145, please see the Assigned Work page under Honor Code. In summary: You must indicate on all of your submitted work any assistance (human or otherwise) that you received. Any assistance received that is not given proper citation will be considered a violation of the Honor Code. In any event, you are responsible for understanding and being able to explain on your own all material that you submit.

• Reminder: Projects must be completed individually.

Overview

Getting familiar with PHP

Even if you haven't used PHP before (and we're assuming you haven't), it may be possible to complete the basic project with minimal help from additional PHP materials. However, if you like to read tutorial materials before jumping in, or if you're feeling confused about PHP, we recommend this PHP MySQL Introduction. This reference, and many others you may find useful, are linked to the class Support Materials page.

• Step 1: Activate Personal CGI Service (if you haven't already)

  Activation can take up to 24 hours. We hope you completed this step when it was first suggested in the Project Part 2 specification. Visit Activate Personal CGI Service and follow the instructions to activate your CGI account. Once activated, you will have a new directory ~/cgi-bin/.
  

• Step 2: Copy Sample PHP Code

  Copy the sample PHP code we are providing into your cgi-bin directory:

     cp /usr/class/cs145/pa3sample/* ~/cgi-bin/.
  

• Step 3: Configure Files and View Samples

  In your cgi-bin directory you first need to configure the mysqlvars.php file with your MySQL username, password, and database name. Then, for a first sample of how PHP pages work, visit the URL:

     http://www.stanford.edu/~[yourname]/cgi-bin/currtime.php
  

  where [yourname] is your SUNet ID. At this URL you should see the current time as reflected in your Time table. If this code doesn't work, you may need to edit currtime.php so that it uses your Time table (named Time in the sample) and the correct attribute within your Time table (named currenttime in the sample -- note there are two references). At this point, your currtime.php should be working.

• Step 4: Examine the Sample Code

  File currtime.php gives an example of how to use PHP to connect to MySQL, execute commands, and process the results. A second sample file, selecttime.php, is designed to help you get familiar with input boxes. (File kill.php will be discussed later.) Examine the sample code, and feel free to adapt this code directly for your project. If you're having trouble understanding the sample code, we recommend the PHP MySQL Introduction mentioned earlier.

• Some notes on the sample PHP code

  • File currtime.php connects to MySQL using mysqli_connect, as opposed to mysql_connect. We have chosen to use MySQLi ("MySQL Improved Extension") for its improved support of transactions. For more on how to use MySQLi with transactions, please see MySQLi and Transactions, as well as the section on Transactions, errors, and constraint-checking below.
  • Since there is only one tuple in the Time table, currtime.php does not need to use a loop. For an example of how to loop through a set of result tuples, please see PHP MySQL Select from the tutorial.
  • The operator (.) is PHP's string concatenation operator. Please see PHP String for more information.
  • File selecttime.php uses the $_POST variable. This variable is used to collect values from an HTML form with method="post". Please see PHP POST for more details.

Functionality

• Ability to manually change the "current time."
• Ability for auction users to enter bids on open auctions.
• Automatic auction closing. An auction is "open" after its start time and "closed" when its end time is past or its buy price is reached. Your design may be such that an auction closes implicitly with high enough bids or a time update, or you may have chosen to represent open/closed status with an explicit data field.
• Ability to see the winner of a closed auction.
• Ability to browse auctions of interest based on some simple input choices such as category, price, and open/closed status. Please include a minimum of three different choices.
• Ability to find an (open or closed) auction based on itemID.

Full credit also requires general error- and constraint-checking as specified in the Transactions, errors, and constraint-checking section of this document, below. All of your required constraints from Part 2 of the project should be enforced in your "live" AuctionBase system.

Here are some examples of additional capabilities beyond our basic expectations that you might consider adding to your system if you're feeling ambitious. Use your imagination to come up with even more.

• Ability for new auction users to provide information to be entered into the database (name, initial rating if not assigned automatically, optional location and country).
• Ability for auction users to add new items up for auction.
• Ability to retrieve auction or bidding history for a given user, including current auctions or bids.
• Ability to browse auctions of interest based on even more input choices, such as date, substring match in description, etc.
• Ability to run some statistics over the auctions. Possibilities include average number of bids per user, highest selling price over initial bid, average time to reach buy-price, etc.

Miscellaneous hints and requirements

• You don't have to implement user authentication. For example, it's okay to ask the user to enter his username when bidding, without asking for a password.
• If you allow new auction items to be entered into your database, you will need to automatically generate unique itemID's for them. You may do so any way you like.
• When you generate dynamic HTML pages from your program, use relative paths for URLs, i.e., do not hard-code the machine name and port number into your program. (We will almost certainly be testing your program on a different machine.) With relative paths the browser will automatically find the right machine and port number.
• Important: The special characters &, <, and > need to be replaced in HTML by the escape strings "&amp;", "&lt;", and "&gt;" (without the quotes) respectively, so they can be displayed properly. We expect you to escape all three characters in displayed data even if you are testing on a browser that does not require it (you may find the PHP function htmlspecialchars useful).

Transactions, errors, and constraint-checking

If it helps, you may assume that AuctionBase has only one user operating on it at a time. Although transactions may be useful for database modifications and constraint-checking, you do not need to worry about transactions as a concurrency-control mechanism. That said, even without special effort your system may turn out to be fairly robust for multiple users.

Reminder: You must create your tables using the "InnoDB" storage engine for constraint-checking and transactions to work properly.

   <?php

    // kill script after 20 seconds
    set_time_limit(20);

    // function to handle errors: rollback and exit
    function error_exit ($con, $errormsg="unspecified"){
       echo "We're sorry: a system error occurred.<p></p>";
       echo "Error Message: " . $errormsg;
       mysqli_rollback($con);  // if error, roll back transaction
       mysqli_close($con);
       exit();
    }

    // establish MySQL connection
    $link = mysqli_connect($host,$username,$password,$dbname);
    if (mysqli_connect_errno()) {
       printf("Connect failed: %s\n", mysqli_connect_error());
       exit();
    }

    // step 1: turn off auto-commit
    $result = mysqli_autocommit($link, FALSE);
    if (!$result) {
       error_exit($link, "autocommit");  // if error, roll back transaction
    }

    // step 2: perform action
    // run command 1
    $com1 = "select/insert/delete/update ... ";
    $result = mysqli_query($link, $com1);
    if (!$result) {
       error_exit($link, "com1");  // if error, roll back transaction
    }

    // run command 2
    $com2 = "select/insert/delete/update ... ";
    $result = mysqli_query($link, $com2);
    if (!$result) {
       error_exit($link, "com2");  // if error, roll back transaction
    }
   
    // step 3: assuming no errors, commit transaction
    $result = mysqli_commit($link);
    if (!$result) {
       error_exit($link, "commit");  // if error, roll back transaction
    }
    echo "Success";

    // close connection
    mysqli_close($link);
    ?>

• set_time_limit(20) prevents this script from running longer than 20 seconds (excluding time spent running tasks such as database queries). Placing this command at the top of your PHP scripts will help prevent your system from leaving open a large number of MySQL connections. Note in particular that closing the browser after visiting a PHP script does not stop the script's execution, so leaving connections open can occur easily without this time limit.
• The error_exit function, declared next, is called whenever an error occurs. It prints an error message, then rolls back the current transaction and exits.
• We use mysqli_connect to open a MySQL connection, then we turn off "autocommit" using mysqli_autocommit($link, FALSE). Doing so commits any currently uncommmited commands, then starts a new transaction.
• Next the actual database operations comprising the transactional unit are performed, consisting of one or more select/insert/delete/update commands. In the above code, we have two commands, $com1 and $com2. We first call mysqli_query with the command $com1. A return value of FALSE indicates that an error occurred. (This is the point at which a constraint violation or trigger error is caught; other errors are possible here as well.) If an error has occurred, we call error_exit. Executing $com2 is similar.
• Assuming no errors have occurred up to this point, we commit the transaction by calling mysqli_commit, then close the MySQL connection using mysqli_close. Although connections are closed automatically at the end of PHP scripts, it is still good practice to close connections explicitly.

User interface

Browser compatibility

When the preapproval process is not followed, projects that have problems on the Myth Firefox browsers may lose points, possibly all points if we cannot run your project at all.

System testing and open connections

If you notice an unexplained slowdown in system performance, it may be due to a large number of open MySQL connections. Here are some tips to avoid this problem:

• Ctrl-Z does not kill queries or close connections in the MySQL command-line interface; it only suspends the client. Queries should be killed using Ctrl-C.
• If you do use Ctrl-Z, follow up afterwards with "ps aux | grep [username]" to find your process ID, then "kill [processID]" to kill the process. Otherwise the MySQL connection remains open.

• Remember to use set_time_limit(20) at the top of your PHP scripts to prevent MySQL connections from remaining open indefinitely. Note again that closing the browser after visiting a PHP script does not stop the script's execution.
• In the MySQL command-line client, "show processlist" shows the list of MySQL processes, and a process can be killed with "kill [Id]". Alternatively, to kill all open connections, visit the page kill.php, which we provided with the sample code.

Using other languages and tools

Most importantly: It is imperative that we can run your project with a minimum of effort on the Myth machines. Due to the size of the class we will not be able to set up separate environments for individual projects, or conduct private demos.

Having trouble?

What to submit

Your README.txt file should include at least the following, in this order:

1. The line "I WOULD LIKE TO ENTER THE AUCTIONBASE CONTEST" if you want your project to be considered for the contest described below. Otherwise leave blank.
2. A description of how the user gets to each of the basic capabilities required by the assignment.
3. A short description of the input parameters a user can provide when browsing auctions.
4. A list of any capabilities in your system beyond the basic requirements, how the user gets to them, and a short description of any relevant input parameters.

Since we will be connecting to your MySQL database through your web application, make sure that before submission and throughout the grading period your database is loaded with all of the appropriate data, constraints, and triggers.

If you did not use PHP: It's imperative that we can run your project with a minimum of effort on the Myth machines. You must submit detailed instructions and all of your source code.

As usual, from your submission directory execute the script:

    /usr/class/cs145/bin/submit-project

Remember that points may be deducted if you do not follow the submission procedures exactly as specified.

The (Optional) CS145 AuctionBase Contest

We will select a small number of AuctionBase systems as winners of our annual CS145 AuctionBase Contest. Winners of the contest will:

• Demonstrate their projects to the class and the world (via Stanford Online) as part of the last class meeting on December 2.
• Logistics permitting, have their running systems linked to the CS145 home page for anyone to try.
• Be invited to enjoy lunch at the Stanford Faculty Club with Prof. Widom, the TA's, and the other contest winners.
• Receive no extra credit, just the extra recognition.

Important - If you want your project to be considered for the contest, you must clearly indicate so at the top of your README file, as described in What to submit above.