Skip to content

Commit 113119d

Browse files
authored
feat: add laravel skills (anomalyco#420)
* feat: add laravel skills * docs: fix laravel patterns example * docs: add laravel api example * docs: update readme and configure-ecc for laravel skills * docs: reference laravel skills in php rules * docs: add php import guidance * docs: expand laravel skills with more pattern, security, testing, and verification examples * docs: add laravel routing, security, testing, and sail guidance * docs: fix laravel example issues from code review * docs: fix laravel examples and skills per review findings * docs: resolve remaining laravel review fixes * docs: refine laravel patterns and tdd guidance * docs: clarify laravel queue healthcheck guidance * docs: fix laravel examples and test guidance * docs: correct laravel tdd and api example details * docs: align laravel form request auth semantics * docs: fix laravel coverage, imports, and scope guidance * docs: align laravel tdd and security examples with guidance * docs: tighten laravel form request authorization examples * docs: fix laravel tdd and queue job examples * docs: harden laravel rate limiting and policy examples * docs: fix laravel pagination, validation, and verification examples * docs: align laravel controller response with envelope * docs: strengthen laravel password validation example * docs: address feedback regarding examples * docs: improve guidance and examples for pest usage * docs: clarify laravel upload storage and authorization notes * docs: tighten up examples
1 parent 17a6ef4 commit 113119d

11 files changed

Lines changed: 1504 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -292,6 +292,10 @@ everything-claude-code/
292292
| |-- django-security/ # Django security best practices (NEW)
293293
| |-- django-tdd/ # Django TDD workflow (NEW)
294294
| |-- django-verification/ # Django verification loops (NEW)
295+
| |-- laravel-patterns/ # Laravel architecture patterns (NEW)
296+
| |-- laravel-security/ # Laravel security best practices (NEW)
297+
| |-- laravel-tdd/ # Laravel TDD workflow (NEW)
298+
| |-- laravel-verification/ # Laravel verification loops (NEW)
295299
| |-- python-patterns/ # Python idioms and best practices (NEW)
296300
| |-- python-testing/ # Python testing with pytest (NEW)
297301
| |-- springboot-patterns/ # Java Spring Boot patterns (NEW)
@@ -411,6 +415,7 @@ everything-claude-code/
411415
| |-- saas-nextjs-CLAUDE.md # Real-world SaaS (Next.js + Supabase + Stripe)
412416
| |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)
413417
| |-- django-api-CLAUDE.md # Real-world Django REST API (DRF + Celery)
418+
| |-- laravel-api-CLAUDE.md # Real-world Laravel API (PostgreSQL + Redis) (NEW)
414419
| |-- rust-api-CLAUDE.md # Real-world Rust API (Axum + SQLx + PostgreSQL) (NEW)
415420
|
416421
|-- mcp-configs/ # MCP server configurations
@@ -615,7 +620,7 @@ cp -r everything-claude-code/.agents/skills/* ~/.claude/skills/
615620
cp -r everything-claude-code/skills/search-first ~/.claude/skills/
616621
617622
# Optional: add niche/framework-specific skills only when needed
618-
# for s in django-patterns django-tdd springboot-patterns; do
623+
# for s in django-patterns django-tdd laravel-patterns springboot-patterns; do
619624
# cp -r everything-claude-code/skills/$s ~/.claude/skills/
620625
# done
621626
```
@@ -869,7 +874,7 @@ Please contribute! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
869874
### Ideas for Contributions
870875
871876
- Language-specific skills (Rust, C#, Kotlin, Java) — Go, Python, Perl, Swift, and TypeScript already included
872-
- Framework-specific configs (Rails, Laravel, FastAPI, NestJS) — Django, Spring Boot already included
877+
- Framework-specific configs (Rails, FastAPI, NestJS) — Django, Spring Boot, Laravel already included
873878
- DevOps agents (Kubernetes, Terraform, AWS, Docker)
874879
- Testing strategies (different frameworks, visual regression)
875880
- Domain-specific knowledge (ML, data engineering, mobile)

‎examples/laravel-api-CLAUDE.md‎

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
# Laravel API — Project CLAUDE.md
2+
3+
> Real-world example for a Laravel API with PostgreSQL, Redis, and queues.
4+
> Copy this to your project root and customize for your service.
5+
6+
## Project Overview
7+
8+
**Stack:** PHP 8.2+, Laravel 11.x, PostgreSQL, Redis, Horizon, PHPUnit/Pest, Docker Compose
9+
10+
**Architecture:** Modular Laravel app with controllers -> services -> actions, Eloquent ORM, queues for async work, Form Requests for validation, and API Resources for consistent JSON responses.
11+
12+
## Critical Rules
13+
14+
### PHP Conventions
15+
16+
- `declare(strict_types=1)` in all PHP files
17+
- Use typed properties and return types everywhere
18+
- Prefer `final` classes for services and actions
19+
- No `dd()` or `dump()` in committed code
20+
- Formatting via Laravel Pint (PSR-12)
21+
22+
### API Response Envelope
23+
24+
All API responses use a consistent envelope:
25+
26+
```json
27+
{
28+
"success": true,
29+
"data": {"...": "..."},
30+
"error": null,
31+
"meta": {"page": 1, "per_page": 25, "total": 120}
32+
}
33+
```
34+
35+
### Database
36+
37+
- Migrations committed to git
38+
- Use Eloquent or query builder (no raw SQL unless parameterized)
39+
- Index any column used in `where` or `orderBy`
40+
- Avoid mutating model instances in services; prefer create/update through repositories or query builders
41+
42+
### Authentication
43+
44+
- API auth via Sanctum
45+
- Use policies for model-level authorization
46+
- Enforce auth in controllers and services
47+
48+
### Validation
49+
50+
- Use Form Requests for validation
51+
- Transform input to DTOs for business logic
52+
- Never trust request payloads for derived fields
53+
54+
### Error Handling
55+
56+
- Throw domain exceptions in services
57+
- Map exceptions to HTTP responses in `bootstrap/app.php` via `withExceptions`
58+
- Never expose internal errors to clients
59+
60+
### Code Style
61+
62+
- No emojis in code or comments
63+
- Max line length: 120 characters
64+
- Controllers are thin; services and actions hold business logic
65+
66+
## File Structure
67+
68+
```
69+
app/
70+
Actions/
71+
Console/
72+
Events/
73+
Exceptions/
74+
Http/
75+
Controllers/
76+
Middleware/
77+
Requests/
78+
Resources/
79+
Jobs/
80+
Models/
81+
Policies/
82+
Providers/
83+
Services/
84+
Support/
85+
config/
86+
database/
87+
factories/
88+
migrations/
89+
seeders/
90+
routes/
91+
api.php
92+
web.php
93+
```
94+
95+
## Key Patterns
96+
97+
### Service Layer
98+
99+
```php
100+
<?php
101+
102+
declare(strict_types=1);
103+
104+
final class CreateOrderAction
105+
{
106+
public function __construct(private OrderRepository $orders) {}
107+
108+
public function handle(CreateOrderData $data): Order
109+
{
110+
return $this->orders->create($data);
111+
}
112+
}
113+
114+
final class OrderService
115+
{
116+
public function __construct(private CreateOrderAction $createOrder) {}
117+
118+
public function placeOrder(CreateOrderData $data): Order
119+
{
120+
return $this->createOrder->handle($data);
121+
}
122+
}
123+
```
124+
125+
### Controller Pattern
126+
127+
```php
128+
<?php
129+
130+
declare(strict_types=1);
131+
132+
final class OrdersController extends Controller
133+
{
134+
public function __construct(private OrderService $service) {}
135+
136+
public function store(StoreOrderRequest $request): JsonResponse
137+
{
138+
$order = $this->service->placeOrder($request->toDto());
139+
140+
return response()->json([
141+
'success' => true,
142+
'data' => OrderResource::make($order),
143+
'error' => null,
144+
'meta' => null,
145+
], 201);
146+
}
147+
}
148+
```
149+
150+
### Policy Pattern
151+
152+
```php
153+
<?php
154+
155+
declare(strict_types=1);
156+
157+
use App\Models\Order;
158+
use App\Models\User;
159+
160+
final class OrderPolicy
161+
{
162+
public function view(User $user, Order $order): bool
163+
{
164+
return $order->user_id === $user->id;
165+
}
166+
}
167+
```
168+
169+
### Form Request + DTO
170+
171+
```php
172+
<?php
173+
174+
declare(strict_types=1);
175+
176+
final class StoreOrderRequest extends FormRequest
177+
{
178+
public function authorize(): bool
179+
{
180+
return (bool) $this->user();
181+
}
182+
183+
public function rules(): array
184+
{
185+
return [
186+
'items' => ['required', 'array', 'min:1'],
187+
'items.*.sku' => ['required', 'string'],
188+
'items.*.quantity' => ['required', 'integer', 'min:1'],
189+
];
190+
}
191+
192+
public function toDto(): CreateOrderData
193+
{
194+
return new CreateOrderData(
195+
userId: (int) $this->user()->id,
196+
items: $this->validated('items'),
197+
);
198+
}
199+
}
200+
```
201+
202+
### API Resource
203+
204+
```php
205+
<?php
206+
207+
declare(strict_types=1);
208+
209+
use Illuminate\Http\Request;
210+
use Illuminate\Http\Resources\Json\JsonResource;
211+
212+
final class OrderResource extends JsonResource
213+
{
214+
public function toArray(Request $request): array
215+
{
216+
return [
217+
'id' => $this->id,
218+
'status' => $this->status,
219+
'total' => $this->total,
220+
'created_at' => $this->created_at?->toIso8601String(),
221+
];
222+
}
223+
}
224+
```
225+
226+
### Queue Job
227+
228+
```php
229+
<?php
230+
231+
declare(strict_types=1);
232+
233+
use Illuminate\Bus\Queueable;
234+
use Illuminate\Contracts\Queue\ShouldQueue;
235+
use Illuminate\Foundation\Bus\Dispatchable;
236+
use Illuminate\Queue\InteractsWithQueue;
237+
use Illuminate\Queue\SerializesModels;
238+
use App\Repositories\OrderRepository;
239+
use App\Services\OrderMailer;
240+
241+
final class SendOrderConfirmation implements ShouldQueue
242+
{
243+
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
244+
245+
public function __construct(private int $orderId) {}
246+
247+
public function handle(OrderRepository $orders, OrderMailer $mailer): void
248+
{
249+
$order = $orders->findOrFail($this->orderId);
250+
$mailer->sendOrderConfirmation($order);
251+
}
252+
}
253+
```
254+
255+
### Test Pattern (Pest)
256+
257+
```php
258+
<?php
259+
260+
declare(strict_types=1);
261+
262+
use App\Models\User;
263+
use Illuminate\Foundation\Testing\RefreshDatabase;
264+
use function Pest\Laravel\actingAs;
265+
use function Pest\Laravel\assertDatabaseHas;
266+
use function Pest\Laravel\postJson;
267+
268+
uses(RefreshDatabase::class);
269+
270+
test('user can place order', function () {
271+
$user = User::factory()->create();
272+
273+
actingAs($user);
274+
275+
$response = postJson('/api/orders', [
276+
'items' => [['sku' => 'sku-1', 'quantity' => 2]],
277+
]);
278+
279+
$response->assertCreated();
280+
assertDatabaseHas('orders', ['user_id' => $user->id]);
281+
});
282+
```
283+
284+
### Test Pattern (PHPUnit)
285+
286+
```php
287+
<?php
288+
289+
declare(strict_types=1);
290+
291+
use App\Models\User;
292+
use Illuminate\Foundation\Testing\RefreshDatabase;
293+
use Tests\TestCase;
294+
295+
final class OrdersControllerTest extends TestCase
296+
{
297+
use RefreshDatabase;
298+
299+
public function test_user_can_place_order(): void
300+
{
301+
$user = User::factory()->create();
302+
303+
$response = $this->actingAs($user)->postJson('/api/orders', [
304+
'items' => [['sku' => 'sku-1', 'quantity' => 2]],
305+
]);
306+
307+
$response->assertCreated();
308+
$this->assertDatabaseHas('orders', ['user_id' => $user->id]);
309+
}
310+
}
311+
```

‎rules/php/coding-style.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,11 @@ paths:
2525
- Use **PHPStan** or **Psalm** for static analysis.
2626
- Keep Composer scripts checked in so the same commands run locally and in CI.
2727

28+
## Imports
29+
30+
- Add `use` statements for all referenced classes, interfaces, and traits.
31+
- Avoid relying on the global namespace unless the project explicitly prefers fully qualified names.
32+
2833
## Error Handling
2934

3035
- Throw exceptions for exceptional states; avoid returning `false`/`null` as hidden error channels in new code.

‎rules/php/patterns.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,4 @@ paths:
3030
## Reference
3131

3232
See skill: `api-design` for endpoint conventions and response-shape guidance.
33+
See skill: `laravel-patterns` for Laravel-specific architecture guidance.

‎rules/php/security.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,7 @@ paths:
3131
- Use `password_hash()` / `password_verify()` for password storage.
3232
- Regenerate session identifiers after authentication and privilege changes.
3333
- Enforce CSRF protection on state-changing web requests.
34+
35+
## Reference
36+
37+
See skill: `laravel-security` for Laravel-specific security guidance.

‎rules/php/testing.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ paths:
1111
1212
## Framework
1313

14-
Use **PHPUnit** as the default test framework. **Pest** is also acceptable when the project already uses it.
14+
Use **PHPUnit** as the default test framework. If **Pest** is configured in the project, prefer Pest for new tests and avoid mixing frameworks.
1515

1616
## Coverage
1717

@@ -29,6 +29,11 @@ Prefer **pcov** or **Xdebug** in CI, and keep coverage thresholds in CI rather t
2929
- Use factory/builders for fixtures instead of large hand-written arrays.
3030
- Keep HTTP/controller tests focused on transport and validation; move business rules into service-level tests.
3131

32+
## Inertia
33+
34+
If the project uses Inertia.js, prefer `assertInertia` with `AssertableInertia` to verify component names and props instead of raw JSON assertions.
35+
3236
## Reference
3337

3438
See skill: `tdd-workflow` for the repo-wide RED -> GREEN -> REFACTOR loop.
39+
See skill: `laravel-tdd` for Laravel-specific testing patterns (PHPUnit and Pest).

0 commit comments

Comments
 (0)