You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: "Use this skill whenever the user mentions Horizon by name in a Laravel context. Covers the full Horizon lifecycle: installing Horizon (horizon:install, Sail setup), configuring config/horizon.php (supervisor blocks, queue assignments, balancing strategies, minProcesses/maxProcesses), fixing the dashboard (authorization via Gate::define viewHorizon, blank metrics, horizon:snapshot scheduling), and troubleshooting production issues (worker crashes, timeout chain ordering, LongWaitDetected notifications, waits config). Also covers job tagging and silencing. Do not use for generic Laravel queues without Horizon, SQS or database drivers, standalone Redis setup, Linux supervisord, Telescope, or job batching."
4
+
license: MIT
5
+
metadata:
6
+
author: laravel
7
+
---
8
+
9
+
# Horizon Configuration
10
+
11
+
## Documentation
12
+
13
+
Use `search-docs` for detailed Horizon patterns and documentation covering configuration, supervisors, balancing, dashboard authorization, tags, notifications, metrics, and deployment.
14
+
15
+
For deeper guidance on specific topics, read the relevant reference file before implementing:
16
+
17
+
-`references/supervisors.md` covers supervisor blocks, balancing strategies, multi-queue setups, and auto-scaling
18
+
-`references/notifications.md` covers LongWaitDetected alerts, notification routing, and the `waits` config
19
+
-`references/tags.md` covers job tagging, dashboard filtering, and silencing noisy jobs
20
+
-`references/metrics.md` covers the blank metrics dashboard, snapshot scheduling, and retention config
21
+
22
+
## Basic Usage
23
+
24
+
### Installation
25
+
26
+
```bash
27
+
php artisan horizon:install
28
+
```
29
+
30
+
### Supervisor Configuration
31
+
32
+
Define supervisors in `config/horizon.php`. The `environments` array merges into `defaults` and does not replace the whole supervisor block:
Restrict access in `App\Providers\HorizonServiceProvider`:
60
+
61
+
<!-- Dashboard Gate -->
62
+
```php
63
+
protected function gate(): void
64
+
{
65
+
Gate::define('viewHorizon', function (User $user) {
66
+
return $user->is_admin;
67
+
});
68
+
}
69
+
```
70
+
71
+
## Verification
72
+
73
+
1. Run `php artisan horizon` and visit `/horizon`
74
+
2. Confirm dashboard access is restricted as expected
75
+
3. Check that metrics populate after scheduling `horizon:snapshot`
76
+
77
+
## Common Pitfalls
78
+
79
+
- Horizon only works with the Redis queue driver. Other drivers such as database and SQS are not supported.
80
+
- Redis Cluster is not supported. Horizon requires a standalone Redis connection.
81
+
- Always check `config/horizon.php` before making changes to understand the current supervisor and environment configuration.
82
+
- The `environments` array overrides only the keys you specify. It merges into `defaults` and does not replace it.
83
+
- The timeout chain must be ordered: job `timeout` less than supervisor `timeout` less than `retry_after`. The wrong order can cause jobs to be retried before Horizon finishes timing them out.
84
+
- The metrics dashboard stays blank until `horizon:snapshot` is scheduled. Running `php artisan horizon` alone does not populate metrics.
85
+
- Always use `search-docs` for the latest Horizon documentation rather than relying on this skill alone.
-`"horizon metrics snapshot"` for the snapshot command and scheduling
7
+
-`"horizon trim snapshots"` for retention configuration
8
+
9
+
## What to Watch For
10
+
11
+
### Metrics dashboard stays blank until `horizon:snapshot` is scheduled
12
+
13
+
Running `horizon` artisan command does not populate metrics automatically. The metrics graph is built from snapshots, so `horizon:snapshot` must be scheduled to run every 5 minutes via Laravel's scheduler.
14
+
15
+
### Register the snapshot in the scheduler rather than running it manually
16
+
17
+
A single manual run populates the dashboard momentarily but will not keep it updated. Search `"horizon metrics snapshot"` for the exact scheduler registration syntax, which differs between Laravel 10 and 11+.
18
+
19
+
### `metrics.trim_snapshots` is a snapshot count, not a time duration
20
+
21
+
The `trim_snapshots.job` and `trim_snapshots.queue` values in `config/horizon.php` are counts of snapshots to keep, not minutes or hours. With the default of 24 snapshots at 5-minute intervals, that provides 2 hours of history. Increase the value to retain more history at the cost of Redis memory usage.
-`"horizon notifications"` for Horizon's built-in notification routing helpers
7
+
-`"horizon long wait detected"` for LongWaitDetected event details
8
+
9
+
## What to Watch For
10
+
11
+
### `waits` in `config/horizon.php` controls the LongWaitDetected threshold
12
+
13
+
The `waits` array (e.g., `'redis:default' => 60`) defines how many seconds a job can wait in a queue before Horizon fires a `LongWaitDetected` event. This value is set in the config file, not in Horizon's notification routing. If alerts are firing too often or too late, adjust `waits` rather than the routing configuration.
14
+
15
+
### Use Horizon's built-in notification routing in `HorizonServiceProvider`
16
+
17
+
Configure notifications in the `boot()` method of `App\Providers\HorizonServiceProvider` using `Horizon::routeMailNotificationsTo()`, `Horizon::routeSlackNotificationsTo()`, or `Horizon::routeSmsNotificationsTo()`. Horizon already wires `LongWaitDetected` to its notification sender, so the documented setup is notification routing rather than manual listener registration.
18
+
19
+
### Failed job alerts are separate from Horizon's documented notification routing
20
+
21
+
Horizon's 12.x documentation covers built-in long-wait notifications. Do not assume the docs provide a `JobFailed` listener example in `HorizonServiceProvider`. If a user needs failed job alerts, treat that as custom queue event handling and consult the queue documentation instead of Horizon's notification-routing API.
Search with `search-docs` before writing any supervisor config, as option names and defaults change between Horizon versions:
6
+
-`"horizon supervisor configuration"` for the full options list
7
+
-`"horizon balancing strategies"` for auto, simple, and false modes
8
+
-`"horizon autoscaling workers"` for autoScalingStrategy details
9
+
-`"horizon environment configuration"` for the defaults and environments merge
10
+
11
+
## What to Watch For
12
+
13
+
### The `environments` array merges into `defaults` rather than replacing it
14
+
15
+
The `defaults` array defines the complete base supervisor config. The `environments` array patches it per environment, overriding only the keys listed. There is no need to repeat every key in each environment block. A common pattern is to define `connection`, `queue`, `balance`, `autoScalingStrategy`, `tries`, and `timeout` in `defaults`, then override only `maxProcesses`, `balanceMaxShift`, and `balanceCooldown` in `production`.
16
+
17
+
### Use separate named supervisors to enforce queue priority
18
+
19
+
Horizon does not enforce queue order when using `balance: auto` on a single supervisor. The `queue` array order is ignored for load balancing. To process `notifications` before `default`, use two separately named supervisors: one for the high-priority queue with a higher `maxProcesses`, and one for the low-priority queue with a lower cap. The docs include an explicit note about this.
20
+
21
+
### Use `balance: false` to keep a fixed number of workers on a dedicated queue
22
+
23
+
Auto-balancing suits variable load, but if a queue should always have exactly N workers such as a video-processing queue limited to 2, set `balance: false` and `maxProcesses: 2`. Auto-balancing would scale it up during bursts, which may be undesirable.
24
+
25
+
### Set `balanceCooldown` to prevent rapid worker scaling under bursty load
26
+
27
+
When using `balance: auto`, the supervisor can scale up and down rapidly under bursty load. Set `balanceCooldown` to the number of seconds between scaling decisions, typically 3 to 5, to smooth this out. `balanceMaxShift` limits how many processes are added or removed per cycle.
-`"horizon tags"` for the tagging API and auto-tagging behaviour
7
+
-`"horizon silenced jobs"` for the `silenced` and `silenced_tags` config options
8
+
9
+
## What to Watch For
10
+
11
+
### Eloquent model jobs are tagged automatically without any extra code
12
+
13
+
If a job's constructor accepts Eloquent model instances, Horizon automatically tags the job with `ModelClass:id` such as `App\Models\User:42`. These tags are filterable in the dashboard without any changes to the job class. Only add a `tags()` method when custom tags beyond auto-tagging are needed.
14
+
15
+
### `silenced` hides jobs from the dashboard completed list but does not stop them from running
16
+
17
+
Adding a job class to the `silenced` array in `config/horizon.php` removes it from the completed jobs view. The job still runs normally. This is a dashboard noise-reduction tool, not a way to disable jobs.
18
+
19
+
### `silenced_tags` hides all jobs carrying a matching tag from the completed list
20
+
21
+
Any job carrying a matching tag string is hidden from the completed jobs view. This is useful for silencing a category of jobs such as all jobs tagged `notifications`, rather than silencing specific classes.
Copy file name to clipboardExpand all lines: .agents/skills/fortify-development/SKILL.md
+41-6Lines changed: 41 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,9 @@
1
1
---
2
-
name: developing-with-fortify
3
-
description: Laravel Fortify headless authentication backend development. Activate when implementing authentication features including login, registration, password reset, email verification, two-factor authentication (2FA/TOTP), profile updates, headless auth, authentication scaffolding, or auth guards in Laravel applications.
2
+
name: fortify-development
3
+
description: 'ACTIVATE when the user works on authentication in Laravel. This includes login, registration, password reset, email verification, two-factor authentication (2FA/TOTP/QR codes/recovery codes), passkeys, profile updates, password confirmation, or any auth-related routes and controllers. Activate when the user mentions Fortify, auth, authentication, login, register, signup, forgot password, verify email, 2FA, passkeys, WebAuthn, or references app/Actions/Fortify/, CreateNewUser, UpdateUserProfileInformation, FortifyServiceProvider, config/fortify.php, or auth guards. Fortify is the frontend-agnostic authentication backend for Laravel that registers all auth routes and controllers. Also activate when building SPA or headless authentication, customizing login redirects, overriding response contracts like LoginResponse, or configuring login throttling. Do NOT activate for Laravel Passport (OAuth2 API tokens), Socialite (OAuth social login), or non-auth Laravel features.'
4
+
license: MIT
5
+
metadata:
6
+
author: laravel
4
7
---
5
8
6
9
# Laravel Fortify Development
@@ -29,6 +32,7 @@ Enable in `config/fortify.php` features array:
-`Features::twoFactorAuthentication()` - 2FA with QR codes and recovery codes
35
+
-`Features::passkeys()` - Passwordless authentication with WebAuthn passkeys
32
36
33
37
> Use `search-docs` for feature configuration options and customization patterns.
34
38
@@ -39,14 +43,26 @@ Enable in `config/fortify.php` features array:
39
43
```
40
44
- [ ] Add TwoFactorAuthenticatable trait to User model
41
45
- [ ] Enable feature in config/fortify.php
42
-
- [ ] Run migrations for 2FA columns
46
+
- [ ] If the `*_add_two_factor_columns_to_users_table.php` migration is missing, publish via `php artisan vendor:publish --tag=fortify-migrations` and migrate
43
47
- [ ] Set up view callbacks in FortifyServiceProvider
44
48
- [ ] Create 2FA management UI
45
49
- [ ] Test QR code and recovery codes
46
50
```
47
51
48
52
> Use `search-docs` for TOTP implementation and recovery code handling patterns.
49
53
54
+
### Passkeys Setup
55
+
56
+
```
57
+
- [ ] Add PasskeyAuthenticatable trait to User model and implement PasskeyUser
58
+
- [ ] Enable passkeys feature in config/fortify.php
59
+
- [ ] If the passkeys table migration is missing, publish via `php artisan vendor:publish --tag=fortify-migrations` and migrate
60
+
- [ ] Configure passkeys relying_party_id, allowed_origins, user_handle_secret, and timeout if defaults are not suitable
61
+
- [ ] Build UI with @laravel/passkeys for registration, login, confirmation, and deletion
62
+
```
63
+
64
+
> Use `search-docs` for passkey configuration options. For `@laravel/passkeys` frontend usage, refer to the package's README on npm.
65
+
50
66
### Email Verification Setup
51
67
52
68
```
@@ -75,14 +91,26 @@ Enable in `config/fortify.php` features array:
75
91
76
92
```
77
93
- [ ] Set 'views' => false in config/fortify.php
78
-
- [ ] Install and configure Laravel Sanctum
79
-
- [ ] Use 'web' guard in fortify config
94
+
- [ ] Install and configure Laravel Sanctum for session-based SPA authentication
95
+
- [ ] Use the 'web' guard in config/fortify.php (required for session-based authentication)
80
96
- [ ] Set up CSRF token handling
81
97
- [ ] Test XHR authentication flows
82
98
```
83
99
84
100
> Use `search-docs` for integration and SPA authentication patterns.
85
101
102
+
#### Two-Factor Authentication in SPA Mode
103
+
104
+
When `views` is set to `false`, Fortify returns JSON responses instead of redirects.
105
+
106
+
If a user attempts to log in and two-factor authentication is enabled, the login request will return a JSON response indicating that a two-factor challenge is required:
107
+
108
+
```json
109
+
{
110
+
"two_factor": true
111
+
}
112
+
```
113
+
86
114
## Best Practices
87
115
88
116
### Custom Authentication Logic
@@ -113,4 +141,11 @@ Configure via `fortify.limiters.login` in config. Default configuration throttle
113
141
| Confirm 2FA | POST |`/user/confirmed-two-factor-authentication`|
0 commit comments