# Pollux

Pollux is a small Laravel 5.6 bookkeeping application for managing bookings,
projects, people, targets, and reports.

## Local development

The application targets PHP 7.4 and MySQL 5.7. Those old runtimes are run in
Docker so they do not have to be installed on the host. [mise](https://mise.jdx.dev/)
manages the host-side tools: Just and Node 10 (required by the old Laravel Mix 2
asset pipeline).

### Prerequisites

- Docker with Compose v2 (`docker compose`)
- [mise](https://mise.jdx.dev/)

### First run

```sh
mise install
just setup
just up
```

Then open <http://localhost:8000>. A development login is created automatically:

- **Email:** `dev@pollux.local`
- **Password:** `password`

`just setup` builds the PHP image, installs Composer dependencies, creates `.env`
from `.env.docker.example`, generates `APP_KEY`, starts MySQL, runs migrations,
and loads the constant and demo data.

### Everyday commands

| Command | Description |
| --- | --- |
| `just up` | Start the app and database in the foreground |
| `just up -d` | Start the app and database in the background |
| `just down` | Stop the app and database |
| `just logs` | Follow container logs |
| `just artisan <command>` | Run an Artisan command |
| `just composer <command>` | Run a Composer command |
| `just shell` | Open a shell in the app container |
| `just db` | Open a MySQL shell |
| `just migrate` | Run migrations |
| `just seed` | Add the demo/test dataset to an existing database |
| `just seed-real` | Recreate the database and load the full dataset from `database/seeds/data/real` |
| `just fresh` | Drop and recreate the database, then load demo data |
| `just test` | Run PHPUnit |
| `just assets` | Install npm packages and build frontend assets |
| `just watch` | Rebuild frontend assets on change |

Run `just --list` to see the full list.

### Database

MySQL is exposed on host port **3307** so it does not clash with a local MySQL
on 3306. The database is `pollux` with username `pollux` and password `secret`.
The app container connects to the `db` service on port 3306.

Data lives in the Docker volume `pollux_mysql-data`. `just down` keeps the data;
use `docker compose down -v` if you want to remove it as well.

### Frontend assets

Node 10 is pinned in `mise.toml` because Laravel Mix 2 and `node-sass` do not run
on current Node versions. Prebuilt assets are committed, so `just assets` is not
needed just to run the application.

### Tests

```sh
just test
```

`just test` starts a separate MySQL 5.7 service (`db-test`) and runs PHPUnit in
the PHP container. The `pollux_test` database uses temporary storage, has no
published port, and is separate from the development database and its volume.
Tests migrate this database automatically and roll back their fixtures after
each test. No demo or real-data seeders are needed. Run `just setup` first on a
new checkout to build the PHP image and install dependencies.

To run a focused subset:

```sh
just test --filter BookingsTest
```

Coverage includes login/logout and guest access, booking forms and changes,
split entries, validation, deletion cascades, income/expense totals, monthly
balances, year boundaries, project and scope reports, and target payment states.
These are PHP HTTP/database tests; they do not exercise browser JavaScript.

PHPUnit forces isolated database settings, and the test bootstrap refuses to run
against another database configuration. If cached application configuration
prevents testing, run `just artisan config:clear`. `just down` also stops the test
database; its temporary data is discarded when the container stops.

## Legacy compatibility notes

This project uses several old dependencies, so a few small compatibility fixes
are included:

Temporary workarounds and legacy runtime pins are marked `TODO(compat)` in the
source, with the condition for removing or replacing each one. Search for this
marker during upgrades. In particular, remove the test `artisan()` override once
Laravel's inherited helper works, and remove both the package-manifest patch
and its Composer hook once Laravel supports Composer 2 directly.

The test startup timestamp, isolated database settings, and database safety
check are normal test infrastructure, not temporary version workarounds.

- `phpdocumentor/phpdocumentor` 2.* was removed from `require-dev`. It requires
  Symfony 2.x, conflicts with Laravel 5.6, and was never present in
  `composer.lock`.
- `scripts/patch-package-manifest.php` runs after Composer's autoload dump. It
  adds Composer 2 support to Laravel 5.6's package discovery, which otherwise
  fails with `Undefined index: name`.
- `fzaninotto/faker` was updated to 1.9.2 for PHP 7.4 compatibility.
- `bookings.note` is created as `TEXT` because the full dataset in
  `database/seeds/data/real` contains notes longer than the default
  191-character string length.

## License

Pollux is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).