# xxx.org.za

A Content Management System for x.x.x, a collection of 100-word stories.

This code was mostly written between 2004 and 2008, although the git history
doesn't stretch that far. If you're wondering why some core ports don't use
fancy new PHP features... that's probably why.

The site reads its configuration from `.env`. Copy `.env.example` to
`.env`, and set the values in it.

## reCAPTCHA

To enable reCAPTCHA, set up the Google Cloud credentials:

1. Enable the reCAPTCHA Enterprise API in the project that owns your
   checkbox key.
2. Set `RECAPTCHA_SITE_KEY` to that checkbox key in `.env`.
3. Set `RECAPTCHA_PROJECT_ID` to the Google Cloud project ID.
4. Create a Google Cloud API key for server requests.
5. Restrict the API key to the reCAPTCHA Enterprise API.
6. If the server has a fixed outbound IP address, restrict the API key
   to that address too.
7. Set `RECAPTCHA_API_KEY` to the API key in `.env`.
8. Set `SITE_URL` to the site's HTTPS address.

## Tests

The repository has three sets of tests:

- The PHP unit tests (`tests/php/Unit`) run the functions of the site
  against a fake database. They do not need MySQL or the network.
- The PHP page tests (`tests/php/Pages`) run the pages on the PHP
  built-in web server, and send HTTP requests to them.
- The JavaScript tests (`tests/js`) run the story editor and the other
  scripts in jsdom, a browser document for Node.js.

No test uses the real database, the real `.env` file, Google, or a mail
server. The tests use `tests/php/fixtures/test.env` for the
configuration, and they write only to the system temporary directory.

### Requirements

- PHP 8.4.1 or later on the command line, with the dom, filter, json,
  libxml, mbstring, simplexml and xmlwriter extensions. The mysqli
  extension is not necessary.
- Composer.
- Node.js 20.19, 22.13, or 24 or later, with npm.

### Run the PHP tests

Install PHPUnit and the other development packages into `vendor/`:

```sh
composer install
```

Run all the PHP tests:

```sh
composer test
```

### Run the JavaScript tests

Install jsdom into `node_modules/`, then run the tests:

```sh
npm install
npm test
```

To run one file:

```sh
node --test tests/js/editor.test.js
```

### Development files on the live site

Do not install the development packages on the live server. The site itself
does not use them.

If the tests or the packages are on the server, `.htaccess` stops Apache from
serving `tests/`, `vendor/`, `node_modules/` and the Composer, npm and PHPUnit
files. This needs `AllowOverride AuthConfig`, as the other rules in `.htaccess`
do.