CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Stack
6 
7- **PHP 8.2+** / **Laravel 12** (framework), **Laravel Mix** (webpack) for frontend assets
8- **AdminLTE 2** / **Bootstrap 3** UI — Blade views. Mostly server-rendered; a handful of newer admin-settings screens use **Livewire** components (`app/Livewire/`, e.g. `LdapSettings`, `CustomFieldEditor`, `Importer`) — no Inertia.
9- **Chart.js v2.9.4** — bundled at `public/js/dist/Chart.min.js`; use `horizontalBar` type (v2 API, not v3)
10- Snipe-IT is a FOSS IT asset management system (assets, licenses, accessories, consumables, components, kits) — see README.md for product context.
11 
12## Common Commands
13 
14```bash
15# Run all tests
16php artisan test
17# or
18vendor/bin/phpunit
19 
20# Run a single test file
21php artisan test tests/Feature/Assets/AssetsTest.php
22 
23# Run a specific test method
24php artisan test --filter testSomeMethod
25 
26# Run/exclude tests by group (e.g. LDAP tests, which need the LDAP extension)
27php artisan test --group=ldap
28php artisan test --exclude-group=ldap
29 
30# Lint / static analysis
31vendor/bin/pint          # code style (Laravel preset, see pint.json)
32vendor/bin/phpstan analyse   # static analysis via Larastan, level 4 (phpstan.neon.dist)
33 
34# Build frontend assets (dev)
35npm run dev
36 
37# Build for production
38npm run prod
39 
40# Laravel Mix watch
41npm run watch
42 
43# Tinker / REPL
44php artisan tinker
45 
46# Clear caches after config/route changes
47php artisan optimize:clear
48```
49 
50Dev server is served via **Laravel Herd** (`herd coverage vendor/bin/phpunit --coverage-html tests/coverage/html` for coverage reports — see `composer.json` scripts).
51 
52Before running tests locally, copy `.env.testing.example` to `.env.testing`. Default test config uses in-memory SQLite (`DB_CONNECTION=sqlite_testing`); MySQL is also supported by setting the `DB_*` vars. See TESTING.md for details.
53 
54## Architecture
55 
56### Controllers
57 
58Two parallel controller trees:
59- `app/Http/Controllers/` — web/UI controllers (Blade views)
60- `app/Http/Controllers/Api/` — REST API controllers (JSON, used by datatables + select2)
61 
62Subdirectory groupings: `Assets/`, `Licenses/`, `Users/`, `Accessories/`, `Consumables/`, `Components/`, `Kits/`, `Account/`, `Auth/`
63 
64### API Pattern
65 
66Every API controller returns data via a **Transformer** (`app/Http/Transformers/`). Never return raw model attributes from API controllers — always pass through the transformer. `DatatablesTransformer` wraps paginated results.
67 
68```php
69return (new AssetsTransformer)->transformAssets($assets, $assets->count());
70```
71 
72### Authorization
73 
74All authorization goes through **Policies** (`app/Policies/`). `CheckoutablePermissionsPolicy` is the base for assets/licenses/accessories/consumables — its `checkout()` / `checkin()` methods accept `$item = null` so you can use `@can('checkout', \App\Models\Asset::class)` without an instance.
75 
76### FMCS (Full Multiple Company Support)
77 
78`Setting::getSettings()->full_multiple_companies_support == '1'` gates company-scoped filtering. The select2 API endpoints (`selectlist()` methods) accept a `companyId` query param — apply it like this:
79 
80```php
81if ((Setting::getSettings()->full_multiple_companies_support == '1') && ($request->filled('companyId'))) {
82    $query->where('table.company_id', $request->input('companyId'));
83}
84```
85 
86Pass `data-company-id="{{ $user->company_id }}"` in Blade to wire it to select2.
87 
88### Select2 AJAX Dropdowns
89 
90Use `class="js-data-ajax"` with `data-endpoint="hardware|licenses|consumables|..."`. `snipeit.js` auto-initializes these, forwarding `data-company-id` as `companyId` and `data-asset-status-type` as `statusType` to the API.
91 
92### Routes
93 
94All routes are in `routes/web.php` (UI) and `routes/api.php` (API). Breadcrumbs are defined inline using `->breadcrumbs(fn (Trail $trail) => ...)` from `tabuna/breadcrumbs`. Every UI route should have a breadcrumb.
95 
96Note: the `reports/unaccepted_assets` route is named with slashes, not dots — use `route('reports/unaccepted_assets')`.
97 
98### Translations
99 
100String keys live in `resources/lang/en-US/general.php` (and other files in that directory). Always add new UI strings as translation keys rather than hard-coding English.
101 
102### Checkout Redirect Flow
103 
104After checkout, `Helper::getRedirectOption()` reads `$request->redirect_option`. For redirecting back to the assigned user after checkout:
105- Set `redirect_option=target` in the form
106- Set `checkout_to_type=user` in the form
107- Set `assigned_user={{ $user->id }}` in the form
108 
109### Key Helper Methods (`app/Helpers/Helper.php`)
110 
111- `Helper::deployableStatusLabelList()` — status labels for checkout forms
112- `Helper::defaultChartColors()` — 10-color palette used in charts
113- `Helper::getRedirectOption($request, $id, $table)` — post-checkout redirect logic
114 
115### Global View Variables
116 
117`$snipeSettings` is injected into all views via a service provider — no need to pass `Setting::getSettings()` from every controller. Use it directly in Blade.
118 
119### CSV Importing
120 
121`app/Importer/` holds per-entity importers (`AssetImporter`, `LicenseImporter`, `AccessoryImporter`, `ComponentImporter`, `ConsumableImporter`, `AssetModelImporter`, `CategoryImporter`, `UserImporter`, etc.), all extending `Importer.php`. The `Importer` Livewire component (`app/Livewire/Importer.php`) drives the UI for CSV import.
122 
123### Presenters
124 
125`app/Presenters/` (e.g. `AssetPresenter`, `AssetModelPresenter`, `AccessoryPresenter`) define the column/field configuration consumed by the Bootstrap Table datatables on index views — check these when adding or changing a column shown in a listing.
126 
127## Testing
128 
129Tests live in `tests/Feature/` (organized by entity) and `tests/Unit/`. Feature tests hit the database; the test environment uses `array` cache/session/mail drivers. Tests use factories for data setup. Use PHPUnit `#[Group('name')]` attributes to tag tests that need optional extensions/services (e.g. `LdapTest` is tagged `ldap`) so they can be excluded via `--exclude-group`.
130 
131## Contribution Policy
132 
133Per README.md / the project's AI Contribution Policy: PRs and issues generated by fully-automated tools without human review are not accepted upstream. If producing a PR for the upstream project (not an internal fork), treat Claude's output as a draft for human review, not a submission-ready artifact.
134