laravel-api-skill

Here’s a production-ready Laravel REST API skeleton for **TaskFlow**, a project management tool, designed for high scalability and maintainability. The API includes endpoints for managing tasks, projects, and users with full type safety and clean architecture.

### **Project Structure**
```
app/
├── Http/
│   ├── Controllers/
│   │   ├── Api/
│   │   │   ├── v1/
│   │   │   │   ├── TaskController.php
│   │   │   │   ├── ProjectController.php
│   │   │   │   └── UserController.php
│   ├── Requests/
│   │   ├── TaskRequest.php
│   │   ├── ProjectRequest.php
│   │   └── UserRequest.php
├── Models/
│   ├── Task.php
│   ├── Project.php
│   └── User.php
├── DTOs/
│   ├── TaskDTO.php
│   ├── ProjectDTO.php
│   └── UserDTO.php
├── Repositories/
│   ├── TaskRepository.php
│   ├── ProjectRepository.php
│   └── UserRepository.php
├── Services/
│   ├── TaskService.php
│   ├── ProjectService.php
│   └── UserService.php
└── Providers/
    └── AppServiceProvider.php
```

### **Key Features**
1. **Type Safety**: All DTOs, requests, and responses are strictly typed using PHP 8.2+ features.
2. **Clean Architecture**: Separation of concerns with controllers, services, repositories, and DTOs.
3. **Validation**: Custom request classes for endpoint validation.
4. **Error Handling**: Global exception handling with Laravel’s `Renderable` and `Reportable` interfaces.
5. **Testing**: PestPHP unit tests for services and repositories.
6. **Documentation**: OpenAPI (Swagger) annotations for API documentation.

### **Example Endpoints**
- `GET /api/v1/tasks` – List all tasks with pagination.
- `POST /api/v1/tasks` – Create a new task with validation.
- `PUT /api/v1/tasks/{id}` – Update a task.
- `DELETE /api/v1/tasks/{id}` – Delete a task.

### **Code Snippets**
**TaskController.php**
```php
<?php

namespace App\Http\Controllers\Api\v1;

use App\DTOs\TaskDTO;
use App\Http\Requests\TaskRequest;
use App\Http\Resources\TaskResource;
use App\Services\TaskService;
use Illuminate\Http\JsonResponse;

class TaskController extends Controller
{
    public function __construct(private TaskService $taskService) {}

    public function index(): JsonResponse
    {
        $tasks = $this->taskService->getAll();
        return TaskResource::collection($tasks)->response();
    }

    public function store(TaskRequest $request): JsonResponse
    {
        $taskDTO = TaskDTO::fromRequest($request);
        $task = $this->taskService->create($taskDTO);
        return (new TaskResource($task))->response()->setStatusCode(201);
    }
}
```

**TaskDTO.php**
```php
<?php

namespace App\DTOs;

use Illuminate\Http\Request;

class TaskDTO
{
    public function __construct(
        public string $title,
        public string $description,
        public int $project_id,
        public ?int $assigned_to = null,
        public ?string $due_date = null,
    ) {}

    public static function fromRequest(Request $request): self
    {
        return new self(
            title: $request->input('title'),
            description: $request->input('description'),
            project_id: $request->input('project_id'),
            assigned_to: $request->input('assigned_to'),
            due_date: $request->input('due_date'),
        );
    }
}
```

### **Testing**
A PestPHP test for the `TaskService` ensures business logic is validated:
```php
it('can create a task', function () {
    $taskDTO = new TaskDTO(
        title: 'Test Task',
        description: 'This is a test task',
        project_id: 1,
    );

    $task = $this->taskService->create($taskDTO);
    expect($task)->toBeInstanceOf(Task::class);
    expect($task->title)->toBe('Test Task');
});
```

### **Next Steps**
1. Run `composer install` to install dependencies.
2. Configure `.env` with database and API settings.
3. Run `php artisan migrate` to set up tables.
4. Use `php artisan serve` to test locally.
5. Generate API docs with `php artisan l5-swagger:generate`.