88 lines
2.5 KiB
Markdown
88 lines
2.5 KiB
Markdown
# 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.
|