# Students Projects

Analytics now opens Students Projects, preserving the university's green/gold design, Bootstrap dialogs and sharp corners. Students also have a Students Projects navigation link. Existing assignment submission features and their records remain separate and unchanged.

## Update an existing installation

1. Back up the application and database, deploy this complete slps folder, and preserve your live database configuration and uploads.
2. In phpMyAdmin, select the SLPS database and import `database/migrations/20261015_student_projects.sql`. This adds one table; it does not delete existing records. New installations have this table included in `database/slps_schema.sql`.
3. Enable PHP `zip` for ZIP extraction and edited-project downloads. Enable PECL `rar` for RAR extraction. RAR uploads and original downloads work without it, but browsing/editing their contents requires that extension. The interface reports actual extension availability. If your host cannot enable RAR, students should submit ZIP files instead. No shell extraction commands are used.
4. Set PHP `upload_max_filesize=25M`, `post_max_size=30M` or larger, and suitable request timeouts. On XAMPP use php.ini and restart Apache; on cPanel use the host's supported PHP configuration tools. The application still enforces 25 MB compressed uploads. Set a practical PHP memory limit (for example 256M) for archive processing.
5. Students Projects uses `slps/storage/private/student-projects/` by default. Preserve its `.htaccess` and verify that direct HTTP access returns 403 before uploading. Existing `SLPS_PRIVATE_STORAGE` settings take precedence; see the in-project storage instructions below to change locations safely.
6. Refresh with Ctrl+F5 and open Students Projects. Submit a small ZIP, extract it, open a source file, edit/save, and download the edited ZIP. Verify using your own real student and HOD accounts.

## Student flow

Submit project opens a Bootstrap modal: title, course, description, selected languages/frameworks, optional custom technologies, and ZIP/RAR archive. Courses come from the student's active department courses. Each submission appears in My submitted projects. Choose it, then Extract project. Use the gold folder navigation, file search, Up one level and the file list. Opening a UTF-8 text file loads the local Ace editor with syntax highlighting based on its filename. Common language, web and configuration formats are supported; unknown formats use plain text. Framework selection is metadata, not automatic dependency installation or code execution. Other technologies can be entered with the Other selection.

Save changes (Ctrl/Cmd+S) updates the shared working copy on the server. Students, authorized HODs and administrators see these saved edits. Unsaved navigation changes trigger a Bootstrap confirmation modal. Concurrent changes to the same file return a conflict instead of overwriting another user's work; copy your edits locally before reopening the latest file.

Original archive always downloads the unchanged upload. Download edited ZIP packages the latest working copy with its original folder structure. This is the ZIP the HOD/admin can receive and download; the original RAR remains available separately. The editor is for inspecting source, not running or hosting uploaded websites. Binary/non-UTF-8 files and files above 1 MB can be downloaded, but cannot be edited in the browser.

## Access and limits

- Student: own submissions only. HOD: assigned department AND campus. Admin: all submissions. Staff does not receive permission through this feature.
- Authenticated downloads, reads, extraction and saves; CSRF protection for mutations.
- 25 MB compressed archive, 100 MB total extracted content, 10 MB per extracted file, 3,000 archive entries, 25 folder levels; UTF-8 names, no traversal, drive paths, links, special files, encrypted archives or duplicate names.
- Up to 200 most recent accessible submissions are listed, with browser filtering. Ten submissions per account per hour. Student Projects works without Piston or internet when PHP/database and archive extensions are available locally.
- Original submissions and content-addressed working-copy data live in private storage; back up this storage together with the database. Saves retain old content blobs internally, but there is no user-facing version restore or grading workflow in this release.
- Remove node_modules, dependency/build folders, production secrets and private keys before submitting. Excluded dependencies can be reinstalled locally by the recipient.

## Validation

Tested using real PHP 8.3, ZIP, MariaDB and Chromium: authenticated upload, CSRF, course validation, student and HOD access isolation, nested folders, extraction idempotency, text/binary handling, file saves across roles, stale-write conflict, unchanged original download, edited ZIP content, traversal/duplicate rejection, and the missing-RAR-extension response. Browser checks covered source highlighting, save, file navigation, confirmation/submission modals and desktop/mobile overflow. Real RAR decompression was not tested because the test runtime does not include PECL rar; validate that feature on your configured host before requiring RAR submissions.

## In-project private storage (updated default)

Students Projects now defaults to `slps/storage/private/student-projects/` when neither `SLPS_PROJECT_STORAGE` nor `SLPS_PRIVATE_STORAGE` is set. This supersedes step 5 above for this module. Uploaded files remain accessible only through the authenticated project API. The bundled `storage/private/.htaccess` denies all direct HTTP access on Apache 2.4, including XAMPP. Preserve this file when uploading the project (enable hidden files in cPanel).

If you previously set `SLPS_PRIVATE_STORAGE`, that setting continues to be used to avoid losing access to earlier uploads. To use the internal directory for Students Projects while retaining the shared storage setting for other modules, set `SLPS_PROJECT_STORAGE` to the full path of `slps/storage/private`. If existing student-projects files are stored externally, copy that entire directory into the new location before switching; preserve random folder names, originals, blobs and manifests. Back up first.

Before uploading student work, request `http://localhost/slps/storage/private/index.html` on XAMPP, or the equivalent URL on your hosting. It must return HTTP 403. If it returns the file or HTTP 200, configure Apache to honor Require directives in .htaccess or apply the Directory rule in `config/private-storage-apache.example.conf`, then restart Apache and retest. The application checks that the protection file exists; it cannot prove that your web server honors it.

Nginx ignores .htaccess. If you use Nginx, an administrator must add an appropriate deny rule for the full `/slps/storage/private/` URL prefix (adjust for your deployment), including any static file routing, before enabling uploads. A PHP built-in development server does not honor .htaccess either and needs a router that denies this URL. Do not treat the directory name alone as access protection.
