# Babel

Babel is a language learning web application focused on less commonly served languages, such as Hebrew, Arabic, and Japanese. It provides account management, lesson subscriptions, and vocabulary training with progress tracking.

The repository is split into two main parts:

- `api/`: PHP backend and API endpoints.
- `html/`: Vue 3 frontend built with webpack.

## Requirements

General tools:

- `bash`
- `make`
- `git`
- `composer`
- `node` and `npm`
- PHP 8.x (8.3+ recommended for current dev dependency set)

PHP extensions used by the backend/runtime:

- `pdo`
- `pdo_sqlite` (default DB provider in current code)
- `curl` (used for Gravatar profile lookups)

Platform requirements from the current Composer lock also include:

- `ctype`, `dom`, `filter`, `hash`, `json`, `libxml`, `mbstring`, `phar`, `tokenizer`, `xml`, `xmlwriter`

## Optional Requirements

Optional PHP extensions (identified from first-party `function_exists(...)` checks):

- `apcu`
  - Used in `api/lib/password_hash.class.php` for caching hash benchmark timings and adaptive bcrypt cost.
  - If unavailable, password hashing still works, but without APCu-based caching/adaptation persistence.
- `sysvsem`
  - Used in `api/lib/mutex_lock.class.php` via `sem_get`, `sem_acquire`, and `sem_release`.
  - If unavailable, the app automatically falls back to file locking (`flock`).

Other optional runtime items:

- `pdo_mysql` if you wire the MySQL provider (`api/lib/mysql_provider.class.php`) instead of SQLite.
- `setfacl` (package `acl`) for `make fix-permissions`.

## Build

Run from the project root:

```bash
make build
```

This runs:

1. `composer install` in `api/`
2. `npm install` in `html/`
3. `npm run build` in `html/`

Build backend and frontend independently:

```bash
make build-api
make build-html
```

## Install (Build Artifacts)

Run from the project root:

```bash
make install
```

`install` depends on `build`, so it always builds first.

The install step creates `build/` with deployment artifacts:

- `build/api/`: selected backend files plus runtime vendor packages.
- `build/html/`: copied from `html/dist/`.
- `build/.htaccess`: copied from root `.htaccess` with install-time rewriting rules.

## Reset Installation (Testing)

To reset the current installation state for testing:

```bash
make clear-install
```

Direct command:

```bash
cd api
composer clear-install
```

`clear-install` does the following using the current database configuration from `api/config/config.php`:

- Drops all tables/views in the configured database.
- Moves `api/config/config.php` to `api/config/config.bak.php` and overwrites any existing backup file.

This is useful when table layout changes are made without incrementing the database version and you need a clean installation state.

## Fix Permissions

To apply shared group ACL/permissions (group `www-data`):

```bash
make fix-permissions
```

This wraps `tools/set-permissions.php` and requires `setfacl`.

## Run Tests

Run all tests from the project root:

```bash
make test
```

This runs backend and frontend tests:

1. `composer test` in `api/`
2. `npm run test` in `html/`

Run tests independently:

```bash
make test-api
make test-html
```

Direct commands (without Make):

```bash
cd api
composer test

cd ../html
npm run test
```

Note: the current frontend `test` script in `html/package.json` is still a placeholder and exits with an error until a real frontend test runner is configured.

## Development Run

You can run the project in place even if you edit files as a different user than the web server user (`www-data` by default).

Recommended workflow:

1. Run permissions setup once:

```bash
make fix-permissions
```

2. After changes, rebuild:

```bash
make build
```

3. Run tests:

```bash
make test
```

If you only changed one side, use the split targets:

- Backend only: `make build-api` and `make test-api`
- Frontend only: `make build-html` and `make test-html`