fix: Non-UTF8 column data docs & command notice (#20135)

danharrin · web-flow · commit 8212b2b0b6aa · 2026-07-10T22:51:35.000+01:00
diff --git a/docs/03-resources/01-overview.md b/docs/03-resources/01-overview.md
@@ -672,3 +672,15 @@ protected function mutateFormDataBeforeFill(array $data): array
 ```
 
 In this example, we remove the `is_admin` attribute from JavaScript, as it's not being used by the form.
+
+<Aside variant="warning">
+    Adding a column to `$hidden` is required, not just recommended, when it contains binary data that is not valid UTF-8, such as a `geometry`, `point`, or `blob` column. Since Filament exposes model attributes to JavaScript, these values are sent to the browser as part of the Livewire request, but they cannot be serialized to JSON. This causes the page to fail to load, often with a blank screen and no error in the Laravel log.
+
+    Adding such columns to [the `$hidden` array](https://laravel.com/docs/eloquent-serialization#hiding-attributes-from-json) on your model excludes them from its array and JSON representations, resolving the issue:
+
+    ```php
+    protected $hidden = ['location'];
+    ```
+
+    If you need to work with the value, expose it through an [accessor](https://laravel.com/docs/eloquent-mutators#defining-an-accessor) instead of the raw column.
+</Aside>
diff --git a/docs/12-components/02-form.md b/docs/12-components/02-form.md
@@ -160,6 +160,16 @@ public function mount(Post $post): void
 
 It's important that you use the `$this->form->fill()` method instead of assigning the data directly to the `$this->data` property. This is because the post's data needs to be internally transformed into a useful format before being stored.
 
+<Aside variant="warning">
+    The data you pass to `fill()` is exposed to JavaScript as part of the Livewire request. If your model has a column containing binary data that is not valid UTF-8, such as a `geometry`, `point`, or `blob` column, it cannot be serialized to JSON and the page will fail to load, often with a blank screen and no error in the Laravel log.
+
+    To resolve this, add the column to [the `$hidden` array](https://laravel.com/docs/eloquent-serialization#hiding-attributes-from-json) on your model, which excludes it from `attributesToArray()`:
+
+    ```php
+    protected $hidden = ['location'];
+    ```
+</Aside>
+
 ## Setting a form model
 
 Giving the `$form` access to a model is useful for a few reasons:
diff --git a/packages/actions/docs/05-edit.md b/packages/actions/docs/05-edit.md
@@ -2,6 +2,7 @@
 title: Edit action
 ---
 import AutoScreenshot from "@components/AutoScreenshot.astro"
+import Aside from "@components/Aside.astro"
 import UtilityInjection from "@components/UtilityInjection.astro"
 
 ## Introduction
@@ -40,6 +41,18 @@ EditAction::make()
 
 <UtilityInjection set="actions" version="4.x">As well as `$data`, the `mutateRecordDataUsing()` function can inject various utilities as parameters.</UtilityInjection>
 
+<Aside variant="warning">
+    Filament fills the form using the record's array representation, which is sent to the browser as part of the Livewire request. If your model has a column containing binary data that is not valid UTF-8, such as a `geometry`, `point`, or `blob` column, it cannot be serialized to JSON and the modal will fail to open, often with no error in the Laravel log.
+
+    To resolve this, add the column to [the `$hidden` array](https://laravel.com/docs/eloquent-serialization#hiding-attributes-from-json) on your model, which excludes it from the model's array and JSON representations:
+
+    ```php
+    protected $hidden = ['location'];
+    ```
+
+    This applies equally to the [View](view) and [Replicate](replicate) actions.
+</Aside>
+
 ## Customizing data before saving
 
 Sometimes, you may wish to modify form data before it is finally saved to the database. To do this, you may use the `mutateDataUsing()` method, which has access to the `$data` as an array, and returns the modified version:
diff --git a/packages/forms/src/Commands/FileGenerators/Concerns/CanGenerateModelForms.php b/packages/forms/src/Commands/FileGenerators/Concerns/CanGenerateModelForms.php
@@ -85,6 +85,12 @@ public function getFormComponents(?string $model = null, array $exceptColumns =
 
             $type = $this->parseColumnType($column);
 
+            if (! $this->canGenerateSchemaComponentForColumnType($type)) {
+                $this->recordSkippedColumn($model, $column);
+
+                continue;
+            }
+
             $componentData = [];
 
             $componentData['type'] = match (true) {
diff --git a/packages/forms/src/Commands/FileGenerators/FormSchemaClassGenerator.php b/packages/forms/src/Commands/FileGenerators/FormSchemaClassGenerator.php
@@ -6,11 +6,12 @@
 use Filament\Schemas\Schema;
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Illuminate\Database\Eloquent\Model;
 use Nette\PhpGenerator\ClassType;
 use Nette\PhpGenerator\Method;
 
-class FormSchemaClassGenerator extends ClassGenerator
+class FormSchemaClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateModelForms;
     use CanReadModelSchemas;
diff --git a/packages/forms/src/Commands/FileGenerators/LivewireFormComponentClassGenerator.php b/packages/forms/src/Commands/FileGenerators/LivewireFormComponentClassGenerator.php
@@ -10,6 +10,7 @@
 use Filament\Schemas\Schema;
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Illuminate\Contracts\View\View;
 use Illuminate\Database\Eloquent\Model;
 use Livewire\Component;
@@ -19,7 +20,7 @@
 use Nette\PhpGenerator\Property;
 use Nette\PhpGenerator\TraitUse;
 
-class LivewireFormComponentClassGenerator extends ClassGenerator
+class LivewireFormComponentClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateModelForms;
     use CanReadModelSchemas;
diff --git a/packages/infolists/src/Commands/FileGenerators/Concerns/CanGenerateModelInfolists.php b/packages/infolists/src/Commands/FileGenerators/Concerns/CanGenerateModelInfolists.php
@@ -55,6 +55,12 @@ public function getInfolistComponents(?string $model = null, array $exceptColumn
 
             $type = $this->parseColumnType($column);
 
+            if (! $this->canGenerateSchemaComponentForColumnType($type)) {
+                $this->recordSkippedColumn($model, $column);
+
+                continue;
+            }
+
             if (in_array($type['name'], [
                 'json',
             ])) {
diff --git a/packages/panels/src/Commands/FileGenerators/Resources/Pages/ResourceManageRelatedRecordsPageClassGenerator.php b/packages/panels/src/Commands/FileGenerators/Resources/Pages/ResourceManageRelatedRecordsPageClassGenerator.php
@@ -11,6 +11,7 @@
 use Filament\Schemas\Schema;
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Filament\Support\Icons\Heroicon;
 use Filament\Tables\Table;
 use Illuminate\Database\Eloquent\Model;
@@ -25,7 +26,7 @@
 use Nette\PhpGenerator\Method;
 use Nette\PhpGenerator\Property;
 
-class ResourceManageRelatedRecordsPageClassGenerator extends ClassGenerator
+class ResourceManageRelatedRecordsPageClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateResourceForms;
     use CanGenerateResourceProperty;
diff --git a/packages/panels/src/Commands/FileGenerators/Resources/RelationManagerClassGenerator.php b/packages/panels/src/Commands/FileGenerators/Resources/RelationManagerClassGenerator.php
@@ -10,6 +10,7 @@
 use Filament\Schemas\Schema;
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Filament\Tables\Table;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
@@ -23,7 +24,7 @@
 use Nette\PhpGenerator\Method;
 use Nette\PhpGenerator\Property;
 
-class RelationManagerClassGenerator extends ClassGenerator
+class RelationManagerClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateResourceForms;
     use CanGenerateResourceInfolists;
diff --git a/packages/panels/src/Commands/FileGenerators/Resources/ResourceClassGenerator.php b/packages/panels/src/Commands/FileGenerators/Resources/ResourceClassGenerator.php
@@ -12,6 +12,7 @@
 use Filament\Schemas\Schema;
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Filament\Support\Icons\Heroicon;
 use Filament\Tables\Table;
 use Illuminate\Database\Eloquent\Builder;
@@ -24,7 +25,7 @@
 use Nette\PhpGenerator\Method;
 use Nette\PhpGenerator\Property;
 
-class ResourceClassGenerator extends ClassGenerator
+class ResourceClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateResourceForms;
     use CanGenerateResourceInfolists;
diff --git a/packages/panels/src/Commands/FileGenerators/Resources/Schemas/ResourceFormSchemaClassGenerator.php b/packages/panels/src/Commands/FileGenerators/Resources/Schemas/ResourceFormSchemaClassGenerator.php
@@ -6,13 +6,14 @@
 use Filament\Schemas\Schema;
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Support\Arr;
 use Nette\PhpGenerator\ClassType;
 use Nette\PhpGenerator\Method;
 
-class ResourceFormSchemaClassGenerator extends ClassGenerator
+class ResourceFormSchemaClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateResourceForms;
     use CanReadModelSchemas;
diff --git a/packages/panels/src/Commands/FileGenerators/Resources/Schemas/ResourceInfolistSchemaClassGenerator.php b/packages/panels/src/Commands/FileGenerators/Resources/Schemas/ResourceInfolistSchemaClassGenerator.php
@@ -6,13 +6,14 @@
 use Filament\Schemas\Schema;
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Support\Arr;
 use Nette\PhpGenerator\ClassType;
 use Nette\PhpGenerator\Method;
 
-class ResourceInfolistSchemaClassGenerator extends ClassGenerator
+class ResourceInfolistSchemaClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateResourceInfolists;
     use CanReadModelSchemas;
diff --git a/packages/panels/src/Commands/FileGenerators/Resources/Schemas/ResourceTableClassGenerator.php b/packages/panels/src/Commands/FileGenerators/Resources/Schemas/ResourceTableClassGenerator.php
@@ -5,14 +5,15 @@
 use Filament\Commands\FileGenerators\Resources\Concerns\CanGenerateResourceTables;
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Filament\Tables\Table;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Support\Arr;
 use Nette\PhpGenerator\ClassType;
 use Nette\PhpGenerator\Method;
 
-class ResourceTableClassGenerator extends ClassGenerator
+class ResourceTableClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateResourceTables;
     use CanReadModelSchemas;
diff --git a/packages/support/src/Commands/Concerns/CanManipulateFiles.php b/packages/support/src/Commands/Concerns/CanManipulateFiles.php
@@ -3,6 +3,7 @@
 namespace Filament\Support\Commands\Concerns;
 
 use Filament\Support\Commands\FileGenerators\Contracts\FileGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Illuminate\Filesystem\Filesystem;
 use Illuminate\Support\Arr;
 use ReflectionClass;
@@ -11,6 +12,13 @@
 
 trait CanManipulateFiles
 {
+    /**
+     * Columns already reported to the user as skipped, to avoid warning about the same column more than once per command.
+     *
+     * @var array<string, string>
+     */
+    protected array $reportedSkippedColumns = [];
+
     /**
      * @param  string | array<string>  $paths
      */
@@ -73,7 +81,40 @@ protected function writeFile(string $path, string | FileGenerator $contents): vo
             pathinfo($path, PATHINFO_DIRNAME),
         );
 
-        $filesystem->put($path, (($contents instanceof FileGenerator) ? $contents->generate() : $contents));
+        if ($contents instanceof FileGenerator) {
+            $filesystem->put($path, $contents->generate());
+
+            if ($contents instanceof HasSkippedColumns) {
+                $this->reportSkippedColumns($contents->getSkippedColumns());
+            }
+
+            return;
+        }
+
+        $filesystem->put($path, $contents);
+    }
+
+    /**
+     * @param  array<string, string>  $skippedColumns  Column names, keyed by name with their database type as the value.
+     */
+    protected function reportSkippedColumns(array $skippedColumns): void
+    {
+        $newlySkippedColumns = array_diff_key($skippedColumns, $this->reportedSkippedColumns);
+
+        if (empty($newlySkippedColumns)) {
+            return;
+        }
+
+        $this->reportedSkippedColumns = [
+            ...$this->reportedSkippedColumns,
+            ...$newlySkippedColumns,
+        ];
+
+        $columnsList = collect($newlySkippedColumns)
+            ->map(fn (string $type, string $name): string => "{$name} ({$type})")
+            ->join(', ');
+
+        $this->components->warn("Binary columns were skipped, as they cannot be displayed in the browser: {$columnsList}. Add them to your model's `\$hidden` property to prevent errors.");
     }
 
     protected function getDefaultStubPath(): string
diff --git a/packages/support/src/Commands/Concerns/CanReadModelSchemas.php b/packages/support/src/Commands/Concerns/CanReadModelSchemas.php
@@ -143,6 +143,8 @@ protected function parseColumnType(array $column): array
             'timestamp', 'timestamptz' => 'timestamp',
             'text', 'tinytext', 'longtext', 'mediumtext', 'ntext' => 'text',
             'json', 'jsonb' => 'json',
+            'binary', 'varbinary', 'blob', 'tinyblob', 'mediumblob', 'longblob', 'bytea' => 'binary',
+            'geometry', 'geography', 'point', 'linestring', 'polygon', 'multipoint', 'multilinestring', 'multipolygon', 'geometrycollection', 'geomcollection' => 'binary',
             default => $column['type_name'],
         };
 
@@ -159,6 +161,45 @@ protected function parseColumnType(array $column): array
         return array_merge(['name' => $type], array_filter($values));
     }
 
+    /**
+     * Columns skipped while reading the model schema, keyed by column name with their database type as the value.
+     *
+     * @var array<string, string>
+     */
+    protected array $skippedColumns = [];
+
+    /**
+     * @param  array<string, mixed>  $type
+     */
+    protected function canGenerateSchemaComponentForColumnType(array $type): bool
+    {
+        // Binary and spatial columns (`blob`, `geometry`, `point`, etc.) hold data that
+        // is not valid UTF-8, so it cannot be serialized to JavaScript for a schema component.
+        return $type['name'] !== 'binary';
+    }
+
+    /**
+     * @param  class-string<Model>  $model
+     * @param  array<string, mixed>  $column
+     */
+    protected function recordSkippedColumn(string $model, array $column): void
+    {
+        // A column that is already `$hidden` is excluded from the model's array representation, so it cannot cause errors and does not need a warning.
+        if (in_array($column['name'], app($model)->getHidden(), strict: true)) {
+            return;
+        }
+
+        $this->skippedColumns[$column['name']] = $column['type_name'];
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function getSkippedColumns(): array
+    {
+        return $this->skippedColumns;
+    }
+
     /**
      * @param  array<string, mixed>  $column
      * @param  class-string<Model>  $model
diff --git a/packages/support/src/Commands/FileGenerators/Contracts/HasSkippedColumns.php b/packages/support/src/Commands/FileGenerators/Contracts/HasSkippedColumns.php
@@ -0,0 +1,11 @@
+<?php
+
+namespace Filament\Support\Commands\FileGenerators\Contracts;
+
+interface HasSkippedColumns
+{
+    /**
+     * @return array<string, string>
+     */
+    public function getSkippedColumns(): array;
+}
diff --git a/packages/tables/src/Commands/FileGenerators/Concerns/CanGenerateModelTables.php b/packages/tables/src/Commands/FileGenerators/Concerns/CanGenerateModelTables.php
@@ -74,6 +74,12 @@ public function getTableColumns(?string $model = null, array $exceptColumns = []
 
             $type = $this->parseColumnType($column);
 
+            if (! $this->canGenerateSchemaComponentForColumnType($type)) {
+                $this->recordSkippedColumn($model, $column);
+
+                continue;
+            }
+
             if (in_array($type['name'], [
                 'json',
                 'text',
diff --git a/packages/tables/src/Commands/FileGenerators/LivewireTableComponentClassGenerator.php b/packages/tables/src/Commands/FileGenerators/LivewireTableComponentClassGenerator.php
@@ -8,6 +8,7 @@
 use Filament\Schemas\Contracts\HasSchemas;
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Filament\Tables\Commands\FileGenerators\Concerns\CanGenerateModelTables;
 use Filament\Tables\Concerns\InteractsWithTable;
 use Filament\Tables\Contracts\HasTable;
@@ -21,7 +22,7 @@
 use Nette\PhpGenerator\Method;
 use Nette\PhpGenerator\TraitUse;
 
-class LivewireTableComponentClassGenerator extends ClassGenerator
+class LivewireTableComponentClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateModelTables;
     use CanReadModelSchemas;
diff --git a/packages/tables/src/Commands/FileGenerators/TableClassGenerator.php b/packages/tables/src/Commands/FileGenerators/TableClassGenerator.php
@@ -4,14 +4,15 @@
 
 use Filament\Support\Commands\Concerns\CanReadModelSchemas;
 use Filament\Support\Commands\FileGenerators\ClassGenerator;
+use Filament\Support\Commands\FileGenerators\Contracts\HasSkippedColumns;
 use Filament\Tables\Commands\FileGenerators\Concerns\CanGenerateModelTables;
 use Filament\Tables\Table;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Nette\PhpGenerator\ClassType;
 use Nette\PhpGenerator\Method;
 
-class TableClassGenerator extends ClassGenerator
+class TableClassGenerator extends ClassGenerator implements HasSkippedColumns
 {
     use CanGenerateModelTables;
     use CanReadModelSchemas;
diff --git a/packages/widgets/src/Commands/FileGenerators/TableWidgetClassGenerator.php b/packages/widgets/src/Commands/FileGenerators/TableWidgetClassGenerator.php
diff --git a/tests/database/migrations/0004_create_posts_table.php b/tests/database/migrations/0004_create_posts_table.php
diff --git a/tests/src/Fixtures/Models/PostWithHiddenLocation.php b/tests/src/Fixtures/Models/PostWithHiddenLocation.php
diff --git a/tests/src/Forms/Commands/MakeFormCommandTest.php b/tests/src/Forms/Commands/MakeFormCommandTest.php
diff --git a/tests/src/Panels/Commands/MakeResourceCommandTest.php b/tests/src/Panels/Commands/MakeResourceCommandTest.php
