Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions src/contracts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,6 @@ The `Container` contract also requires `isScoped()`, `isScopedInstance()`, `reso

The `View` contract also requires `gatherData(): array`, which exposes the data used to render the view, including shared values, for response assertions. The standard `Hypervel\View\View` already provides it.

The `ExceptionHandler` contract also requires `shouldStopRetries(Throwable $e): bool`, so handlers that wrap another handler, such as the exception fake, keep its `dontRetry()` and `dontRetryWhen()` rules for queued jobs. Extending `Hypervel\Foundation\Exceptions\Handler` supplies it.

Ported from: https://github.com/laravel/framework/tree/13.x/src/Illuminate/Contracts
9 changes: 6 additions & 3 deletions src/contracts/src/Debug/ExceptionHandler.php
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,6 @@
use Symfony\Component\HttpFoundation\Response;
use Throwable;

/**
* @method bool shouldStopRetries(Throwable $e)
*/
interface ExceptionHandler
{
/**
Expand Down Expand Up @@ -58,4 +55,10 @@ public function buildContextForException(Throwable $e): array;
* Register a callback to be called after an HTTP error response is rendered.
*/
public function afterResponse(callable $callback): void;

// Unlike Laravel, this is required so wrapping handlers, such as the exception fake, keep the retry policy.
/**
* Determine if jobs should stop retrying for the given exception.
*/
public function shouldStopRetries(Throwable $e): bool;
}
22 changes: 22 additions & 0 deletions src/contracts/src/Foundation/Application.php
Original file line number Diff line number Diff line change
Expand Up @@ -40,53 +40,73 @@ public function setBasePath(string $basePath): static;

/**
* Get the base path of the Hypervel installation.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function basePath(string $path = ''): string;

/**
* Get the path to the bootstrap directory.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function bootstrapPath(string $path = ''): string;

/**
* Get the path to the application "app" directory.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function path(string $path = ''): string;

/**
* Get the path to the application configuration files.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function configPath(string $path = ''): string;

/**
* Get the path to the database directory.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function databasePath(string $path = ''): string;

/**
* Get the path to the language files.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function langPath(string $path = ''): string;

/**
* Get the path to the public directory.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function publicPath(string $path = ''): string;

/**
* Get the path to the resources directory.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function resourcePath(string $path = ''): string;

/**
* Get the path to the views directory.
*
* This method returns the first configured path in the array of view paths.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function viewPath(string $path = ''): string;

/**
* Get the path to the storage directory.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function storagePath(string $path = ''): string;

Expand All @@ -102,6 +122,8 @@ public function getCachedConfigPath(): string;

/**
* Join the given paths together.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
public function joinPaths(?string $basePath, string $path = ''): string;

Expand Down
64 changes: 64 additions & 0 deletions src/contracts/src/Queue/Queue.php
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@

use DateInterval;
use DateTimeInterface;
use Hypervel\Queue\Jobs\InspectedJob;
use Hypervel\Support\Attributes\BootOrTestsOnly;
use Hypervel\Support\Collection;
use UnitEnum;

interface Queue
Expand All @@ -31,11 +33,73 @@ public function delayedSize(UnitEnum|string|null $queue = null): int;
*/
public function reservedSize(UnitEnum|string|null $queue = null): int;

/**
* Get the number of jobs across every queue.
*/
public function totalSize(): int;

/**
* Get the number of pending jobs across every queue.
*/
public function totalPendingSize(): int;

/**
* Get the number of delayed jobs across every queue.
*/
public function totalDelayedSize(): int;

/**
* Get the number of reserved jobs across every queue.
*/
public function totalReservedSize(): int;

/**
* Get the creation timestamp of the oldest pending job, excluding delayed jobs.
*/
public function creationTimeOfOldestPendingJob(UnitEnum|string|null $queue = null): ?int;

/**
* Get the pending jobs for the given queue.
*
* @return Collection<int, InspectedJob>
*/
public function pendingJobs(UnitEnum|string|null $queue = null): Collection;

/**
* Get the delayed jobs for the given queue.
*
* @return Collection<int, InspectedJob>
*/
public function delayedJobs(UnitEnum|string|null $queue = null): Collection;

/**
* Get the reserved jobs for the given queue.
*
* @return Collection<int, InspectedJob>
*/
public function reservedJobs(UnitEnum|string|null $queue = null): Collection;

/**
* Get all pending jobs across every queue.
*
* @return Collection<int, InspectedJob>
*/
public function allPendingJobs(): Collection;

/**
* Get all delayed jobs across every queue.
*
* @return Collection<int, InspectedJob>
*/
public function allDelayedJobs(): Collection;

/**
* Get all reserved jobs across every queue.
*
* @return Collection<int, InspectedJob>
*/
public function allReservedJobs(): Collection;

/**
* Push a new job onto the queue.
*/
Expand Down
8 changes: 4 additions & 4 deletions src/docs/porting-from-laravel.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,8 @@ Some packages also define package-local contracts, such as `Hypervel\Permission\

Custom `Hypervel\Contracts\View\View` implementations must provide `gatherData(): array`, returning the data used to render the view, including any shared values. Extending `Hypervel\View\View` supplies it.

Custom `Hypervel\Contracts\Debug\ExceptionHandler` implementations must provide `shouldStopRetries(Throwable $e): bool`, which tells queue workers whether a job should stop retrying after the exception. Extending `Hypervel\Foundation\Exceptions\Handler` supplies it.

Custom `Hypervel\View\ViewFinderInterface` implementations must provide `prependLocation()`, `getPaths()` and `getHints()`; extending `Hypervel\View\FileViewFinder` supplies them.

<a name="missing-equivalents"></a>
Expand Down Expand Up @@ -522,11 +524,9 @@ Replace `laravel/doctor` with `hypervel/doctor` and the `Laravel\Doctor` namespa
<a name="static-analysis"></a>
### Static Analysis

Replace `larastan/larastan` with `hypervel/phpstan`. For manual configuration, replace Larastan's include with `vendor/hypervel/phpstan/extension.neon` and `vendor/phpstan/phpstan-deprecation-rules/rules.neon`.

Rename ignored identifiers from `larastan.*` to `hypervel.*`, and `rules.modelAppends` to `hypervel.modelAppends`. PHPStan's own identifiers are unchanged. Remove ignores for Octane and deferred provider diagnostics, and remove the unsupported `checkOctaneCompatibility`, `generalizeEnvReturnType` and `redisDriver` parameters.
Use `hypervel/phpstan` and start with the configuration in the [Static Analysis guide](/docs/{{version}}/static-analysis).

Supported parameters retain their names, but several defaults are stricter. The extension also reports ignores without reasons and uses of deprecated APIs. See [Static Analysis](/docs/{{version}}/static-analysis) for setup and configuration.
Review inline `@phpstan-ignore` comments in ported code. Remove ignores for Octane and deferred providers. Replace the `larastan.` prefix with `hypervel.` on remaining ignores, and replace `rules.modelAppends` with `hypervel.modelAppends`. Hypervel also reports ignores without reasons and uses of deprecated APIs.

<a name="scheduling"></a>
### Scheduling
Expand Down
12 changes: 12 additions & 0 deletions src/docs/static-analysis.md
Original file line number Diff line number Diff line change
Expand Up @@ -301,6 +301,18 @@ Declare the type the collection is meant to hold when you create it:
$ids = collect([1, 2, 3]);
```

Models loaded through a `BelongsToMany` or `MorphToMany` relation keep their pivot in collections too, including a custom accessor name set with `as()`:

```php
/** @return BelongsToMany<Podcast, $this, Subscription, 'subscription'> */
public function podcasts(): BelongsToMany
{
return $this->belongsToMany(Podcast::class)->as('subscription')->using(Subscription::class);
}

$user->podcasts->first()?->subscription; // Subscription|null
```

A custom collection class that fixes its item type, such as a `UserCollection` that extends `Collection<int, User>`, keeps that type when methods such as `map()`, `mapWithKeys()`, `groupBy()` and `chunk()` return the same class holding other items. This is a PHPStan limitation. For example, `$users->groupBy('team_id')` is typed as a `UserCollection` of users, although it holds user collections. Declare the result's type where your code relies on it:

```php
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,15 @@ public function buildContextForException(Throwable $e): array
public function afterResponse(callable $callback): void
{
}

/**
* Determine if jobs should stop retrying for the given exception.
*/
public function shouldStopRetries(Throwable $e): bool
{
// Retry policy is configuration, not exception handling.
return $this->originalHandler->shouldStopRetries($e);
}
};

$currentExceptionHandler = app(ExceptionHandler::class);
Expand Down
16 changes: 16 additions & 0 deletions src/foundation/src/helpers.php
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,8 @@ function app_id(): string
if (! function_exists('app_path')) {
/**
* Get the path to the application folder.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
function app_path(string $path = ''): string
{
Expand Down Expand Up @@ -237,6 +239,8 @@ function back(int $status = 302, array $headers = [], mixed $fallback = false):
if (! function_exists('base_path')) {
/**
* Get the path to the base of the install.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
function base_path(string $path = ''): string
{
Expand Down Expand Up @@ -358,6 +362,8 @@ function config(mixed $key = null, mixed $default = null): mixed
if (! function_exists('config_path')) {
/**
* Get the configuration path.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
function config_path(string $path = ''): string
{
Expand Down Expand Up @@ -441,6 +447,8 @@ function csrf_token(): ?string
if (! function_exists('database_path')) {
/**
* Get the path to the database folder.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
function database_path(string $path = ''): string
{
Expand Down Expand Up @@ -555,6 +563,8 @@ function info(Arrayable|Jsonable|Stringable|array|string $message, array $contex
if (! function_exists('lang_path')) {
/**
* Get the path to the language folder.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
function lang_path(string $path = ''): string
{
Expand Down Expand Up @@ -672,6 +682,8 @@ function precognitive(?callable $callable = null): mixed
if (! function_exists('public_path')) {
/**
* Get the path to the public folder.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
function public_path(string $path = ''): string
{
Expand Down Expand Up @@ -827,6 +839,8 @@ function resolve(string $name, array $parameters = [])
if (! function_exists('resource_path')) {
/**
* Get the path to the resources folder.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
function resource_path(string $path = ''): string
{
Expand Down Expand Up @@ -921,6 +935,8 @@ function session(array|UnitEnum|string|null $key = null, mixed $default = null):
if (! function_exists('storage_path')) {
/**
* Get the path to the storage folder.
*
* @return ($path is non-empty-string ? non-empty-string : string)
*/
function storage_path(string $path = ''): string
{
Expand Down
6 changes: 2 additions & 4 deletions src/log/src/Formatters/JsonFormatter.php
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,8 @@ protected function normalizeException(Throwable $e, int $depth = 0): array
}

// Active reports already carry this context at record level; rebuilding it can re-enter user callbacks.
if (! method_exists($handler, 'isReporting') || ! $handler->isReporting($e)) {
if (method_exists($handler, 'buildContextForException')
&& is_array($normalizedHandlerExceptionContext = $this->normalize($handler->buildContextForException($e), $depth + 1))
) {
if (! $handler->isReporting($e)) {
if (is_array($normalizedHandlerExceptionContext = $this->normalize($handler->buildContextForException($e), $depth + 1))) {
$response = array_replace($normalizedHandlerExceptionContext, $response);
} elseif (method_exists($e, 'context')) {
$response = array_replace($this->getExceptionContext($e, $depth), $response);
Expand Down
3 changes: 1 addition & 2 deletions src/phpstan/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,9 @@ Documentation: https://hypervel.org/docs/static-analysis
- Collections keep Laravel's covariant value type, so a `Collection<int, User>` is accepted where a `Collection<int, Model>` is expected. Upstream's stubs make it invariant. With bleeding edge, PHPStan does not widen a covariant value type it has already inferred, so a call such as `collect([1, 2, 3])->push(4)` is reported. See [Collection Types](https://hypervel.org/docs/static-analysis#collection-types).
- `now()`, `today()` and the `Date` facade return `CarbonInterface`, as declared, rather than the date class configured when analysis runs. Code that needs a specific class should convert the value, for example with `toImmutable()`.
- Configuration value types apply to reads through the `config()` helper, the `Config` facade and application-container calls such as `app('config')`. A repository received as a parameter or property, or created with `new Repository($items)`, keeps its declared return types. Upstream applies the application's configuration types to `get()` on any `Repository` instance. See [Configuration and Services](https://hypervel.org/docs/static-analysis#configuration-and-services).
- The `generalizeEnvReturnType` and `redisDriver` settings are omitted. An `env()` default does not decide the type of the value it reads, and Redis types always describe Hypervel's phpredis connection.
- Request input getters return the types the input can hold. A keyed `query()`, `post()` or `cookie()` value can be a string, number, boolean, array or `Stringable`, a keyed `server()` or `route()` value is `mixed`, and `header()` can return null even with a default. Whole query, post, cookie and file arrays have `array-key` keys, because a query string or JSON list body can use integer keys. Upstream's narrower types do not cover these values. `FormRequest::validated()` and `safe($keys)` return `array<array-key, mixed>` for the same reason.
- `Storage::disk()` and `FilesystemManager::disk()` are typed per disk from the booted configuration, such as `ClientPooledFilesystem` for a pooled S3 disk, instead of always `FilesystemAdapter`. Calls the `Storage` facade forwards to the default disk use that disk's methods. `Storage::cloud()` is not supported.
- Connection-bound Redis methods such as `client()` and `auth()` are reported when called through `Redis::connection()` or the manager, because the pooled proxy rejects them. Call them on a held connection from `Redis::withConnection()`.
- Connection-bound phpredis methods such as `client()` and `auth()` are reported when called through `Redis::connection()` or the manager, because the pooled proxy rejects them. Call them on a held connection from `Redis::withConnection()`.
- A builder method called through a relation returns the relation only when it is declared to return `static` or `$this`, as a relation returns itself when the builder returns itself. Upstream does so for any builder result. `static` is treated as the fluent convention, not proof of identity, so a custom `static` method that returns a clone is still typed as the relation; declare `$this` where identity matters. Builder's own `clone()`, `cloneWithout()`, `cloneWithoutBindings()` and `applyScopes()` return the builder.
- A `@method scopeActive()` tag does not add an `active()` scope, because Eloquent only calls scope methods that exist. Upstream adds one.
- The model visibility rule makes only a private scope or accessor protected automatically. A public one may be called directly from other files, so it is reported without a fix.
Expand Down
2 changes: 0 additions & 2 deletions src/phpstan/extension.neon
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@ parameters:
checkMissingTranslations: true
checkModelAppends: true
checkModelMethodVisibility: true
# generalizeEnvReturnType is omitted: env() declares its return type, which a default does not decide.
checkConfigTypes: true
checkAuthCallsWhenInRequestScope: false
parseModelCastsMethod: true
Expand Down Expand Up @@ -72,7 +71,6 @@ parameters:
noLegacyQueueProperties: true
noPipeSeparatedValidationRules: true
checkRedisConnectionBoundMethods: true
# redisDriver is omitted: Redis types always describe Hypervel's phpredis connection.
# Builder macros added by model traits' global scopes: trait => interface declaring the macros.
eloquentBuilderMacros:
Hypervel\Database\Eloquent\SoftDeletes: Hypervel\PHPStan\Methods\Macros\SoftDeletingMacros
Expand Down
3 changes: 1 addition & 2 deletions src/phpstan/src/Collectors/UsedEmailViewCollector.php
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,7 @@ public function processNode(Node $node, Scope $scope): ?array
return null;
}

// Upstream reads the first argument by position, which misses reordered named arguments. The
// mailable and mail message text() methods name it textView; the others name it view.
// The mailable and mail message text() methods name the view parameter textView; the others name it view.
$parameter = $method === 'text' && ! $isContent ? 'textView' : 'view';

return $this->getMailViews($node->getArg($parameter, 0)?->value, $scope);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,6 @@ public function processNode(Node $node, Scope $scope): ?array
return null;
}

// Upstream reads the second argument by position, which misses reordered named arguments.
return $this->getViewNames($node->getArg('view', 1)?->value, $scope);
}
}
1 change: 0 additions & 1 deletion src/phpstan/src/Collectors/UsedViewFacadeMakeCollector.php
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,6 @@ public function processNode(Node $node, Scope $scope): ?array
return null;
}

// Upstream reads the first argument by position, which misses reordered named arguments.
return $this->getViewNames($node->getArg('view', 0)?->value, $scope);
}
}
1 change: 0 additions & 1 deletion src/phpstan/src/Collectors/UsedViewFunctionCollector.php
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,6 @@ public function processNode(Node $node, Scope $scope): ?array
return null;
}

// Upstream reads the first argument by position, which misses reordered named arguments.
return $this->getViewNames($node->getArg('view', 0)?->value, $scope);
}
}
Loading