# FAQ - Frequently Asked Questions

Common questions and solutions for the Web Dolphin Japan project.

> **Backend API-Only Project:** This is a REST API server with no frontend. All questions focus on backend development.

## Installation & Setup

### Q: I'm getting "PHP 8.2 required" error
**A:** Install PHP 8.2 or higher from [php.net](https://www.php.net/downloads)
```bash
php --version  # Check your current version
```

### Q: "Composer: command not found"
**A:** Install Composer from https://getcomposer.org/download/
```bash
composer --version  # Verify installation
```

### Q: Can I use a different PHP version?
**A:** The project requires PHP 8.2+. Earlier versions won't work due to dependency requirements.

### Q: What database does this project use?
**A:** The project uses PostgreSQL by default. Configuration is already in `.env.example`.

To set it up:
```bash
# Ensure PostgreSQL is running, then:
createdb -U postgres dolphinapp
php artisan migrate
```

### Q: Setup command failed, what do I do?
**A:** Run the manual steps individually:
```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
```
Check each step's output to identify the issue.

---

## Development

### Q: How do I start the development server?
**A:** Two options:

**Option 1** (Recommended - everything in one command):
```bash
composer run dev
```

**Option 2** (Individual services in separate terminals):
```bash
php artisan serve           # Terminal 1
npm run dev                # Terminal 2
php artisan queue:listen   # Terminal 3
php artisan queue:listen   # Terminal 2
php artisan pail           # Terminal 3
```
**A:** Use a different port:
```bash
php artisan serve --port=8001
# Then access at http://localhost:8001
```

### Q: How do I debug an issue?
**A:** Use Laravel Tinker for interactive testing:
```bash
php artisan tinker

>>> Brand::all()                    # Get all brands
>>> Brand::find(1)                  # Get brand with id=1
>>> Brand::create(['name' => 'Test'])  # Create brand
>>> exit
```

### Q: How do I view application logs?
**A:** Use Laravel Pail:
```bash
php artisan pail              # Real-time logs
php artisan pail --filter=error  # Show only errors
```

Or view the log file:
```bash
tail -f storage/logs/laravel.log
```

### Q: Where should I put my code?
**A:** Follow the 3-layer architecture:

1. **Controller** - `app/Http/Controllers/Admin/`
2. **Service** - `app/Http/Service/`
3. **Repository** - `app/Http/Repository/`
4. **Model** - `app/Models/`
5. **Request** (Validation) - `app/Http/Requests/`
6. **Resource** (JSON) - `app/Http/Resources/`

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed examples.

---

## Database

### Q: How do I reset the database?
**A:** Warning: This deletes all data!
```bash
php artisan migrate:fresh  # Reset and re-run all migrations
```

### Q: I deleted a migration file by mistake
**A:** 
1. Restore from git: `git checkout database/migrations/`
2. Or if it's not committed, recreate it manually

### Q: Can I use database seeders?
**A:** Yes! Create seeders:
```bash
php artisan make:seeder BrandSeeder
```

Then run:
```bash
php artisan db:seed           # Run all seeders
php artisan migrate:fresh --seed  # Reset + seed
```

### Q: How do I check my database?
**A:** Use Tinker or psql:

```bash
# Using Tinker
php artisan tinker
>>> DB::table('brands')->all()

# Using psql (PostgreSQL command line)
psql -U postgres -d dolphinapp
dolphinapp=# SELECT * FROM brands;
dolphinapp=# \q
```

### Q: "SQLSTATE[08006]" connection error
**A:** PostgreSQL is not running or not configured:
```bash
# Start PostgreSQL
sudo systemctl start postgresql  # Linux
brew services start postgresql   # macOS

# Check .env database settings match PostgreSQL config
php artisan migrate
```

---

## Testing

### Q: How do I write tests?
**A:** Create test file:
```bash
php artisan make:test BrandTest --feature
```

Example test:
```php
public function test_can_get_brands()
{
    $response = $this->getJson('/api/v1/brand/');
    $response->assertStatus(200);
}
```

### Q: How do I run specific tests?
**A:**
```bash
php artisan test                           # All tests
php artisan test tests/Feature/BrandTest  # Specific test
php artisan test --filter=can_get_brands  # Specific method
```

### Q: Tests are failing, what do I do?
**A:** 
1. Check the error message: `php artisan test`
2. Run in debug mode: `php artisan test -v`
3. Check database state: Use Tinker to inspect
4. Reset database: `php artisan migrate:fresh`

---

## Code Quality

### Q: How do I format my code?
**A:** Use Laravel Pint:
```bash
./vendor/bin/pint              # Auto-fix style issues
./vendor/bin/pint --test       # Check without fixing
```

### Q: My code doesn't follow PSR-12
**A:** Run Pint to automatically fix:
```bash
./vendor/bin/pint
git add .
git commit -m "style: Format code to PSR-12"
```

### Q: What naming conventions should I use?
**A:** See [AGENTS.md](AGENTS.md) for complete list:
- Controllers: `BrandController`
- Services: `BrandService`
- Repositories: `BrandRepository`
- Models: `Brand`
- Methods: `getAllBrands()` (camelCase)

---

## Git & GitHub

### Q: How do I create a pull request?
**A:**
1. Create feature branch: `git checkout -b feature/my-feature`
2. Make changes and commit: `git commit -m "feat: Add feature"`
3. Push: `git push origin feature/my-feature`
4. Create PR on GitHub website
5. Request review from team members

### Q: What should my commit message be?
**A:** Use this format:
```
[Type] Short description

Types: feat, fix, refactor, test, docs, style, chore

✅ Good: "feat: Add category management endpoints"
❌ Bad: "update stuff"
```

### Q: I accidentally committed sensitive data
**A:** Remove from history:
```bash
# Add to .gitignore
git rm --cached .env
git commit --amend

# Remove from all history
git filter-branch --tree-filter 'rm -f .env' HEAD
```

### Q: How do I stay updated with main branch?
**A:**
```bash
git fetch origin
git rebase origin/main
```

---

## Deployment

### Q: How do I deploy to production?
**A:** See [DEPLOYMENT.md](DEPLOYMENT.md) for complete guide.

Quick summary:
```bash
git pull origin main
composer install --no-dev
php artisan config:cache
php artisan migrate --force
```

### Q: What's the difference between dev and production?
**A:**
- **Development**: Debug mode on, console logs visible
- **Production**: Debug off, optimized autoloader

Set in `.env`:
```env
APP_ENV=production  # or local
APP_DEBUG=false     # false for production
```

---

## Common Errors & Solutions

| Error | Solution |
|-------|----------|
| `composer install` fails | Clear cache: `composer clear-cache` |
| Port 8000 in use | Use different port: `php artisan serve --port=8001` |
| Permission denied on storage/ | `chmod -R 775 storage bootstrap/cache` |
| Database connection error | Check `.env` DB settings and PostgreSQL is running |
| Tests fail randomly | Run: `php artisan migrate:fresh` then test again |
| "Class not found" error | Run: `composer dump-autoload` |

---

## Need More Help?

- **Setup Issues**: [SETUP.md](SETUP.md)
- **Development Guide**: [CONTRIBUTING.md](CONTRIBUTING.md)
- **Quick Commands**: [QUICK_START.md](QUICK_START.md)
- **Architecture**: [AGENTS.md](AGENTS.md)
- **Laravel Docs**: https://laravel.com/docs/12

---

**Still stuck?** Ask your team members or check Laravel documentation.

Last Updated: May 5, 2026