guestbook/README.md

# guestbook.php

This is a guestbook system for personal websites! Its gimick is that it's simple enough to fit in one file (the SQLite database is technically another file, but `guestbook.php` will generate and handle it all on its own).

## Setup

Assuming you have PHP installed on your server, setting up this guestbook should be as easy as dropping `guestbook.php` into a folder. It will create the database and necessary tables on the first load. If it doesn't work immediately it's probably a bug and I'd encourage you to reach out to me about it.

[Have the latest version of PHP installed][1], and make sure you have SQLite3 set up as well. On Debian, if you don't have `php-8.2-sqlite3` installed, you can install it by running:

```
$ sudo apt install php8.2-sqlite3
```

I've tested this using PHP 8.2. It seems like the Debian package `php8.3-sqlite3` is still experimental as of writing (2024-03-10) so some additional setup may be required to get it working with PHP 8.3 if you're on Debian.

If you just want to test it out without installing something like Nginx, you can use some built in PHP utilities to run a simple server. Run this in the directory where you downloaded `guestbook.php`

```
php -S localhost:8080
```

Then, navigate to `http://localhost:8080/guestbook.php` in your browser.


## Configuring

Several constants are defined at the very top of `guestbook.php` using the PHP `define` function, which works as follows:

```php
define('[name of constant]', [PHP expression]);
```

You can change these constants according to your need. You can also search the file for references to them to see where they're used:
* `GUESTBOOK_NAME` - The name of your guestbook! Used as the page title
* `GUESTBOOK_PAGE_SIZE` - The maximum number of guestbook entries to display on a single page. Additional entries will be moved to the next page, reachable by clicking the navigation buttons at the bottom of the document
* `GUESTBOOK_RATE_LIMIT_SECONDS` - The number of seconds between allowable submissions to the guestbook (i.e. for a rate limit of N seconds, users can only publish an entry every N seconds). Used as a spam prevention mechanism.
* `GUESTBOOK_SQLITE_LOCATION` - The location of the database. If the database isn't found at the location, a new one will be created. Make sure your server has the ability to write to this location!
* `CHALLENGE_QUESTION` - An additional question added to the form as a spam prevention mechanism. The default is "What month is it?" which will trip up LLM-enabled spam bots 11 out of 12 times. If a user doesn't answer correctly, their submission will be quietly ignored
* `CHALLENGE_ANSWER_REGEX` - A regex matching all correct answers to the challenge question
* `SHADOWBAN_REGEX` - If any of the fields (except the challenge question) match this regex, they will be quietly ignored. You may want to use this to block certain keywords you don't want showing up in your guestbook.

Beneath the PHP script at the top of the file, there's the complete HTML page for the guestbook, including the style sheet in the head tag, that you can adjust to your needs.

[1]: https://www.php.net/manual/en/install.php

## Screenshots
![A screenshot of the guestbook. The header reads "Sign the guestbook". Beneath it, a smaller notice indicates that the user has successfully submitted an entry. A boxed form allows the user to input their name, website and message, along with an answer to a challenge question. Below the box, guestbook entries are listed. At the very bottom, a privacy statement describes how the user's IP address is stored as a hash to prevent spam](meta/screenshot.jpg)

## "License"

This software is a gift from me to you. By accepting this gift, we're forming a relationship, and with that comes certain expectations. Namely:

* When you share this gift with others, you will share it in the same spirit as I share it with you.
* You will not use this gift to hurt people, any living creatures, or the planet