README

FilamentPHP "粘贴导入" 输入 - 直接粘贴、导入和验证表单字段中的机器可读数据。（PHP / Laravel / Livewire）

此包为FilamentPHP添加了表单组件ImportInlineInput，允许您将机器可读字符串数据直接导入您的Filament表单字段，并验证其结构。

该插件可以自动通过“粘贴”事件导入数据，这使得它在编辑内容时大大提高了工作效率。

您可以使用标准的Laravel验证规则来验证导入的数据。

该插件包含两个实用的导入器，jsonString()和csvString()，但您也可以编写并使用自己的导入器。

快速跳转到目录。

下面是包的简短演示视频。

下面是一个将ImportInlineInput组件添加到您的FilamentPHP资源表单的示例。请在此处阅读完整文档。

示例的JSON数据如下。将此数据导入/粘贴到您新添加的组件表单字段中。

{
    "title": "The title of this post!",
    "slug": "title-of-post",
    "content": "Lorem ipsum."
}

实现

use Camya\Filament\Forms\Components\ImportInlineInput;
use Camya\Laravel\Importer\Facades\Import;

class PostResource extends Resource
{
    public static function form(Form $form): Form
    {
        return $form->schema([

            ImportInlineInput::make('Import')
                ->afterStateUpdated(
                    function ($state, Closure $set, ImportInlineInput $component): void {

                        $validator = $component->validator();

                        // Try to import JSON from given state
                        try {
                            $importedData = Import::jsonString($state);
                        } catch (\Exception $e) {
                            $validator->setValidationError($e->getMessage());
                        }

                        // Validate imported data.
                        $validatedData = $validator->validate(
                            data: $importedData,
                            rules: [
                                'title' => [
                                    'required',
                                ],
                                'slug' => [
                                    'required',
                                ],
                                'content' => [
                                    'required',
                                ],
                            ],
                            messages: [
                                'title.required' => 'title is required',
                                'slug.required' => 'slug is required',
                                'content.required' => 'content is required',
                            ]
                        );

                        // Set fields with validated data
                        $set('title', $validatedData['title']);
                        $set('slug', $validatedData['slug']);
                        $set('content', $validatedData['content']);

                        $component->statusMessage('Data imported <strong>successful!</strong>');

                    }
                )
                ->dataHelperHtml('Example JSON: {"title":"Lorem","slug":"ipsum","content":"Hello"}')
                ->dataHelperLink('https://www.camya.com/', 'Help')

    }
}

输出如下：（观看» 演示视频 «）

功能

导入和验证任何类型的机器可读字符串数据。
直接“粘贴”事件，提高内容编辑的生产效率。
包含JSON和CSV导入器。
使用Laravel验证规则验证结构。
所有文本均可自定义和翻译。
支持暗黑模式。
完全可配置，请参阅所有可用参数。

支持我们

您可以通过捐赠来支持我的工作。

关注Twitter以获取DEV更新。

支持该包：如果您觉得它有用，请在GitHub和官方Filament 插件页面给它一个⭐星星。

安装

您可以通过composer安装此包

composer require camya/filament-import-inline

如果需要，您可以使用以下命令发布配置文件：

php artisan vendor:publish --tag="filament-import-inline-config"

翻译

如果需要，您可以使用以下方式发布翻译文件：

php artisan vendor:publish --tag="filament-import-inline-translations"

您可以在以下位置找到发布的翻译：trans/vendor/filament-import-inline

本包已翻译为

英语 (en)

您也翻译了它吗？在我们的GitHub讨论页面上分享您的翻译。

用法和示例

导入和验证数据 - 步骤指南。

用户输入的文本被发送到组件的afterStateUpdated()方法，并包含在$state参数中。

以下代码的解释

首先将此组件的验证器设置为变量。
导入传入的数据。如果需要，您可以使用$validator->setValidationError()方法引发验证错误。
将导入的数据 + 验证规则添加到$validator->validate($data, $rules, $messages)方法。
验证后
- 验证失败：如果验证失败，模板将显示验证错误。
- 有效数据：如果有效，您可以使用Filament的$set('title', $validatedData['title'])闭包方法设置任何表单字段。
使用组件的$component->statusMessage()方法设置表单下的成功消息。（您可以使用Filament的通知系统，使用Filament::notify('success', 'Data imported');）

示例的JSON数据如下。将此数据导入/粘贴到您新添加的组件表单字段中。

{
    "title": "How to develop Filament plugins!"
}

实现

ImportInlineInput::make('Import')
    ->afterStateUpdated(
        function ($state, Closure $set, ImportInlineInput $component): void {

            // 1.
            $validator = $component->validator();

            // 2.
            try {
                $importedData = Import::jsonString($state);
            } catch (\Exception $e) {
                $validator->setValidationError($e->getMessage());
            }

            // 3.
            $validatedData = $validator->validate(
                data: $importedData,
                rules: [
                    'title' => [
                        'required',
                    ],
                ].
                messages: [
                    'title.required' => 'The title is required!',
                ],
            );

            // 4.
            $set('title', $validatedData['title']);
            $set('slug', $validatedData['slug']);
            $set('content', $validatedData['content']);

            // 5.
            $component->statusMessage('Data imported <strong>successful!</strong>');

        }
    )

如何导入和验证数组数据？示例：标签、分类ID

您可以在这里阅读有关使用csvString()进行CSV导入的文档。

我们使用Import::csvString()方法导入CSV数据。我们设置每行的最小/最大值范围为3，以避免使用csvPerRow:输入错误。所有参数和返回格式在此处解释。
我们只将结果的第一行传递给验证。
我们为tags设置规则，同时也为tags.*设置规则以验证数组元素。
我们为tags和tags.*设置消息。
最后，我们将$dataValidated['tags']数组设置为filament资源中的目标表单字段。（这里是指标签字段）。

示例的CSV数据如下。将此数据导入/粘贴到您新添加的组件表单字段中。

1,2,3

实现

ImportInlineInput::make('Tag Importer')
    ->afterStateUpdated(
        function ($state, Closure $set, ImportInlineInput $component): void {

            $validator = $component->validator();

            // 1.
            try {
                $dataInput = Import::csvString(
                    input: $state,
                    csvPerRow: 3,
                );
            } catch (\Exception $e) {
                $validator->setValidationError($e->getMessage());
            }

            $dataValidated = $validator->validate(
                data: [
                    // 2.
                    'tags' => $dataInput['rows'][0] ?? [],
                ],
                // 3
                rules: [
                    'tags' => [
                        'array',
                        'min:2',
                        'max:3',
                    ],
                    'tags.*' => [
                        'integer'
                    ],
                ],
                // 4.
                messages: [
                    'tags.min' => 'Min 2 tags',
                    'tags.max' => 'Max 3 tags',
                    'tags.*.integer' => 'Only add Tag IDs.'
                ],
            );

            // 5.
            $set('tags', $dataValidated['tags'] ?? []);

            $component->statusMessage('Tags imported <strong>successful!</strong>');

        }),

JSON导入器 - Import::jsonString()

本包提供了一个简单的JSON导入器，其主要目的是为底层PHP函数设置一些必要的默认值。此外，如果发生错误，它还会抛出ImportException。

\Camya\Laravel\Importer\Facades\Import::jsonString($input);

jsonString(
    string|null $input
): array

input: 字符串输入

输入数据

使用此方法导入类似以下JSON数据

{
    "title": "Lorem Ipsum",
    "slug": "lorem-ipsum",
    "tags": [1,2,3,4]
}

实现

$output = Import::jsonString(
    data: $input,
);

输出

这生成以下数组结构

[
    'title' => 'Lorem Ipsum',
    'slug' => 'lorem-ipsum',
    'tags' => [
        0 => 1,
        1 => 2,
        2 => 3,
        3 => 4,
    ],
]

处理ImportException

如果导入失败，会抛出以下ImportExceptions之一。在您的实现中使用错误消息或代码常量。

// Attempt to import JSON from the specified state.
try {
    $importedData = Import::jsonString($state);
} catch (\Exception $e) {
    $validator->setValidationError($e->getMessage());
}

可用的异常代码

所有异常的验证错误消息为"无效的JSON数据"（$e->getMessage()）。

您可以使用提供的错误代码来区分错误并设置自己的消息。（$e->getCode()）

// Incorrect input format, not a valid JSON string.
Import::JSON_ERROR_INVALID_INPUT

// Valid JSON, but result is not an array.
// If the input is an integer, it's technically a valid JSON object.
// We throw an exception nevertheless, because importing integers
// is not the use case of the importJSON method.
Import::JSON_ERROR_INVALID_RESULT

CSV导入器（用于逗号分隔值）

使用Import::csvString()方法导入逗号分隔值。

\Camya\Laravel\Importer\Facades\Import::csvString($input);

csvString(
    string|null $input,
    null|int $csvPerRow = null,
    bool $hasHeader = false,
    string $separator = ',',
    string $enclosure = '"',
    string $escape = '\\',
    bool $csvPerRowAutodetect = true,
): array

输入:` 字符串输入
csvPerRow: 指定每行的值数。如果一行比指定的列多或少，将触发异常。
hasHeader: 如果为真，则第一行作为标题。
separator: 值之间的分隔符。（v1, v2, v3）
Enclosure: 值的包装字符。（"v - 1", "v2", "v3"）
escape: 转义字符。
csvPerRowAutodetect: 自动检测每行的值数（从第一行设置）。如果以下行比指定的列多或少，将触发异常。

输入数据

使用此方法导入逗号分隔的CSV数据，例如在重复字段中填充标签ID。设置hasHeader

"Title", "TagID1", "TagID2", "CategoryID"
"Hello", "1", "2", "21"
"World", "5", "6", "65"

实现

$output = Import::csvString(
    data: $input,
    csvPerRow: 4,
    hasHeader: true,
);

输出

这生成以下数组结构

[
    'header' => [
        0 => 'Title',
        1 => 'TagID1',
        2 => 'TagID2',
        4 => 'CategoryID',
    ],
    'rows' => [
        [
            0 => 'Hello',
            1 => '1',
            2 => '2',
            4 => '21',
        ],
        [
            0 => 'World',
            1 => '5',
            2 => '6',
            4 => '65',
        ],
    ],
]

使用“hasHeader”的实现

如果设置hasHeader: false，则解析所有行作为行。

$output = Import::csvString(
    data: $input,
    csvPerRow: 4,
    hasHeader: false,
);

使用“hasHeader”的输出

它生成以下数组结构

[
    'header' => []
    'rows' => [
        [
            0 => 'Title',
            1 => 'TagID1',
            2 => 'TagID2',
            4 => 'CategoryID',
        ],
        [
            0 => 'Hello',
            1 => '1',
            2 => '2',
            4 => '21',
        ],
        [
            0 => 'World',
            1 => '5',
            2 => '6',
            4 => '65',
        ],
    ],
]

处理ImportException

如果导入失败，会抛出以下ImportExceptions之一。在您的实现中使用错误消息或代码常量。

// Attempt to import CSV from the specified state.
try {
    $importedData = Import::csvString($state);
} catch (\Exception $e) {
    $validator->setValidationError($e->getMessage());
}

可用的异常代码

所有异常的验证错误消息为"无效的JSON数据"（$e->getMessage()）。

您可以使用提供的错误代码来区分错误并设置自己的消息。（$e->getCode()）

// Empty input data
Import::CSV_ERROR_INVALID_INPUT

// Value count does not matche the value count set in $valuePerRow.
Import::CSV_ERROR_INVALID_CVS_PER_ROW_COUNT

如果导入失败，如何显示表单错误？

内置导入器在失败时抛出\Exception。在它们周围添加try/catch块，并使用$component的$validator->setValidationError()方法设置表单错误。

如果您编写自己的导入器，可以使用相同的机制。

try {
    $dataInput = Import::jsonString($importData);
} catch (\Exception $e) {
    $validator->setValidationError($e->getMessage());
}

您可以使用提供的错误代码来区分错误并设置自己的消息。（$e->getCode()）

可用的错误代码有

JSON导入器

// Incorrect input format, not a valid JSON string.
Import::JSON_ERROR_INVALID_INPUT

// Valid JSON, but result is not an array.
// If the input is an integer, it's technically a valid JSON object.
// We throw an exception nevertheless, because importing integers
// is not the use case of the importJSON method.
Import::JSON_ERROR_INVALID_RESULT

CSV导入器

// Empty input data
Import::CSV_ERROR_INVALID_INPUT

// Value count does not matche the value count set in $valuePerRow.
Import::CSV_ERROR_INVALID_CVS_PER_ROW_COUNT

编写您自己的导入器

您可以编写自己的导入器。请随意与我们的GitHub社区分享您的导入器。

一个良好的起点是导入和验证数据 - “逐步指南”。

Laravel验证规则

您可以使用官方的Laravel验证规则。

所有可用参数

此插件提供许多参数来配置其行为。

HINT：阅读“逐步指南” - 如何导入和验证数据。

ImportInlineInput::make('Import')

    // Import / Validate / Set your data here.
    ->afterStateUpdated(
        function ($state, Closure $set, ImportInlineInput $component): void {
            // ...
        }
    )

    // Sets the label above the form element.
    ->label('Inport Data')

    // Hide the label above the form element.
    ->disableLabel()

    // Help text for the detail panel.
    ->dataHelperHtml('Help <strong>text</strong>')

    // Link URL and Title for the detail panel.
    ->dataHelperLink('https://www.camya.com/', 'Specs')
    
    // Form field placeholder text for the "detail input" field.
    ->dataPlaceholder('Insert data here.')

    // Form field placeholder text for the "paste input" field.
    ->placeholder('Paste or insert valid data.')

    // Deactive listening for "on paste" on "paste input" field.
    ->insertOnPaste(false)

    // Default count of rows of the "paste input" field.
    ->dataInputRows(2)

变更日志

有关最近更改的更多信息，请参阅发布变更日志。

贡献

想实现一个功能、修复一个错误或翻译此包？请参阅贡献以获取详细信息。

安全漏洞

请查看我们的安全策略了解如何报告安全漏洞。

鸣谢

Andreas Scheibel (camya)（camya.com / epicbundle.com）的开发商

FilamentPHP基于Laravel、Livewire、AlpineJS和TailwindCSS。（又称Tall Stack）

此包受到了awcodes的一个包和spatie的工作的启发。还要感谢ralphjsmit，他提供了我用来实现Filament组件Pest Tests的蓝图。

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

工具 - 我使用的开发工具

PHPStorm IDE（
- Laravel Idea 插件）
Laravel与Valet和Lambo
GitHub Desktop
使用DeepL和LanguageTool进行翻译
Markdown TOC生成器
SVG 图标由 Heroicons 提供
iTerm2 终端
Regex101 - 构建、编辑、调试正则表达式。
Affinity Photo & Designer
VSCode

在 Twitter 上关注我

camya / filament-import-inline

维护者

详细信息

README

FilamentPHP "粘贴导入" 输入 - 直接粘贴、导入和验证表单字段中的机器可读数据。（PHP / Laravel / Livewire）

功能

支持我们

目录

安装

翻译

用法和示例

导入和验证数据 - 步骤指南。

如何导入和验证数组数据？示例：标签、分类ID

JSON导入器 - Import::jsonString()

CSV导入器（用于逗号分隔值）

如果导入失败，如何显示表单错误？

编写您自己的导入器

Laravel验证规则

所有可用参数

变更日志

贡献

安全漏洞

鸣谢

许可证

工具 - 我使用的开发工具