Introduce PHPStan + improve DocBlocks

.gitattributes

@@ -11,3 +11,4 @@
 /tests export-ignore
 /CHANGELOG.md export-ignore
 /README.md export-ignore
+/phpstan.neon export-ignore

.github/workflows/facade.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.1
+          php-version: 8.2
           tools: composer:v2
           coverage: none
 

.github/workflows/static-analysis.yml

@@ -0,0 +1,14 @@
+name: static analysis
+
+on:
+  push:
+    branches:
+      - "2.x"
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    uses: laravel/.github/.github/workflows/static-analysis.yml@main

.github/workflows/tests.yml

@@ -37,6 +37,10 @@ jobs:
           tools: composer:v2
           coverage: none
 
+      - name: Remove PHPStan on PHP 8.1 and Laravel 10
+        run: composer remove --dev larastan/larastan
+        if: matrix.php == 8.1 || matrix.laravel == 10
+
       - name: Set Minimum PHP 8.1 Versions
         uses: nick-fields/retry@v3
         with:

composer.json

@@ -39,7 +39,8 @@
         "orchestra/testbench": "^8.0|^9.2|^10.0",
         "mockery/mockery": "^1.3.3",
         "phpunit/phpunit": "^10.4|^11.5",
-        "laravel/pint": "^1.16"
+        "laravel/pint": "^1.16",
+        "larastan/larastan": "^3.0"
     },
     "suggest": {
         "ext-pcntl": "Recommended when running the Inertia SSR server via the `inertia:start-ssr` artisan command."
@@ -53,4 +54,4 @@
     },
     "minimum-stability": "dev",
     "prefer-stable": true
-}
+}

phpstan.neon

@@ -0,0 +1,17 @@
+includes:
+	- vendor/larastan/larastan/extension.neon
+
+parameters:
+	level: 6
+	paths:
+		- src
+		- tests
+	excludePaths:
+		- src/Testing/Concerns
+	ignoreErrors:
+		- '#Call to an undefined method.*TestResponse.*::assertInertia\(\)#'
+		- '#Call to an undefined method.*TestResponse.*::inertiaPage\(\)#'
+		- '#Call to an undefined method.*TestResponse.*::inertiaProps\(\)#'
+		- '#Call to an undefined.*method.*Request::inertia\(\)#'
+		- '#Call to an undefined.*method.*Route::inertia\(\)#'
+

src/AlwaysProp.php

@@ -6,17 +6,32 @@
 
 class AlwaysProp
 {
-    /** @var mixed */
+    /**
+     * The property value.
+     *
+     * Always included in Inertia responses, bypassing partial reload filtering.
+     *
+     * @var mixed
+     */
     protected $value;
 
     /**
+     * Create a new always property instance. Always properties are included
+     * in every Inertia response, even during partial reloads when only
+     * specific props are requested.
+     *
      * @param  mixed  $value
      */
     public function __construct($value)
     {
         $this->value = $value;
     }
 
+    /**
+     * Resolve the property value.
+     *
+     * @return mixed
+     */
     public function __invoke()
     {
         return is_callable($this->value) ? App::call($this->value) : $this->value;

src/Commands/CheckSsr.php

@@ -25,7 +25,7 @@ class CheckSsr extends Command
     protected $description = 'Check the Inertia SSR server health status';
 
     /**
-     * check the SSR server via a Node process.
+     * Check the Inertia SSR server health status.
      */
     public function handle(Gateway $gateway): int
     {

src/Commands/CreateMiddleware.php

@@ -50,6 +50,8 @@ protected function getDefaultNamespace($rootNamespace): string
 
     /**
      * Get the console command arguments.
+     *
+     * @return array<int, array<int, mixed>>
      */
     protected function getArguments(): array
     {
@@ -60,6 +62,8 @@ protected function getArguments(): array
 
     /**
      * Get the console command options.
+     *
+     * @return array<int, array<int, mixed>>
      */
     protected function getOptions(): array
     {

src/Commands/StartSsr.php

@@ -26,7 +26,7 @@ class StartSsr extends Command
     protected $description = 'Start the Inertia SSR server';
 
     /**
-     * Start the SSR server via a Node process.
+     * Start the Inertia SSR server.
      */
     public function handle(): int
     {

src/Commands/StopSsr.php

@@ -23,7 +23,7 @@ class StopSsr extends Command
     protected $description = 'Stop the Inertia SSR server';
 
     /**
-     * Stop the SSR server.
+     * Stop the Inertia SSR server.
      */
     public function handle(): int
     {

src/Controller.php

@@ -6,6 +6,10 @@
 
 class Controller
 {
+    /**
+     * Handle the incoming request and render the Inertia response.
+     * Renders the component and props defined in the route defaults.
+     */
     public function __invoke(Request $request): Response
     {
         return Inertia::render(

src/DeferProp.php

@@ -8,21 +8,50 @@ class DeferProp implements IgnoreFirstLoad, Mergeable
 {
     use MergesProps;
 
+    /**
+     * The callback to resolve the property.
+     *
+     * Loaded asynchronously after initial page render for performance.
+     *
+     * @var callable
+     */
     protected $callback;
 
+    /**
+     * The defer group.
+     *
+     * @var string|null
+     */
     protected $group;
 
+    /**
+     * Create a new deferred property instance. Deferred properties are excluded
+     * from the initial page load and only evaluated when requested by the
+     * frontend, improving initial page performance.
+     */
     public function __construct(callable $callback, ?string $group = null)
     {
         $this->callback = $callback;
         $this->group = $group;
     }
 
+    /**
+     * Get the defer group for this property. Properties with the same group
+     * are loaded together in a single request, allowing for efficient
+     * batching of related deferred data.
+     *
+     * @return string|null
+     */
     public function group()
     {
         return $this->group;
     }
 
+    /**
+     * Resolve the property value.
+     *
+     * @return mixed
+     */
     public function __invoke()
     {
         return App::call($this->callback);

src/Directive.php

@@ -5,7 +5,9 @@
 class Directive
 {
     /**
-     * Compiles the "@inertia" directive.
+     * Compile the "@inertia" Blade directive. This directive renders the
+     * Inertia root element with the page data, handling both client-side
+     * rendering and SSR fallback scenarios.
      *
      * @param  string  $expression
      */
@@ -30,7 +32,9 @@ public static function compile($expression = ''): string
     }
 
     /**
-     * Compiles the "@inertiaHead" directive.
+     * Compile the "@inertiaHead" Blade directive. This directive renders the
+     * head content for SSR responses, including meta tags, title, and other
+     * head elements from the server-side render.
      *
      * @param  string  $expression
      */

src/EncryptHistoryMiddleware.php

@@ -4,14 +4,15 @@
 
 use Closure;
 use Illuminate\Http\Request;
-use Symfony\Component\HttpFoundation\Response;
 
 class EncryptHistoryMiddleware
 {
     /**
-     * Handle the incoming request.
+     * Handle the incoming request and enable history encryption. This middleware
+     * enables encryption of the browser history state, providing additional
+     * security for sensitive data in Inertia responses.
      *
-     * @return Response
+     * @return \Symfony\Component\HttpFoundation\Response
      */
     public function handle(Request $request, Closure $next)
     {

src/Inertia.php

@@ -6,7 +6,7 @@
 
 /**
  * @method static void setRootView(string $name)
- * @method static void share(string|array|\Illuminate\Contracts\Support\Arrayable $key, mixed $value = null)
+ * @method static void share(string|array<array-key, mixed>|\Illuminate\Contracts\Support\Arrayable<array-key, mixed>|\Inertia\ProvidesInertiaProperties $key, mixed $value = null)
  * @method static mixed getShared(string|null $key = null, mixed $default = null)
  * @method static void clearHistory()
  * @method static void encryptHistory($encrypt = true)
@@ -20,7 +20,7 @@
  * @method static \Inertia\AlwaysProp always(mixed $value)
  * @method static \Inertia\MergeProp merge(mixed $value)
  * @method static \Inertia\MergeProp deepMerge(mixed $value)
- * @method static \Inertia\Response render(string $component, array|\Illuminate\Contracts\Support\Arrayable $props = [])
+ * @method static \Inertia\Response render(string $component, array<array-key, mixed>|\Illuminate\Contracts\Support\Arrayable<array-key, mixed>|\Inertia\ProvidesInertiaProperties $props = [])
  * @method static \Symfony\Component\HttpFoundation\Response location(string|\Symfony\Component\HttpFoundation\RedirectResponse $url)
  * @method static void macro(string $name, object|callable $macro)
  * @method static void mixin(object $mixin, bool $replace = true)

src/LazyProp.php

@@ -4,15 +4,31 @@
 
 use Illuminate\Support\Facades\App;
 
+/**
+ * @deprecated Use OptionalProp instead for clearer semantics.
+ */
 class LazyProp implements IgnoreFirstLoad
 {
+    /**
+     * The callback to resolve the property.
+     *
+     * @var callable
+     */
     protected $callback;
 
+    /**
+     * Create a new lazy property instance.
+     */
     public function __construct(callable $callback)
     {
         $this->callback = $callback;
     }
 
+    /**
+     * Resolve the property value.
+     *
+     * @return mixed
+     */
     public function __invoke()
     {
         return App::call($this->callback);

src/MergeProp.php

@@ -8,10 +8,20 @@ class MergeProp implements Mergeable
 {
     use MergesProps;
 
-    /** @var mixed */
+    /**
+     * The property value.
+     *
+     * Merged with existing client-side data during partial reloads.
+     *
+     * @var mixed
+     */
     protected $value;
 
     /**
+     * Create a new merge property instance. Merge properties are combined
+     * with existing client-side data during partial reloads instead of
+     * completely replacing the property value.
+     *
      * @param  mixed  $value
      */
     public function __construct($value)
@@ -20,6 +30,11 @@ public function __construct($value)
         $this->merge = true;
     }
 
+    /**
+     * Resolve the property value.
+     *
+     * @return mixed
+     */
     public function __invoke()
     {
         return is_callable($this->value) ? App::call($this->value) : $this->value;

src/Mergeable.php

@@ -4,7 +4,31 @@
 
 interface Mergeable
 {
+    /**
+     * Mark the property for merging.
+     *
+     * @return static
+     */
     public function merge();
 
+    /**
+     * Determine if the property should be merged.
+     *
+     * @return bool
+     */
     public function shouldMerge();
+
+    /**
+     * Determine if the property should be deep merged.
+     *
+     * @return bool
+     */
+    public function shouldDeepMerge();
+
+    /**
+     * Get the properties to match on for merging.
+     *
+     * @return array<int, string>
+     */
+    public function matchesOn();
 }