Lab Software Management

A Laravel 12 application for managing academic software requests, licences, and sign-off processes across course offerings and academic sessions. Built with Livewire & Flux for a reactive UI, integrated with LDAP for authentication, and supporting bulk import/export via Excel.

Table of Contents

• Features
• Requirements
• Git Clone
• Installation & Setup
• Running the App
• Running Tests
• Environment Variables
• Architecture & Code Organization
• Key Components
• Deployment
• Contributing
• License

---

Features

• LDAP-backed authentication (via ohffs/simple-laravel-ldap)
• Role-based access: staff vs. admin
• Per-course software catalogue with licences, versions, config, notes
• Bulk import of software requests from .xlsx files (ImportController → ImportData job)
• Export full dataset to Excel (ExportAllData)
• Course sign-off workflow with email notifications (User::getSignoffLink & signed-off route)
• Multi-session support: copy data forward to new academic sessions (CopyForward job & AcademicSession::copyForwardTo)
• Admin settings: manage sessions & schools (Livewire Settings component)
• Reactive UI with Livewire + Flux (app/Livewire/*.php)
• Queue processing via Horizon
• Error tracking with Sentry

---

Requirements

• PHP 8.2+
• Composer
• Node.js & npm
• MySQL (or configured DB_CONNECTION)
• Redis (for cache, sessions, queues)
• Lando (development)

---

Git Clone

git clone git@github.com:UoGSoE/lab-software.git
cd lab-software

---

Installation & Setup

1. Copy environment file

   cp .env.example .env

2. Start Lando & services

   lando start
   lando composer install
   npm install

3. Generate database tables & test data

   lando artisan mfs

4. (Optional) Publish assets & run Vite

   lando artisan vendor:publish --tag=laravel-assets --force
   npm run dev

---

Running the App

After lando start, your local URL will be displayed (e.g. https://lab-software.lndo.site). Use that to:

• Log in via /login (LDAP credentials)
• View home dashboard (HomePage Livewire component)
• Import software requests at /importexport
• Browse users at /users
• Admin settings at /settings

---

Running Tests

lando test

Tests are written with Pest (pestphp/pest-plugin-laravel, Livewire & Faker plugins).

---

Environment Variables

Key entries in .env:

• APP_URL, APP_KEY, APP_DEBUG
• DB_, REDIS_, QUEUE_CONNECTION=redis
• LDAP_SERVER, LDAP_OU, LDAP_AUTHENTICATION
• MAIL_HOST & port for email (default: MailHog)

See .env.example for full list.

---

Architecture & Code Organization

• app/Http/Controllers
  • ImportController.php – handles upload & dispatch of ImportData job
• app/Jobs
  • ImportData.php – validates rows, creates Courses, Software, Users & emails results
  • CopyForward.php – enqueues AcademicSession::copyForwardTo
• app/Livewire
  • HomePage.php, CollegeWide.php, ImportExport.php, UserList.php, Settings.php, Help.php
  • Each maps to a Blade view under resources/views/livewire
• app/Models
  • AcademicSession, Course, Software, User (all scoped by session)
  • Domain logic: session copying, sign-off, scoped queries
• app/Exporters
  • ExportAllData.php – generates .xlsx via OpenSpout
• resources/views
  • Livewire templates & components
  • Email views under views/emails
• routes/web.php
  • Public login/logout & signed-off link
  • Authenticated routes under SetAcademicSessionMiddleware

---

Key Components

1. LDAP Login
   • App\Livewire\Auth\LdapLogin
   • Middleware: guest → auth
2. Bulk Import
   • Form on /importexport → POST to ImportController@store
   • Job ImportData reads via Ohffs\SimpleSpout\ExcelSheet
3. Course Catalogue
   • Course & Software models, relation course->software
   • Home filters: name, school prefix, course code (Livewire filtering)
4. Sign-Off Workflow
   • User::getSignoffLink() generates signed route → /signed-off/{user}
   • signed-off route calls User::signOffLastYearsSoftware()
5. Session Management
   • Admin creates new session in Settings → enqueues CopyForward → duplicates data
6. Export
   • ExportAllData::export() streams all courses & software to Excel

---

Deployment

• Adjust .env for production (database, queue driver, Sentry DSN, mail)
• Configure queue workers & Horizon
• Build assets via npm run build
• Set web‐server root to public/
• Run migrations & seeders

---

Contributing

1. Fork & branch
2. Follow PSR-12 & Laravel conventions
3. Write tests (Pest) for new features
4. Submit PR against develop branch

---

License

MIT © University of Glasgow School of Engineering