Homework 5 - Anagrams Server Edition

Due: Monday, March 24, 2025 at 11:59pm (Updated!)

Purpose:

  • Gain experience writing in PHP using objects and sessions
  • Gain experience reading files in PHP

Overview

For this homework, you may work alone or with another student in this course. You will implement an Anagrams game, which displays seven letters (shuffled) and requires the user to use those letters to name words. It then provides feedback on if the word guessed is a valid word (that has not been entered before) and keeps track of an overall score. The game will end when the user correctly guesses a valid seven-letter word. Users will be prompted to enter their name and email, they will be able to see the valid words they have guessed, and their sessions will be tracked using $_SESSION. You may use the in-class Trivia Game as a starting point, or you may implement everything from scratch.

Anagrams Requirements

Move over Game Pigeon… we’re writing our own word guessing game! Our web application will begin by displaying a welcome screen that requires users to enter their name and email, which we’ll use to personalize the game interface. Once they enter that information, the game page will be displayed. On the game page, the user will be presented with a game page displaying their score (0), seven letters (in a random order) in a large font, and a text box to enter their guess. Once the user enters a word, one of the following things happens:

  • If the word does not include only the exact letters displayed, then display an error message that the player used disallowed letters. You may choose to impose a score penalty if you’d like to increase the difficulty.
  • If the word only includes letters from the game but is not a valid word, then display an error message that the word is not valid. You may choose to impose a score penalty if you’d like to increase the difficulty.
  • If the word is a valid word, includes only the letters allowed, and is less than seven characters, then display that word along with other words correctly guessed and increase the player’s score. You may choose to display a message of congrats for finding a valid word.
  • If the word is a valid word, includes only the letters allowed, and is seven characters long, then take the user to a Game Over screen displaying the results of their game.

For this assignment, you must implement the following 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. Front controller
    • Create an index.php file, which will receive all of the requests for your application. It should instantiate and run your anagram game’s controller as well as handling any necessary session management.
    • Create a AnagramsGameController class that contains the controller to handle all of the logic for your application.
  2. Your application should have at least the following 3 views/templates available to the user. You may choose to include more.
    1. Welcome page. It must ask the user for at least their name and email.
    2. Game page. This template will display the main game page. It should have the following content:
      • The user’s name, email, and list of all valid words guessed.
      • The current score (starting at 0).
      • Seven characters from a randomly-chosen word (which we’ll call the target word), in shuffled order, displayed prominently in a large font.
      • Instructions asking the user to enter a word by rearranging some or all of the characters displayed to form a word, including that guesing the 7-letter target word will conclude the game.
      • An option (link, button, etc) to re-shuffle the characters of the target word in a different order.
      • A form and text box for the user to enter the guess, with a button to submit.
      • A list of all the valid words guessed by the suer. Please be creative! You are encouraged to determine how best to organize the display
      • An option (link, button, etc) for the user to quit the game, which will take the user to the Game Over page.
    3. Game Over page. This template will display the final score, all the guessed words that were valid, the number of invalid words guessed, and provide the option for the user to play again or exit. If the user chooses to play again, return them to the game page with a new target word. If the user chooses to exit, destroy the current session and display the welcome page again.
  3. You must implement the following logic for the overall game:
    • Read in the seven-letter word list from our words7.txt. For development, save this text file locally in your src directory (so that it won’t be publicly available to view under Apache).
      • Word bank (for development): words7.txt
      • When you publish your code to the CS4640 server, update your code to read our words7.txt file directly from the server. You can do this by reading from the following absolute path: /var/www/html/homework/words7.txt
    • Your application should choose one word (the target word) at random from the bank and use its individual characters as the letters available for the game.
    • When the user makes a guess, it should be checked for validity:
      • It should be compared with the characters in the target word to ensure that the word can be made only from the target word’s characters
      • Read in the valid short words list from our server. For development, save this JSON file locally in your src directory (so that it won’t be publicly available to view under Apache).
        • Short word bank (for development): JSON file
        • When you publish your code to the CS4640 server, update your code to read our word_bank.json file directly from the server. You can do this by reading from the following absolute path: /var/www/html/homework/word_bank.json
      • Compare the users guess with the words in the word bank (ignoring case, i.e., it should be a case-insensitive check) of the correct length. It must be in this list to be valid.
      • If the guess is a valid word, add to the player’s score using the following calculations:
        • one-letter word: 1 point
        • two-letter word: 2 points
        • three-letter word: 4 points
        • four-letter word: 8 points
        • five-letter word: 15 points
        • six-letter word: 30 points
  4. 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.
  5. 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.
  6. Create any other classes that you need to help with your application.
  7. Session tracking
    • The user should not be able to access any other views except the welcome page unless they have provided their name and email.
    • You must keep track of the current session with $_SESSION. When the user ends the game, destroy the current session and display the welcome page again.

Submission

The submission will consist of two parts:

  1. Submit your code (HTML, CSS, PHP, etc) to Gradescope in the “Homework 5” 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!
  2. Publish your web site to the cs4640 server under a folder titled “hw5”. Therefore, we should be able to access your work at https://cs4640.cs.virginia.edu/yourid/hw5. 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 - Front controller and URL rewriting
  • 10 points - Maintain session with $_SESSION
  • 5 points - Welcome template
  • 10 points - Game template and submission logic
  • 10 points - Game Over template and display logic
  • 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 5, you are not allowed to use generative AI tools to help you solve this problem.