PostERG/xamxam
1
0
Fork 0
mirror of https://codeberg.org/PostERG/xamxam.git synced 2026-09-25 01:53:03 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: verify and refactor documentation to match current codebase

Browse Source
This commit is contained in:
Pontoporeia
2026-08-24 11:31:38 +02:00
parent b2cdbd0174
commit e9747edce0
17 changed files with 1006 additions and 1442 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/public/admin/README.md
+68 -124
View File
@@ -1,145 +1,89 @@
# Admin Panel Structure
This directory contains the admin panel for managing XAMXAM thesis database.
This directory and `app/templates/admin/` contain the admin panel for managing
the XAMXAM TFE database.
## Directory Structure
## Entry points (`app/public/admin/`)
```
public/admin/
├── index.php # List all theses (main page)
├── add.php # Add new thesis form
├── edit.php # Edit existing thesis form
├── import.php # CSV import form
├── recapitulatif.php # Recap page after submission
├── actions/ # Backend processing scripts (no HTML output)
│ ├── formulaire.php # Process thesis submission from add.php
│ └── publish.php # Toggle publish/unpublish status
├── inc/ # Shared templates
│ ├── head.php # HTML head, CSS, navigation
│ └── footer.php # HTML footer
└── data/ # Upload directory (not in git)
├── theses/ # PDF files
└── covers/ # Cover images
```
| File | Purpose |
|------|---------|
| `index.php` | List all theses (main page; hosts the inline CSV import + tabs for list/trash) |
| `add.php` | Add new thesis form |
| `edit.php` | Existing thesis form |
| `recapitulatif.php` | Post-submission recap |
| `cleanup.php` | Orphaned-draft / storage cleanup |
| `system.php` | System dashboard (logs, SMTP/PeerTube status) |
| `contenus.php` | Editable content (pages, contacts) |
| `contenus-edit.php` | Edit a content page |
| `acces.php` | Share-link management |
| `file-access.php` | Restricted-file access requests |
| `account.php` | Admin account / password |
| `login.php` | Login (session) |
| `import.php` | Redirects to `/admin/` (CSV import is inline in `index.php`) |
| `status.php`, `markdown-cheatsheet-fragment.php`, `*fragment.php` | HTMX fragments / helpers |
## File Types
### Backend actions (`app/public/admin/actions/`)
### User-Facing Templates (Root Directory)
Files that display HTML to users:
- **index.php** - Lists all theses with filters and bulk actions
- **add.php** - Form to add a new thesis
- **edit.php** - Form to edit an existing thesis
- **import.php** - CSV import interface
- **recapitulatif.php** - Success confirmation page
Process forms and redirect (no HTML output):
### Backend Scripts (actions/)
Files that process forms and redirect (no HTML output):
- **formulaire.php** - Processes thesis submission from add.php
- **publish.php** - Handles publish/unpublish actions
### Shared Templates (inc/)
Reusable HTML components:
- **head.php** - HTML head, CSS links, navigation menu
- **footer.php** - HTML footer
## Workflow
### Adding a Thesis
1. User visits `add.php` (displays form)
2. User submits form to `actions/formulaire.php` (processes data)
3. On success, redirects to `recapitulatif.php?id=123`
4. On error, redirects back to `add.php` with error message
### Publishing/Unpublishing
1. User clicks publish/unpublish button in `index.php`
2. Form submits to `actions/publish.php` (processes action)
3. Redirects back to `index.php` with success/error message
## Security
- All pages require HTTP Basic Auth (configured in nginx) — primary layer
- All pages require PHP session auth (`AdminAuth::requireLogin()`) — defence-in-depth
- CSRF tokens protect all forms
- File uploads validated and sanitized
- Database queries use prepared statements
- Upload directory outside public/ in production
See `nginx/PHP_AUTH_LAYER.md` for details on the dual-auth architecture.
- `formulaire.php` — thesis create submission (`ThesisCreateController::submit()`)
- `edit.php` — thesis edit submission (`ThesisEditController::save()`)
- `export-csv.php`, `export-db.php`, `export-files.php` — see `docs/export.md`
- `filepond/` — FilePond async upload endpoints
- many others: `publish`, `delete`, `corbeille` (trash), `draft`, `visibility`,
`tag`, `language`, `form-help*`, `page`, `apropos`, `smtp-test`,
`peertube-*`, `maintenance`, `settings`, `account`, `access-request`,
`acces-etudiante`, `cleanup-*`
## Templates
The `inc/` folder contains shared templates:
- `head.php` - Included at the top of each page (DOCTYPE, CSS, nav)
- `footer.php` - Included at the bottom of each page (closing tags)
View templates live under `app/templates/admin/` (not in `public/`):
- `app/templates/admin/*.php` — page layouts
- `app/templates/admin/partials/` — shared fragments (toasts, dialogs, toc, …)
The public/partage and form partials live in `app/templates/partials/` and
`app/templates/partage/`.
## Auth
- **PHP session auth** (`src/AdminAuth.php`) via `AdminAuth::requireLogin()` is
the only authentication layer. The old nginx `auth_basic` layer has been
removed — see `docs/security.md` and `nginx/docs/PHP_AUTH_LAYER.md`.
- All forms include a CSRF token from `$_SESSION['csrf_token']`.
- Inputs use PDO prepared statements; uploads validated and stored outside the
webroot (`app/storage/`).
## Bootstrap / routing
Entry pages bootstrap the app and set up the environment:
Usage:
```php
<?php include "inc/head.php" ?>
<!-- Page content here -->
<?php include "inc/footer.php" ?>
```
## URL Structure
- `/admin/` - List theses (index.php)
- `/admin/add.php` - Add new thesis
- `/admin/edit.php?id=123` - Edit thesis #123
- `/admin/import.php` - Import CSV
- `/admin/recapitulatif.php?id=123` - Recap page
Backend actions (not directly accessed):
- `/admin/actions/formulaire.php` - Form processor
- `/admin/actions/publish.php` - Publish toggle
## Development
### Adding a New Page
1. Create the template in `/admin/yourpage.php`:
```php
<?php
require_once __DIR__ . "/../../config/bootstrap.php";
require_once __DIR__ . '/../../lib/AdminAuth.php';
require_once __DIR__ . '/../../bootstrap.php'; // defines APP_ROOT, autoload, config
require_once APP_ROOT . '/src/AdminAuth.php';
AdminAuth::requireLogin();
$pageTitle = "Your Page Title";
?>
<?php include "inc/head.php" ?>
<!-- Your content here -->
<?php include "inc/footer.php" ?>
```
2. Add navigation link in `inc/head.php` if needed
`APP_ROOT` is the `app/` directory. Database access is via
`app/src/Database.php`; form logic lives in `app/src/Controllers/` and
`app/src/Form/`.
### Adding a New Action
## URL structure
1. Create the script in `/admin/actions/youraction.php`:
```php
<?php
require_once __DIR__ . "/../../config/bootstrap.php";
require_once __DIR__ . '/../../lib/AdminAuth.php';
AdminAuth::requireLogin();
- `/admin/` — list theses (index.php)
- `/admin/add.php` — add thesis
- `/admin/edit.php?id=N` — edit thesis
- `/admin/cleanup.php`, `/admin/system.php`, `/admin/acces.php`, etc.
- `/admin/actions/…` — backend processors
// Verify CSRF token
if (!hash_equals($_SESSION['csrf_token'], $_POST['csrf_token'])) {
$_SESSION['error'] = "Security error";
header('Location: ../index.php');
exit;
}
## Development guide
// Process action...
**Add a page:** create `app/templates/admin/yourpage.php`, add a thin
`app/public/admin/yourpage.php` entry that bootstraps + requires the template,
and add navigation in `app/templates/admin/partials/admin-toc.php`.
// Redirect
header('Location: ../yourpage.php');
exit;
```
**Add an action:** create `app/public/admin/actions/youraction.php` that
bootstraps, requires login, verifies the CSRF token, performs the work, and
redirects back to the referring admin page.
2. Create form in template that posts to `actions/youraction.php`
## Notes
- Bootstrap path from actions/: `__DIR__ . "/../../config/bootstrap.php"`
- Redirects from actions/: use `../` prefix (e.g., `../index.php`)
- Database class: `require_once __DIR__ . '/../../lib/Database.php'`
- All forms must include CSRF token from `$_SESSION['csrf_token']`
See `docs/development.md` for the general workflow (dev server, builds,
tests, linting).