Homework 6 - Anagrams Database Edition

Due: Wednesday, March 26, 2025 at 11:59pm

Purpose:

  • Gain experience persisting state in PHP using PostgresSQL
  • Manage security in handling passwords and database queries

Overview

For this homework, you may work alone or with another student in this course. You will implement an Anagrams game, as described in Homework 5. It must have the functionality described in that homework, along with the additional functionality described below. You should start with your prior homework code; however, you may use the in-class Trivia Game as a starting point or you may implement everything from scratch.

Anagrams Base Requirements

See Homework 5

Maintaining State

Modify your Anagrams game to persist state across user sessions. That is, we’ll need to ask the user to log in with a password and store authentication and information about the users’ games in the database.

For this assignment, you must implement the following changes and components. (You may implement more functionality if you wish, for example highlighting the table cells of their prior guess, but remember that we’ll be grading on effort in implementing these components below.)

  1. Homework 5 Anagrams game
    • You must fulfill all the requirements of Homework 5 as a starting point for this assignment. As part of that, you must have an index.php file and an AnagramsGameController that contains the controller to handle all of the logic for your application.
  2. Updated welcome screen: it must ask the user for at least their name, email, and password. You may use the welcome page you created for Homework 5 or our example from the Trivia game.
  3. Authentication logic. The user must be able to log in and their session must be tracked until they log out.
    • The user must be able to enter at least their name, email, and a password.
    • If the user is in the database (determined by their email address), then verify their password. If the password succeeds, then display the game page and allow the user to play (starting a new game). If the password verification does not succeed, then display the welcome page again with a message to the user alerting them that their password was incorrect.
    • If the user is not in the database, add them as a new user and display the game page and allow the user to play (starting a new game).
  4. Game logic and state updates.
    • All of the users’ prior target words should be stored into the database. When a user begins a new game, they must not get a word that they have already played. Hint: it is likely that two different users may have had the same target word. Think about any additional tables you may need if the target words are stored in hw6_words.
    • Game statistics should be stored into the database, kept up-to-date across sessions, and displayed to the user. At a minimum, you should display the following statistics to the user on the game page and game over page:
      • Number of overall games played (i.e., total number of prior words that the user has ever played).
      • Percentage of games won (i.e., those where the user correctly guessed the 7-letter target word).
      • Highest score achieved.
      • Average score across all games played.
      • Hint: think about how any additional tables from above may be modified to keep track of some of these stats more easily. That is, you will likely want a link/join table.
    • If a user logs out without finishing their game, that game is considered lost. Update the game statistics in the database appropriately. You do not need to keep track of the current progress of a game in the database to be resumed later.
  5. Database requirements: user information and game statistics information should be stored in your PostgresSQL database.
    • While you may choose to determine the overall organization of your database, you must include at least two tables:
      • hw6_users that stores the information about the user. That includes at least the following: name, email, password.
      • hw6_words that stores a subset of the 7-letter target words that have already been played.
      • You will likely need additional tables to implement all the required functionality.
    • Define your database schema (i.e., the structure of your database tables). Since you only have one database on the cs4640 server, I highly encourage you to add a prefix (such as hw6_) to all your table names for this assignment so that they don’t interfere with tables used later in the course.
      • Create an initialization script to build all the tables and sequences needed for your Anagrams game:
        • If the tables/sequences already exist in the database, your script should automatically drop them first.
        • It must be written in either SQL (i.e., a .sql file that can be loaded into PSQL or PhpPGAdmin) or a simple PHP script (i.e., it would be placed in the www folder and accessed under Apache).
        • It should have enough comments/documentation that we can quickly determine your overall database schema (i.e., if there is a link/join table, how does it work?)
          • If you use plain SQL, comment lines start with: --
    • You may choose to use the Database and Config classes (provided in the example code in /web/src/example) in your updated AnagramsDB application. If you choose to use them, you should upload them with your codebase.
      • Reminder: you will need to update the Config variables when publishing your code to the cs4640 server. They can be set as follows (which is different from the parameters needed for the local Docker environment): 
              public static $db = [
          "host" => "localhost",
          "port" => 5432,
          "user" => "YOUR COMPUTING ID",
          "pass" => "PASSWORD FROM CANVAS",
          "database" => "YOUR COMPUTING ID"
      ];
  6. You must follow best practices for securely handling password authentication, as described in class.
  7. Create any other classes that you need to help with your application.
  8. Additional reminders from Homework 5:
    1. User and game information and history for the current session should be stored in thee $_SESSION array. You may choose to determine the best way to store this data, but remember that it uses key-value pairs. Hint: Consider using JSON to store PHP arrays.
    2. For portability between our local Docker enviroment and the cs4640 server, you should use query string variables ($_GET variables) to pass commands to the controller rather than using Apache’s mod_rewrite and a .htaccess config file. That is, you should not need a .htaccess file.
      For example, you may wish to use the command variable to determine the current view; sending the user to index.php?command=welcome would then display the welcome page. The Controller may then determine logic to take based on the $_GET["command"] value.
      Note: you may use mod_rewrite, if you wish, but it may lead to unexpected results. It is discouraged for this assignment.

Submission

The submission will consist of two parts:

  1. Submit your code (HTML, CSS, PHP, etc) to Gradescope in the “Homework 6” submission. You may choose to upload the files individually, upload a zip folder, or upload from a GitHub repository.
    • You must include a link to your published version in the comments of your index.php page, or you will not receive credit!
    • If you worked with a partner, links to both partners’ published versions must be included!
  2. Publish your web site to the cs4640 server under a folder titled “hw6”. Therefore, we should be able to access your work at https://cs4640.cs.virginia.edu/yourid/hw6. If you work with a partner, each person should publish the work to their web space.

Grading Rubric

This homework is worth 50 points, based on the following rubric:

  • 10 points - Continues to fulfill functionality of Homework 5
  • 10 points - Includes script or SQL for building database with at least two tables: hw6_users and hw6_words
  • 10 points - Authentication logic, including secure password authentication and storage
  • 10 points - Stores game state in the database and displays it on the game page
  • 5 points - Logic to ensure user does not get same word twice
  • 5 points - Publishing your site to the cs4640 server

Academic Integrity

For this assignment, you are welcome to share/publish your website! You’ll be doing that on our cs4640 server as well. We only ask that you not make any GitHub projects or source code public until after the late deadline.

Note: You must cite any sources you use in a comment at the top of your index.php file. For example:

<?php
// Sources used: https://cs4640.cs.virginia.edu, ...

...

Use of Generative AI

For Homework 6, you are not allowed to use generative AI tools to help you solve this problem.