Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
a685f0d
Assert the exact Exists and Unique rules in data validation tests
binaryfire Nov 20, 2026
0b89f84
Add permission route group macros and document global scopes
binaryfire Nov 20, 2026
9f0cd77
Make the disabled teams relation queryable and read-only
binaryfire Nov 20, 2026
d20b9fb
Test that a refresh doesn't leave the JWT manager in refresh mode
binaryfire Nov 20, 2026
9503cc3
Let a connector choose the URL API version for its requests
binaryfire Nov 20, 2026
4f6dfa8
Restart sub-minute task cycles each minute in the long-running scheduler
binaryfire Nov 20, 2026
13d8841
Document Sentry violation context and classification message types
binaryfire Nov 20, 2026
87419a2
Monitor all scheduled tasks and refine Sentry transaction names
binaryfire Nov 20, 2026
8a285de
Explain using Hypervel's migrations for framework tables when porting
binaryfire Nov 20, 2026
d471d1d
Evaluate scheduled tasks in their own timezone
binaryfire Nov 20, 2026
b5d5302
Record every polled minute when detecting a clock set back
binaryfire Nov 20, 2026
1c18166
Reject every write through the disabled teams relation
binaryfire Nov 20, 2026
58853f8
Leave out schedules Sentry would read differently
binaryfire Nov 20, 2026
dbb099a
Note that only connectors with an API version use the URL version hook
binaryfire Nov 20, 2026
9db9dbb
Keep skeleton migrations only for missing framework tables when porting
binaryfire Nov 20, 2026
18ea58b
Compare cron range values as numbers when checking Sentry schedules
binaryfire Nov 20, 2026
dfd40ba
Start fresh databases from a schema dump after porting an existing one
binaryfire Nov 20, 2026
a57b08b
Describe exactly which writes the disabled teams relation rejects
binaryfire Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 23 additions & 10 deletions src/console/src/Commands/ScheduleRunCommand.php
Comment thread
macroscopeapp[bot] marked this conversation as resolved.
Resolved
Original file line number Diff line number Diff line change
Expand Up @@ -123,9 +123,9 @@ class ScheduleRunCommand extends Command
protected ?Concurrent $concurrent = null;

/**
* The minute currently represented by the evaluated event cache.
* The minute since the Unix epoch currently represented by the evaluated event cache.
*/
protected ?string $evaluatedEventsMinute = null;
protected ?int $evaluatedEventsMinute = null;

/**
* The non-repeatable events already evaluated for the current minute.
Expand Down Expand Up @@ -293,17 +293,33 @@ protected function repeatEvents(Collection $events): void
protected function runEvents(Collection $events, CarbonInterface $startedAt): void
{
$paused = $this->isPaused();
$minute = intdiv($startedAt->getTimestamp(), 60);

// A clock set back into the previous minute doesn't run its events again, while a longer
// correction evaluates the earlier minutes again, as a fresh scheduler would. Every poll
// records its minute, so minutes without due events don't hide a longer correction.
$isPreviousMinute = $this->evaluatedEventsMinute !== null && $minute === $this->evaluatedEventsMinute - 1;

if (! $isPreviousMinute && $minute !== $this->evaluatedEventsMinute) {
$this->evaluatedEventsMinute = $minute;
$this->evaluatedEvents = [];
}

foreach ($events as $event) {
if ($this->shouldQuit) {
break;
}

if ($event->isRepeatable() && $event->lastChecked && ! $event->shouldRepeatNow()) {
// Laravel starts a fresh scheduler each minute, so a repeatable event's first check in a later
// minute runs regardless of the last check. Otherwise a late check would delay later minutes too.
if ($event->isRepeatable()
&& $event->lastChecked
&& intdiv($event->lastChecked->getTimestamp(), 60) >= $minute
&& ! $event->shouldRepeatNow()) {
continue;
}

if ($this->hasAlreadyEvaluatedNonRepeatableEvent($event, $startedAt)) {
if ($this->hasAlreadyEvaluatedNonRepeatableEvent($event, $isPreviousMinute)) {
continue;
}

Expand Down Expand Up @@ -419,17 +435,14 @@ protected function runScheduledEvent(Event $event, CarbonInterface $startedAt):
/**
* Determine if the non-repeatable event was already evaluated this minute.
*/
protected function hasAlreadyEvaluatedNonRepeatableEvent(Event $event, CarbonInterface $startedAt): bool
protected function hasAlreadyEvaluatedNonRepeatableEvent(Event $event, bool $isPreviousMinute): bool
{
if ($event->isRepeatable()) {
return false;
}

$minute = $startedAt->format('YmdHi');

if ($this->evaluatedEventsMinute !== $minute) {
$this->evaluatedEventsMinute = $minute;
$this->evaluatedEvents = [];
if ($isPreviousMinute) {
return true;
}

$eventId = spl_object_id($event);
Expand Down
5 changes: 3 additions & 2 deletions src/console/src/Scheduling/Event.php
Original file line number Diff line number Diff line change
Expand Up @@ -399,8 +399,9 @@ protected function expressionPasses(DateTimeInterface $time): bool
$date = $date->setTimezone($this->timezone);
}

return (new CronExpression($this->expression))
->isDue($date->toDateTimeString());
// Laravel passes a formatted string, which is read in the application's timezone and
// matches the wrong times around that timezone's daylight saving changes
return (new CronExpression($this->expression))->isDue($date);
}

/**
Expand Down
63 changes: 62 additions & 1 deletion src/docs/permission.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@
- [Deleting Models](#deleting-models)
- [UUID and ULID Keys](#uuid-and-ulid-keys)
- [Caching](#caching)
- [Global Scopes and Multitenancy](#global-scopes-and-multitenancy)
- [Testing and Seeding](#testing-and-seeding)
- [Seeding](#seeding)
- [Testing](#testing)
Expand Down Expand Up @@ -1051,7 +1052,7 @@ The `@hasrole` directive is an alias of `@role`. Role directives accept a role n
<a name="route-macros"></a>
## Route Macros

Routes also receive permission macros:
Routes and route groups also receive `role`, `permission`, and `roleOrPermission` macros, which accept a string, an array, or an [enum](#using-enums):

```php
Route::get('/admin', [AdminController::class, 'index'])->role('admin');
Expand All @@ -1060,8 +1061,52 @@ Route::get('/posts/edit', [PostController::class, 'edit'])->permission('edit art

Route::get('/content', [ContentController::class, 'index'])
->roleOrPermission(['editor', 'edit articles']);

Route::permission('publish articles')->group(function () {
// ...
});

Route::prefix('admin')->middleware('auth')->role('manager')->group(function () {
// ...
});
```

The `canAny` and `canAll` macros check a list of permissions, requiring any one of them or all of them. They work on individual routes and groups, accepting strings, enums, or arrays containing either:

```php
Route::get('/articles', [ArticleController::class, 'index'])
->canAny(['publish articles', 'edit articles']);

Route::get('/articles', [ArticleController::class, 'index'])
->canAll(['publish articles', 'edit articles']);

Route::middleware('auth:admin')->canAll(['publish articles', 'edit articles'])->group(function () {
// Requires both permissions for the authenticated admin.
});
```

These macros use the package's permission middleware; the route's own `can` method is unchanged. `canAny` is an alias for `permission`. `canAll` adds a permission middleware check for each array entry, so use separate entries to require separate permissions: a string separated by `|` still requires only one of its permissions. An empty `canAll([])` adds no checks, so apply authentication middleware separately when needed.

On route groups, call `middleware` before `role`, `permission`, `roleOrPermission`, `canAny`, or `canAll`. Calling `middleware` again on a group replaces the group's middleware, so calling it after one of these macros removes the role or permission check:

```php
Route::middleware('auth')->role('manager')->permission('publish articles')->group(function () {
// Requires authentication, the manager role, and the publish articles permission.
});
```

To add more middleware without replacing the group's authorization checks, use a nested group:

```php
Route::middleware('auth')->role('manager')->group(function () {
Route::middleware('throttle:60,1')->group(function () {
// Requires authentication, the manager role, and the rate limit.
});
});
```

Individual routes, such as `Route::get(...)->role('manager')->middleware('auth')`, add the middleware rather than replacing it.

<a name="custom-permission-checks"></a>
## Custom Permission Checks

Expand Down Expand Up @@ -1824,6 +1869,22 @@ app(PermissionRegistrar::class)->forgetCachedPermissions();

If you reset the cache inside a database transaction, the reset is applied after the transaction commits and discarded if it rolls back. The method returns `true` once such a reset has been registered. When row partitioning is enabled, the reset applies only to the current partition.

<a name="global-scopes-and-multitenancy"></a>
### Global Scopes and Multitenancy

The package fills the cached catalog and each model's cached assignments by querying your configured role and permission models, so Eloquent global scopes on either model apply to these queries.

The cache is shared between requests and jobs, so a scope that depends on the current request can affect later permission checks. For example, if a request for tenant A fills the cache while a global scope limits roles to tenant A, tenant B's roles will be missing from the catalog. A later request for tenant B can then deny permissions its roles should grant. Request-specific scopes on the permission model cause the same problem.

Teams don't prevent this. Every team shares the catalog, and selecting a team with `setPermissionsTeamId()` doesn't change which global scopes apply when the cache is filled.

Choose an approach that matches what the scope is for:

- If the scope only filters an administration screen, apply it to that screen's queries instead of registering it globally on the role or permission model. Check whether a package you use registers such a scope on these models.
- If authorization must be limited to the current tenant, use [row partitioning](#row-partitioning), which separates each tenant's rows and cache entries.

After correcting the scope, reset the permission cache as shown above. Resetting the cache on every request does not solve this problem, since the next fill still uses whichever scopes are active at that time.

<a name="testing-and-seeding"></a>
## Testing and Seeding

Expand Down
2 changes: 2 additions & 0 deletions src/docs/porting-from-laravel.md
Original file line number Diff line number Diff line change
Expand Up @@ -1029,6 +1029,8 @@ When porting an application, start from a fresh Hypervel application skeleton an

Do not replace the Hypervel skeleton's `composer.json`, `bootstrap/app.php`, `config` directory, `.env.example`, or `phpunit.xml` with their Laravel counterparts. Move application providers into `bootstrap/providers.php`, move routes into Hypervel's `routes` files, and configure middleware through the Hypervel `bootstrap/app.php` file. Transfer environment values into the corresponding Hypervel configuration keys instead of copying the Laravel environment file unchanged.

Use Hypervel's migrations for framework tables such as jobs, job batches, sessions, and cache. Bring over migrations for your application's own tables and reapply any customizations to framework tables on top of Hypervel's schema. If you're keeping an existing database, preserve its migration history and keep the skeleton's migrations only for framework tables the database doesn't have yet, since the others would try to create tables that already exist. Then write new migrations for the changes needed to bring its existing framework tables in line with Hypervel's schema. Once those migrations have run, [dump the database schema](/docs/{{version}}/migrations#squashing-migrations) with its migration records. Fresh databases then start from the dump, since no remaining migration creates the framework tables the database already had.

Hypervel runs its Swoole HTTP server using `php artisan serve` and does not use `public/index.php` as its HTTP entry point. Review the [deployment documentation](/docs/{{version}}/deployment) before adapting web server or process-monitor configuration.

Build production releases with `composer install --no-dev --classmap-authoritative` instead of `--optimize-autoloader`; Doctor fails production checks without an authoritative class map. See [Autoloader Optimization](/docs/{{version}}/deployment#autoloader-optimization).
Expand Down
2 changes: 1 addition & 1 deletion src/docs/saloon.md
Original file line number Diff line number Diff line change
Expand Up @@ -641,7 +641,7 @@ class AnthropicConnector extends Connector
}
```

In URL mode, the version replaces a `{version}` placeholder in the base URL, endpoint, or URL override, such as `https://generativelanguage.googleapis.com/{version}`. The version may only contain letters, numbers, dashes, underscores, and single dots, so it can only fill that subdomain label or path segment. You may override `getApiVersion` to calculate the version. When both a connector and a request send a version, the request's version is used.
In URL mode, the version replaces a `{version}` placeholder in the base URL, endpoint, or URL override, such as `https://generativelanguage.googleapis.com/{version}`. The version may only contain letters, numbers, dashes, underscores, and single dots, so it can only fill that subdomain label or path segment. You may override `getApiVersion` to calculate the version. When a connector and a request both send a version in the same place, the request's version is used. To choose the version substituted into the URL differently, a connector with an API version may override the protected `resolveUrlApiVersion` method, which receives the pending request.

<a name="authentication"></a>
### Authentication
Expand Down
13 changes: 12 additions & 1 deletion src/docs/sentry.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ To enable performance monitoring, configure a trace sample rate between `0.0` an
SENTRY_TRACES_SAMPLE_RATE=0.1
```

The default configuration traces requests, database queries, HTTP client requests, cache operations, queued jobs, notifications, and views. The conventional `/up` health route path is ignored by default.
The default configuration traces requests, database queries, HTTP client requests, cache operations, queued jobs, notifications, and views. The conventional `/up` health route path and the Horizon and Telescope routes are ignored by default.

Cache spans and breadcrumbs follow cache repository events. Configured stores honor their `events` option, but the `failover` store defaults this option to `false`; enable it explicitly when failover operations should produce telemetry. `Cache::memo()` does not emit a second event for its memoization layer, while operations that reach the wrapped repository follow that store's setting.

Expand Down Expand Up @@ -368,6 +368,17 @@ Schedule::command('reports:generate')

When no monitor slug is given, one is derived from the task's command or description. The macro also accepts the `checkInMargin`, `maxRuntime`, `failureIssueThreshold`, and `recoveryThreshold` monitor settings. Pass `updateMonitorConfig: false` when the monitor is configured in Sentry instead.

To monitor every scheduled task without calling `sentryMonitor` on each one, set the `SENTRY_CRONS_MONITOR_SCHEDULED_TASKS` environment variable to `true`. Tasks that call `sentryMonitor` keep their own settings. You may leave tasks out by listing their monitor slugs, commands, or names in the `crons.exclude_scheduled_tasks` configuration option, using `*` as a wildcard. Unless you give a scheduled job a name, it's named after its class, or by its `displayName` method when you schedule a job instance that has one:

```php
'crons' => [
'monitor_scheduled_tasks' => (bool) env('SENTRY_CRONS_MONITOR_SCHEDULED_TASKS', false),
'exclude_scheduled_tasks' => ['horizon:snapshot', 'scheduled_reports-*'],
],
```

Tasks are only monitored automatically when Sentry can expect every run, so closures without a `name`, tasks that share a slug, sub-minute tasks, tasks with a timezone offset instead of a timezone name, tasks limited by `between`, `unlessBetween`, `when`, or `skip`, and schedules Sentry would read differently, such as some times of day that a daylight saving change skips, are left out. Only a task's time and weekday are compared with daylight saving changes, so a task at such a time can be left out even if its dates never have a change. Call `sentryMonitor` on such a task to monitor it yourself.

Sentry expects a check-in for every run of the task's schedule. Tasks limited by `between`, `unlessBetween`, `when`, or `skip` do not check in when they are skipped, so their skipped runs are reported as missed. Prefer expressing the schedule with the `cron` method.

Failed runs check in as errors, including failures before completion callbacks run. When coroutine cancellation interrupts a run without a known failure, any unfinished check-in is left open because Sentry has no canceled status. Sentry later reports it as timed out. An earlier task failure, or a cleanup failure before the task's outcome is known, still produces an error check-in.
Expand Down
88 changes: 88 additions & 0 deletions src/permission/src/PermissionServiceProvider.php
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@
use Hypervel\Permission\Middleware\RoleMiddleware;
use Hypervel\Permission\Middleware\RoleOrPermissionMiddleware;
use Hypervel\Routing\Route;
use Hypervel\Routing\Router;
use Hypervel\Routing\RouteRegistrar;
use Hypervel\Support\Arr;
use Hypervel\Support\Collection;
use Hypervel\Support\ServiceProvider;
Expand Down Expand Up @@ -156,6 +158,92 @@ protected function registerMacroHelpers(): void
/** @var Route $this */
return $this->middleware('role_or_permission:' . implode('|', $rolesOrPermissions));
});

RouteRegistrar::macro('role', function (mixed $roles = []): RouteRegistrar {
$roles = Arr::wrap($roles);
$roles = array_map(enum_value(...), $roles);

/** @var RouteRegistrar $this */
return $this->middleware([...($this->attributes['middleware'] ?? []), 'role:' . implode('|', $roles)]);
});

RouteRegistrar::macro('permission', function (mixed $permissions = []): RouteRegistrar {
$permissions = Arr::wrap($permissions);
$permissions = array_map(enum_value(...), $permissions);

/** @var RouteRegistrar $this */
return $this->middleware([...($this->attributes['middleware'] ?? []), 'permission:' . implode('|', $permissions)]);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
});

RouteRegistrar::macro('roleOrPermission', function (mixed $rolesOrPermissions = []): RouteRegistrar {
$rolesOrPermissions = Arr::wrap($rolesOrPermissions);
$rolesOrPermissions = array_map(enum_value(...), $rolesOrPermissions);

/** @var RouteRegistrar $this */
return $this->middleware([...($this->attributes['middleware'] ?? []), 'role_or_permission:' . implode('|', $rolesOrPermissions)]);
});

Router::macro('role', function (mixed $roles = []): RouteRegistrar {
$roles = Arr::wrap($roles);
$roles = array_map(enum_value(...), $roles);

/** @var Router $this */
return $this->middleware('role:' . implode('|', $roles));
});

Router::macro('permission', function (mixed $permissions = []): RouteRegistrar {
$permissions = Arr::wrap($permissions);
$permissions = array_map(enum_value(...), $permissions);

/** @var Router $this */
return $this->middleware('permission:' . implode('|', $permissions));
});

Router::macro('roleOrPermission', function (mixed $rolesOrPermissions = []): RouteRegistrar {
$rolesOrPermissions = Arr::wrap($rolesOrPermissions);
$rolesOrPermissions = array_map(enum_value(...), $rolesOrPermissions);

/** @var Router $this */
return $this->middleware('role_or_permission:' . implode('|', $rolesOrPermissions));
});

Route::macro('canAny', function (mixed $permissions = []): Route {
/** @var Route $this */
return $this->permission($permissions);
});

Route::macro('canAll', function (mixed $permissions = []): Route {
foreach (Arr::wrap($permissions) as $permission) {
/** @var Route $this */
$this->permission($permission);
}

return $this;
});

RouteRegistrar::macro('canAny', function (mixed $permissions = []): RouteRegistrar {
/** @var RouteRegistrar $this */
return $this->permission($permissions);
});

RouteRegistrar::macro('canAll', function (mixed $permissions = []): RouteRegistrar {
foreach (Arr::wrap($permissions) as $permission) {
/** @var RouteRegistrar $this */
$this->permission($permission);
}

return $this;
});

Router::macro('canAny', function (mixed $permissions = []): RouteRegistrar {
/** @var Router $this */
return $this->permission($permissions);
});

Router::macro('canAll', function (mixed $permissions = []): RouteRegistrar {
/** @var Router $this */
return (new RouteRegistrar($this))->canAll($permissions);
});
}

/**
Expand Down
Loading