Download the PHP package camya/filament-import-inline without Composer

FilamentPHP Paste "Import Inline" Input - Directly paste, import, and validate machine readable data in form fields. (PHP / Laravel / Livewire)

This package for FilamentPHP adds the form component ImportInlineInput, which allows you to import machine-readable string data directly into your Filament form fields and validate its structure.

The plugin can automatically import data via the "on paste" event, which makes it a great tool for increasing productivity when editing content.

You can validate imported data using the standard Laravel Validation Rules.

The plugin comes with two handy importers, write and use your own importer.

Quick jump to the Table of contents.

You can watch a short demo video of the package below.

Below is an example of how to add the ImportInlineInput component to your FilamentPHP resource form. Read the full documentation here.

The JSON data for the example looks like this. Import/paste this data into you newly added component form field.

Implementation

The output looks like this: (Watch » Demo Video «)

Features

• Import and validate any type of machine readable string data.
• Direct import "on paste" event for a content editing productivity boost.
• Importers for JSON and CSV included.
• Validation of the structure using Laravel's validation rules.
• All texts customizable and translatable.
• Dark mode supported.
• Fully configurable, see all-available-parameters.

Support us

You can support my work with a donation.

Follow me on Twitter for DEV updates.

Support the package: Please give it a ⭐ Star on GitHub and on the official Filament plugin page, if it's helpful for you.

Table of contents

• Installation
• Usage & examples
  • Import and validate data - Step by Step guide
  • How to import & validate array data? Example: Tags, Category IDs
  • Importer
    • JSON importer
    • CSV importer (for Comma Separated Values)
    • Write your own importer
    • How to show a form error, if the import fails?
  • Laravel Validation Rules
  • All available parameters
• Changelog
• Contributing
• Credits

Installation

You can install the package via composer:

If needed, you can publish the config file with:

Translation

If needed, you can publish the translation files with:

You'll find the published translations here: trans/vendor/filament-import-inline

This package is translated to:

• English (en)

You translated it too? Share your translation on our GitHub discussions page.

Usage & examples

Import and validate data - step-by-step guide.

The user input text is sent to the component's afterStateUpdated() method and is contained in the $state parameter.

Explanation of the code below:

1. First set the validator for this component to a variable.
2. Import the incoming data. If necessary, you can raise a validation error using the $validator->setValidationError() method.
3. Add the imported data + validation rules to the $validator->validate($data, $rules, $messages) method.
4. After validation:
   • Validation fails: If validation fails, the template displays the validation errors.
   • Valid data: If valid, you can set any form field using Filament's $set('title', $validatedData['title']) closure method.
5. Use the $component->statusMessage() method of the component to set a success message below the form. (You can use Filament's notification system with Filament::notify('success', 'Data imported');)

The JSON data for the example looks like this. Import/paste this data into you newly added component form field.

Implementation

How to import & validate array data? Example: Tags, Category IDs

You can read the documentation for CSV import with csvString() here.

1. We import the CSV data with the method Import::csvString(). We set the min/max values per line to 3 to avoid wrong input using csvPerRow:. All parameters & return format explained here.
2. We pass only the first row of the result to the validation.
3. We set rules for the tags, but also for the tags.* to validate the array elements.
4. We set messages for tags and the tags.*.
5. Finally, we $set() the $dataValidated['tags'] array into the target form field in the filament resource. (Here it is the tags field).

The CSV data for the example looks like this. Import/paste this data into you newly added component form field.

Implementation

JSON importer - Import::jsonString()

This package provides a simple JSON importer whose main purpose is to set some necessary default values for the underlying PHP function. Additionally, it throws an ImportException in case of an error.

• input: String input

Input data

Use this method to import JSON data like:

Implementation

Output

This generates the following array structure:

Handle ImportException

If the import fails, one of the following ImportExceptions is thrown. Use the error message or code constants in your implementation.

Available exception codes:

The validation error message is "Invalid JSON data" for all exceptions ($e->getMessage()).

You can use the provided error code to distinguish the errors and set your own message. ($e->getCode())

CSV importer (for Comma Separated Values)

Import comma-separated values using the Import::csvString() method.

• Input:` String input
• csvPerRow: Specifies the number of values per row. If a row has more or less columns than specified, an exception is triggered.
• hasHeader: First row serves as header if true.
• separator: Separator between values. (v1, v2, v3)
• Enclosure: Enclosure character for values. ("v - 1", "v2", "v3")
• escape: Escape character.
• csvPerRowAutodetect: Automatic detection of the number of values per row (set from first row). If a following row has more or less columns, an exception is triggered.

Input data

Use this method to import comma separated CSV data as below, e.g. to populate tag IDs in repeat fields. Set hasHeader:

Implementation

Output

This generates the following array structure:

Implementation with "hasHeader"

If you set hasHeader: false, it parses all lines as rows.

Output with "hasHeader"

It generates the following array structure:

Handle ImportException

If the import fails, one of the following ImportExceptions is thrown. Use the error message or code constants in your implementation.

Available exception codes:

The validation error message is "Invalid JSON data" for all exceptions ($e->getMessage()).

You can use the provided error code to distinguish the errors and set your own message. ($e->getCode())

How to show a form error, if the import fails?

The build in importers throw an \Exception on failure. Add a try/catch block around them and use the $validator->setValidationError() method of the $component to set the form errors.

You can use the the same mechanism, if you write your own importer.

You can use a provided error code to distinguish the errors and set your own message. ($e->getCode())

Available error codes are:

JSON importer:

CSV importer:

Write your own importer

You can write your own importer. Feel free to share your importer with our GitHub community.

A good starting point is the Import and validate data - "Step by Step guide".

Laravel Validation Rules

You can use the official Laravel Validation Rules.

All available parameters

This plugin offers many parameters to configure it's behavior.

HINT: Read the "Step by Step guide" - How to import and validate data.

Changelog

Please see the release changelog for more information on what has changed recently.

Contributing

Want to implement a feature, fix a bug, or translate this package? Please see contributing for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Andreas Scheibel (camya) (Developer at camya.com / epicbundle.com)

FilamentPHP is based on Laravel, Livewire, AlpineJS, and TailwindCSS. (aka Tall Stack)

This package was inspired by a package by awcodes and the work of spatie. Thanks also to ralphjsmit for his blueprint that I used to implement the Filament Component Pest Tests.

License

The MIT License (MIT). Please see License File for more information.

Tooling - Development tools I use

• PHPStorm IDE (
  • Laravel Idea Plugin)
• Laravel with Valet and Lambo
• GitHub Desktop
• Translations with DeepL and LanguageTool
• Markdown TOC Generator
• SVG Icons by Heroicons
• iTerm2 Terminal
• Regex101 - Build, text, debug regex.
• Affinity Photo & Designer
• VSCode

Follow me on Twitter