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:

{
  "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:

   {
     "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:

   {
     "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:

{
  "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:

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:

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:

vendor/bin/pint --test

Expected Results:

• 0 violations (code follows PSR-12)
• No formatting changes needed

If violations found:

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:

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:

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:

## 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)