php-api/TODO-PHASE1.md

# Phase 1: Dependency Resolution + Test Baseline

**Created:** 20 February 2026
**Agent:** Clotho
**Related:** Issue #1, FINDINGS.md

---

## Critical Blocker: Missing Dependency

### Issue

`composer install` fails because `host-uk/core` package cannot be found:

```json
{
  "require": {
    "host-uk/core": "@dev"  // ← NOT FOUND
  }
}
```

### Impact

- ❌ Cannot install vendor dependencies
- ❌ Cannot run tests (`vendor/bin/pest`)
- ❌ Cannot run linter (`vendor/bin/pint`)
- ❌ Cannot run static analysis (`vendor/bin/phpstan`)
- ❌ No development environment

---

## Phase 1 Tasks

### Task 1: Resolve `host-uk/core` Dependency

**Priority:** CRITICAL
**Estimated Time:** 1-2 hours (depending on approach)

**Choose ONE approach:**

#### Option A: Path Repository (Monorepo)

If `host-uk/core` exists locally (e.g., `../core/`):

1. Update `composer.json`:
   ```json
   {
     "repositories": [
       {
         "type": "path",
         "url": "../core"
       }
     ],
     "require": {
       "host-uk/core": "@dev"
     }
   }
   ```

2. Run `composer install --no-interaction`

#### Option B: Private Composer Registry

If using Satis or Private Packagist:

1. Update `composer.json`:
   ```json
   {
     "repositories": [
       {
         "type": "composer",
         "url": "https://composer.example.com/"
       }
     ]
   }
   ```

2. Configure credentials if needed
3. Run `composer install --no-interaction`

#### Option C: Symlink Development (Temporary)

1. Clone `host-uk/core` to `../core`
2. Use Option A (path repository)

**Acceptance Criteria:**
- ✅ `composer install` completes successfully
- ✅ `vendor/` directory created
- ✅ `composer.lock` generated
- ✅ No dependency errors

---

### Task 2: Add Missing Dev Dependencies

**Priority:** HIGH
**Estimated Time:** 15 minutes

Current `composer.json` is missing `require-dev` section.

**Action:**

Add to `composer.json`:
```json
{
  "require-dev": {
    "pestphp/pest": "^2.0",
    "pestphp/pest-plugin-laravel": "^2.0",
    "laravel/pint": "^1.0",
    "phpstan/phpstan": "^1.10",
    "orchestra/testbench": "^9.0",
    "mockery/mockery": "^1.6",
    "nunomaduro/collision": "^8.0"
  }
}
```

Then run:
```bash
composer update --no-interaction
```

**Acceptance Criteria:**
- ✅ All dev tools installed
- ✅ `vendor/bin/pest` available
- ✅ `vendor/bin/pint` available
- ✅ `vendor/bin/phpstan` available

---

### Task 3: Establish Test Baseline

**Priority:** HIGH
**Estimated Time:** 30 minutes

Once dependencies are resolved, run full test suite:

```bash
vendor/bin/pest --testdox
```

**Expected Results (from FINDINGS.md):**
- 11 feature test files
- ~50-70 test cases
- All tests passing (as of January 2026)

**Document:**
- Total tests run
- Pass/fail count
- Execution time
- Any failures (unexpected)

**Output to:** `BASELINE-TESTS.md`

---

### Task 4: Establish Lint Baseline

**Priority:** MEDIUM
**Estimated Time:** 15 minutes

Run code style checker:

```bash
vendor/bin/pint --test
```

**Expected Results:**
- 0 violations (code follows PSR-12)
- No formatting changes needed

**If violations found:**
```bash
vendor/bin/pint --dirty  # Fix changed files only
```

**Document:**
- Violations found (if any)
- Files affected
- Auto-fix results

**Output to:** `BASELINE-LINT.md`

---

### Task 5: Establish Static Analysis Baseline

**Priority:** MEDIUM
**Estimated Time:** 30 minutes

Run PHPStan analysis:

```bash
vendor/bin/phpstan analyse --memory-limit=512M
```

**Expected Issues (from TODO.md):**
- Array shape types in resources
- Missing return types
- Property type declarations

**Document:**
- Current PHPStan level
- Total errors found
- Error categories
- Plan to reach Level 5

**Output to:** `BASELINE-PHPSTAN.md`

---

### Task 6: Commit Baseline Files

**Priority:** HIGH
**Estimated Time:** 15 minutes

Commit all baseline documentation:

```bash
git add composer.json composer.lock
git add BASELINE-*.md
git commit -m "chore: establish test, lint, and static analysis baselines (#1)

- Add require-dev dependencies (Pest, Pint, PHPStan)
- Run full test suite: XX tests passing
- Run code linter: 0 violations
- Run static analysis: XX errors at level X
- Document baseline results for future comparison

Co-Authored-By: Clotho <clotho@lthn.ai>"
```

**Acceptance Criteria:**
- ✅ `composer.lock` committed
- ✅ Baseline documents committed
- ✅ Conventional commit message
- ✅ References issue #1

---

### Task 7: Update Documentation

**Priority:** LOW
**Estimated Time:** 15 minutes

Update README.md with setup instructions:

Add section:
```markdown
## Development Setup

### Prerequisites
- PHP 8.2+
- Composer 2.0+
- Access to `host-uk/core` package (see below)

### Installation

1. Clone repository:
   bash
   git clone <repo-url>
   cd php-api


2. Install dependencies:
   bash
   composer install


3. Run tests:
   bash
   vendor/bin/pest


4. Run linter:
   bash
   vendor/bin/pint --test


5. Run static analysis:
   bash
   vendor/bin/phpstan analyse

```

---

## Phase 1 Completion Criteria

- ✅ `composer install` works without errors
- ✅ All test suites pass
- ✅ Lint baseline documented
- ✅ Static analysis baseline documented
- ✅ `composer.lock` committed
- ✅ Baseline files committed
- ✅ README updated with setup instructions

---

## After Phase 1

Proceed to Phase 2 based on TODO.md priorities:

**High Priority (Phase 2):**
- [ ] Fix PHPStan Level 5 errors
- [ ] Add missing test coverage (usage alerts)
- [ ] API versioning support

**Medium Priority (Phase 3):**
- [ ] Response caching optimisation
- [ ] N+1 query elimination
- [ ] Webhook analytics dashboard

See `TODO.md` for full roadmap.

---

**Next Actions:**
1. Team chooses dependency resolution strategy (Option A/B/C)
2. Update `composer.json` accordingly
3. Run through Tasks 1-7
4. Mark Phase 1 complete
5. Begin Phase 2

**Estimated Total Time:** 3-4 hours (excluding dependency setup decision time)