Download the PHP package tobento/app-import-export without Composer

On this page you can find all versions of the php package tobento/app-import-export. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of tobento/app-import-export

Informations about the package app-import-export

App Import and Export

The app import and export provides the following features and uses the Read-Write Service for its readers, writers, and modifiers:

Zero-Config Bootstrapping

The Import & Export system works out-of-the-box with sensible defaults.

Simply register the Import Export Boot in your application, and the full import/export management UI becomes available immediately - no additional configuration required.

All built-in readers, writers and hooks are automatically discovered, listed in the UI, and ready to use. You can run imports, generate exports, inspect job results, and download generated files without writing any custom code.

You only need to customize configuration if you want to override defaults such as:

Table of Contents

Getting Started

Add the latest version of the app import-export project running this command.

Requirements

Highlights

Documentation

App

Check out the App Skeleton if you are using the skeleton.

You may also check out the App to learn more about the app in general.

Import Export Boot

The import/export boot does the following:

You may install the App Backend and boot the import export in the backend app.

Import Export Config

The configuration for the import-export is located in the file at the default App Skeleton config location. Here you can configure hooks and more.

Http Error Handler Boot

The Import & Export package provides an HTTP-level error handler that converts internal import/export exceptions into clean, user-friendly responses. This boot is optional but recommended when you want clean handling of reader, writer, and job-related errors during HTTP requests.

The example below shows how to register the error handler together with the main Import & Export boot:

The HttpErrorHandler boot registers handlers for exceptions raised by the Import & Export module, such as invalid readers or writers, missing storages, or job configuration errors. It ensures these issues are returned as structured HTTP responses instead of raw exceptions, providing clearer feedback and consistent error output across the application.

Features

Import Export Feature

This feature provides an import/export page where users can create and run import/export operations using the configured hooks.

Config

In the config file you can configure this feature:

ACL Permissions

When using the App Backend, you can assign the permissions in the roles or users page.

Workflow

An import or export operation follows a simple workflow:

  1. Create a new job
    The user selects a reader and writer registry and configures their options using the generated CRUD fields.

  2. Configure mappings, modifiers and hooks
    Depending on the registries used, the user may define field mappings, enable modifiers that transform the data during processing, and attach hooks that react to events such as successful, skipped, or failed rows.

  3. Run the job
    The job is executed in the background. The reader loads the data, the writer processes it, and any registered hooks are triggered.

  4. Review results
    After completion, the job displays its status, duration, processed row counts, and any messages generated during processing.
    If a file-storage writer is used, the resulting file can be downloaded from the Exported Files Feature page.
    Hooks may also store individual rows (successful, skipped, or failed), which can then be viewed, exported, or edited in the Job Results Feature, depending on the selected hook options.

This workflow applies to both import and export operations, depending on the selected reader and writer registries.

All import/export jobs are executed through the queue handler configured in the app config file.

To monitor queued jobs, view their status, or inspect failures and retries, you may also install the tobento-ch/app-job package, which provides a simple interface for observing queue activity.

Job Status Lifecycle

Import and export jobs move through a clear set of statuses that reflect their configuration state and processing progress. This ensures that jobs cannot be executed until they are fully configured, preventing issues such as incomplete mappings or invalid modifiers.

unconfigured
The job has been created but is not yet fully configured.
Mappings, modifiers, or hooks may still be missing or invalid.
Jobs in this state cannot be queued or executed.

ready
All required configuration is complete and valid.
Mappings, modifiers, and hooks are fully defined, and the job can safely be executed.
When the user presses Run, the job transitions from ready to queued.

queued
The job has been dispatched to the queue and is waiting to be processed by the queue worker.

processing
The queue worker is actively executing the job.
The reader loads data, the writer processes it, and all registered hooks are triggered.
The Job Lifecycle hook updates status, row counts, and timestamps during this phase.

completed
The job finished successfully.
All results, row counts, and messages are available for review.

failed
The job encountered an exception during processing.
Failure details and partial results (if any) can be reviewed by installing the tobento-ch/app-job package

Job Results Feature

This feature provides a job results page where users can review processed rows (successful, failed, skipped), edit values inline using the table editor, and re-add corrected rows for processing.
On the import/export page, users can define via hooks which rows should be stored. Stored rows can then be viewed, exported, edited, or downloaded within this feature.

Config

In the config file you can configure this feature:

ACL Permissions

The Job Results feature uses the following permission:

This permission allows a user to:

If the permission is missing, the user cannot open the Job Results page or interact with stored rows.

Exported Files Feature

This feature provides a page where users can view and download all generated export files in one place.

Users can:

Config

In the config file you can configure this feature:

ACL Permissions

If withAcl is set to false, this permission is automatically granted.

Warning
Disabling ACL removes all access restrictions. Do not use this setting in production.

Signed Media Features

If autoRegisterMediaFeatures is enabled (default), the feature automatically registers:

both with: supportedStorages: ['uploads-private']

These are required to securely display and download exported files stored in the uploads-private storage.

If you prefer to manage these features manually, set:

Signed URL Expiration

You can control how long the signed display/download URLs remain valid:

This value is passed to the controller and used when generating signed URLs.

Imported Files Feature

The Imported Files feature offers a central place where users can view, download, and manage all files uploaded by your file-upload readers. It is particularly helpful for file-driven import workflows (e.g., CSV uploads), as it provides complete transparency over the stored import files and allows users to keep the import directory clean and organized.

Users can:

Config

In the config file you can configure this feature:

ACL Permissions

If withAcl is set to false, this permission is automatically granted.

Warning
Disabling ACL removes all access restrictions. Do not use this setting in production.

Signed Media Features

If autoRegisterMediaFeatures is enabled (default), the feature automatically registers:

both with: supportedStorages: ['uploads-private']

These are required to securely display and download imported files stored in the uploads-private storage.

If you prefer to manage these features manually, set:

Signed URL Expiration

You can control how long the signed display/download URLs remain valid:

This value is passed to the controller and used when generating signed URLs.

Available Registries

Registries define the readers and writers available for import and export.
Each registry configures the CRUD fields used to edit its options, defines optional modifiers, and is responsible for creating the actual reader or writer instance used during processing.

Registries build on the concepts provided by the Read-Write Service, which supplies readers, writers, and modifiers.

Language configuration

Writers include built-in support for language handling. Each writer registry provides fields for selecting the language mode and the language to use during writing. By default, the available languages are resolved from the resources area when it exists, or otherwise from the default languages of the current application container, ensuring that writers respect the multilingual configuration of each environment. Registries may customize the available languages by overriding the resolveLanguages() method on a specific writer registry.

The following shows the default behavior used by all writer registries.

Customizing available languages

To provide a custom language set for a specific writer registry, override the resolveLanguages() method. The method must return a LanguagesInterface instance:

For more detail see: App Languages

CRUD Controller Writer Registry

This registry provides a writer that uses any CRUD Controller as a write target for import-export jobs. It validates and writes data through the controller's repository using the CrudWriteRepository, ensuring that controller field rules and write logic are respected.

Config

In the config file you can configure this registry:

Writer Behavior

The CRUD Controller Writer performs the following steps:

This writer uses the following underlying components:

UI Options

The following option is available when configuring this writer in the UI:

Field Description
Dry run (no write operations) When enabled, the writer performs all processing steps but does not execute any create or update operations. Useful for testing and validating the import without modifying any data.

Dot Notation for Column Mapping

The writer supports dot notation, allowing flat column names that use dot-notation to be converted into nested arrays during import.

Customizing the CRUD Controller Writer

You can extend CrudControllerWriter to:

Example: Adding a custom option, writer behavior, and modifiers

Registering the custom writer

CSV File Storage Writer Registry

This registry provides a writer that generates CSV files using a FileStorage resource.
It defines the CRUD fields for configuring the output file (filename, delimiter, enclosure, escape, BOM), applies column mapping and language modifiers, and creates the CSV writer that stores the generated file in the configured storage and folder.

Config

In the config file you can configure this registry:

Writer Behavior

The CSV File Storage Writer performs the following steps:

This writer uses two underlying components from the Read-Write service:

UI Options

The following options are available when configuring this writer in the UI:

Field Description
Filename Base filename (without extension). Must contain only letters, numbers, spaces, dots, underscores, and dashes.
Delimiter Character used to separate fields. Options: comma, semicolon, tab, pipe.
Enclosure Character used to wrap field values. Options: double quote, single quote.
Escape Character Character used to escape enclosure characters.
Write BOM Whether to write a UTF-8 BOM at the beginning of the file.
Language Fields Additional language‑related options provided by the system (e.g., locale selection), depending on your application setup.

CSV File Upload Reader Registry

This registry provides a reader that imports data from an uploaded CSV file.
It defines the CRUD fields for uploading and previewing the file, validates allowed extensions, and creates the CSV reader instance used during the processing workflow.

Config

In the config file you can configure this registry:

If you change the file storage, you must also adjust the imported file repository so it points to the correct storage:

Reader Behavior

The CSV File Upload Reader performs the following steps:

This reader uses the following underlying components:

UI Options

The following options are available when configuring this reader in the UI:

Field Description
File Source Uploads a CSV file. The field validates file extension (.csv), filename length, allowed characters, and maximum file size.
Delimiter (edit/update only) Character used to separate columns. Supports auto-detection, comma, semicolon, tab, pipe, or colon.
Enclosure (edit/update only) Character used to wrap values containing delimiters. Typically double-quote or single-quote.
Escape Character (edit/update only) Character used to escape enclosure characters inside values. Usually backslash or double-quote.

File Storage Reader Registry

This registry provides a reader that imports data from files stored in a configured FileStorage.
It lists available files in the storage (optionally including subfolders), filters them by allowed extensions, and creates the appropriate reader based on the selected file type (json, ndjson, or csv).

Config

In the config file you can configure this registry:

If you change the file storage, you must also adjust the imported file repository so it points to the correct storage:

Reader Behavior

The File Storage Reader performs the following steps:

This reader uses the following underlying components:

UI Options

The following option is available when configuring this reader in the UI:

Field Description
File Selects a file from the configured storage. Files are filtered by allowed extensions and optionally sorted by name or last modified timestamp.

HTML File Storage Writer Registry

This registry provides a writer that generates HTML files using a FileStorage resource.
It supports configurable templates, titles, descriptions, image rendering, and language-aware output.
The writer uses the HtmlResource writer from the Read-Write service and stores the generated HTML file in the configured storage and folder.

Config

In the config file you can configure this registry:

If you change the file storage, you must also adjust the exported file repository so it points to the correct storage:

Note on Image Rendering

This writer supports embedding images in the generated output.
To ensure images render correctly, you must configure the
Image Html Modifier and enable the
Media FileDisplay Feature so that image files stored in a file storage
can be resolved into public URLs.

Without this configuration, images referenced in HTML or PDF exports may
fail to load or appear as broken links.

Custom Templates via views()

This writer allows you to define reader-specific HTML templates.
This is useful when different readers (CSV, JSON, API, etc.) should produce HTML output using different layouts.

You can configure custom templates using the views() method:

When generating the HTML file, the writer resolves the template in this order:

  1. User-selected template (from the UI)
  2. Reader-specific template defined via views()
  3. Default template: import-export/html/export-table

This allows global defaults, per-reader templates, and per-job overrides.

Writer Behavior

The HTML File Storage Writer performs the following steps:

This writer uses the following underlying components:

UI Options

The following options are available when configuring this writer in the UI:

Field Description
Filename Base filename (without extension). Must contain only letters, numbers, spaces, dots, underscores, and dashes.
Template Selects the HTML layout. If none is selected, a reader‑specific template may be applied automatically.
Title Optional document title. Can be displayed in the template.
Show Title Whether the title should be rendered as a heading in the template.
Description Optional description text rendered in the template.
Render Images Enables image rendering inside the HTML output.
Max Image Width / Height Maximum dimensions for rendered images.
Language Fields Additional language-related options depending on your application setup.

JSON File Storage Writer Registry

This registry provides writers that store processed rows as JSON-based files, including standard JSON and NDJSON (newline-delimited).
It defines the CRUD fields for configuring the output file, validates allowed extensions, and creates the writer that saves the generated file to the configured storage and folder.

Config

In the config file you can configure this registry:

If you change the file storage, you must also adjust the exported file repository so it points to the correct storage:

Writer Behavior

The JSON File Storage Writer performs the following steps:

This writer uses the following underlying components:

UI Options

The following options are available when configuring this writer in the UI:

Field Description
Filename Base filename (without extension) for the generated file. Must contain only letters, numbers, spaces, dots, underscores, and dashes.
Output Format Selects the file extension/format. Supported formats: json and ndjson. Only shown if multiple formats are available.
Language Fields Additional language-related options provided by the system (e.g., locale selection), depending on your application setup.

JSON File Upload Reader Registry

This registry provides a reader that loads data from an uploaded JSON-based file, including standard JSON and NDJSON (newline-delimited JSON).
It defines the CRUD fields for uploading and previewing the file, validates allowed extensions, and creates the reader used during the processing workflow.

Config

In the config file you can configure this registry:

If you change the file storage, you must also adjust the imported file repository so it points to the correct storage:

Reader Behavior

The JSON File Upload Reader performs the following steps:

This reader uses the following underlying components:

UI Options

The following option is available when configuring this reader in the UI:

Field Description
File Source Uploads a JSON or NDJSON file. The field validates file extension (json, ndjson), filename length, allowed characters, and maximum file size.

PDF File Storage Writer Registry

This registry provides a writer that generates a PDF file from the processed data.
It defines the CRUD fields for configuring the output file and creates the writer that stores the generated PDF in the configured storage and folder.

Config

In the config file you can configure this registry:

If you change the file storage, you must also adjust the exported file repository so it points to the correct storage:

Note on Image Rendering

This writer supports embedding images in the generated output.
To ensure images render correctly, you must configure the
Image Html Modifier and enable the
Media FileDisplay Feature so that image files stored in a file storage
can be resolved into public URLs.

Without this configuration, images referenced in HTML or PDF exports may
fail to load or appear as broken links.

Custom Templates via views()

This writer allows you to define reader-specific PDF templates.
This is useful when different readers (CSV, JSON, API, etc.) should produce PDF output using different layouts.

You can configure custom templates using the views() method:

When generating the PDF file, the writer resolves the template in this order:

  1. User-selected template (from the UI)
  2. Reader-specific template defined via views()
  3. Default template: import-export/pdf/export-table

This allows global defaults, per-reader templates, and per-job overrides.

Writer Behavior

The PDF File Storage Writer performs the following steps:

This writer uses the following underlying components:

UI Options

The following options are available when configuring this writer in the UI:

Field Description
Title Optional title displayed at the top of the PDF.
Show title in PDF Whether the title should appear in the generated PDF.
Description Optional description text rendered in the template.
Render images in PDF Enables or disables rendering of images from the data.
Max Image Width / Height Maximum dimensions (in px) for rendered images.
Paper Paper size (A4, A3, A5).
Orientation Portrait or Landscape.
Margin (mm) Page margin in millimeters.
DPI Rendering resolution (72, 150, 300, 600).
Pagination Format Page numbering style (e.g., {PAGE}, {PAGE}/{PAGES}, etc.).
Compression PDF compression level (0, 3, 6, 9).
Password Protection Optional password required to open the PDF.

Repository Reader Registry

This registry provides a reader that loads data directly from a repository implementing
ReadRepositoryInterface. It is useful for exporting data that already exists inside the application domain (e.g., products, users, orders) without requiring file uploads.

The registry resolves the repository from the container, applies optional default filtering and sorting rules, converts entities to arrays if needed, and creates a RepositoryReader instance used during the import‑export pipeline.

Config

In the config file you can configure this registry:

Reader Behavior

The Repository Reader performs the following steps:

This reader uses the following underlying components:

UI Options

This registry does not define any UI fields.
Custom readers extending this class may add fields for filtering, sorting, or dynamic options.

Extensibility

Custom readers may extend this class to:

This makes RepositoryReader a flexible foundation for building domain‑specific readers.

Repository Writer Registry

This registry provides a writer that stores processed rows into a repository implementing
WriteRepositoryInterface. It is useful for import jobs that write directly into the application domain (e.g., creating or updating products, users, orders) without generating files.

The registry resolves the repository from the container, applies a ColumnMap modifier, supports dry-run mode, and creates a RepositoryWriter instance used during the import-export pipeline.

Config

In the config file you can configure this registry:

Writer Behavior

The Repository Writer performs the following steps:

This writer uses the following underlying components:

UI Options

The following option is available when configuring this writer in the UI:

Field Description
Dry run (no write operations) If enabled, the writer uses a NullRepository so no data is written. Useful for testing imports.

Extensibility

Custom writer registries may extend this class to:

This makes RepositoryWriter a flexible foundation for building domain-specific writers.

Storage Reader Registry

This registry provides a reader that loads data directly from a storage table using
StorageInterface. It is useful for reading structured data stored in a database‑like storage layer (e.g., SQL tables, JSON tables, flat storage tables) without requiring file uploads.

The registry resolves the storage service from the container, applies an optional query callable, supports preview mode, and creates a StorageReader instance used during the import‑export pipeline.

Config

In the config file you can configure this registry:

Reader Behavior

The Storage Reader performs the following steps:

This reader uses the following underlying components:

UI Options

This registry does not define any UI fields.
Custom readers extending this class may add fields for filtering, sorting, or dynamic options.

Extensibility

Custom readers may extend this class to:

This makes StorageReader a flexible foundation for building storage-driven readers.

Storage Writer Registry

This registry provides a writer that stores processed rows into a table of a StorageInterface implementation. It is useful for import jobs that write directly into storage tables (e.g., SQL tables, JSON tables, or other storage backends) without generating files.

The registry resolves the storage service from the container, applies a ColumnMap modifier, supports dry-run mode via an in-memory storage, and creates a StorageWriter instance used during the import-export pipeline.

Config

In the config file you can configure this registry:

Writer Behavior

The Storage Writer performs the following steps:

This writer uses the following underlying components:

UI Options

The following option is available when configuring this writer in the UI:

Field Description
Dry run (no write operations) If enabled, the writer uses an in-memory storage so no data is written. Useful for testing imports.

Extensibility

Custom writer registries may extend this class to:

This makes StorageWriter a flexible foundation for building storage-driven writers.

XML File Storage Writer Registry

This registry provides a writer that generates XML files using a FileStorage resource. It produces XML output via XmlResource and supports filename configuration, XML structure (root/row elements, optional wrapper), XML version, encoding, optional root attributes (namespaces), language modifiers, and column mapping.

The generated XML file is stored in the configured file storage and folder.

Config

In the config file you can configure this registry:

If you change the file storage, you must also adjust the exported file repository so it points to the correct storage:

UI Options

The following options are available when configuring this writer in the UI:

Field Description
Filename Base filename (without extension) for the generated XML file. Default: items.
Root Element Name of the root XML element. Default: items.
Row Element Name of the element used for each row. Default: item.
Row Wrapper (optional) Optional wrapper element around each row element.
Root Attributes Optional preset for XML namespaces (Atom, Google, Sitemap).
XML Version XML version (1.0 or 1.1). Default: 1.0.
Encoding XML encoding (UTF‑8, ISO‑8859‑1, UTF‑16). Default: UTF‑8.
Language fields Language mode and language selection (from SupportsWriterLanguages trait).

All element fields are validated to ensure valid XML element names.

Writer Behavior

The XML File Storage Writer performs the following steps:

This writer uses the following underlying components:

Available Hooks

Hooks allow you to react to events that occur during the import/export process.
They do not modify or validate data themselves; instead, they respond to lifecycle events and row-level outcomes reported by the processor.

The available hooks are defined in the config file and can be selected when editing an import/export job.
Each hook listens to one or more of the following events:

Hooks are typically used to store processed rows, update job metadata, log progress, or trigger side-effects.

Job Lifecycle Hook

This hook updates the job record during processing.
It is always active and cannot be selected or configured in the import/export job editor.
The queue handler automatically registers it for every job.

This hook writes job status and row statistics to the job repository at key points in the lifecycle:

The hook ensures that the job entity always reflects the current processing state and progress.
It also prevents editing import/export jobs while they are in the processing state, ensuring that running jobs cannot be modified until they have completed or failed.

Registration

The hook is registered internally by the queue job handler:

This means the hook is always included for every import/export job and does not need to be defined in the configuration.

Customization

If you need to customize how lifecycle events are handled, you may extend the queue handler and override the mandatoryHooks() method. For example, you can replace or extend the default lifecycle hook:

Next, register your customized queue handler in the config file:

This gives you full control over how jobs are processed, re-queued, and how lifecycle events are handled.

Notify Hook

The Notify Hook allows you to send notifications to a specific, fixed recipient such as a developer, support team, or monitoring system.
It is ideal for external alerts (mail, SMS, etc.) that should always go to the same destination, regardless of which user triggered the job.

This hook supports:

Config

Define the hook in your config file:

Additional Resources

To learn more about notifications, channels, recipients, and queueing, see:

Notify Current User Hook

The Notify Current User Hook sends notifications to the user who triggered the job.
It is ideal for providing real-time feedback during long-running import or export operations.

This hook supports:

Config

Define the hook in your config file:

Additional Resources

To learn more about notifications, channels, recipients, and queueing, see:

Notify Users Hook

The Notify Users Hook allows you to send notifications to all users matching specific roles.
It is ideal for notifying administrators, managers, operators, or any internal user group that should be informed about job activity.

With the notify users hook you send notifications to users using the User Repository, which is used to look up users by their roles before sending notifications.

This hook supports:

Config

Define the hook in your config file:

Additional Resources

To learn more about notifications, channels, recipients, and queueing, see:

Save Job Result Hook

This hook stores processed rows so they can be reviewed later in the Job Results Feature.
Depending on the selected mode, the hook saves either successful, skipped, or failed rows.
This is useful for inspecting problematic data, exporting results, or correcting and re-processing individual rows.

Config

In the config file you can configure this hook:

Additional Modifiers

In addition to the read/write modifiers, the Import & Export system provides extra modifiers that enhance formatting, localization, and media handling during the import-export pipeline.

Modifiers allow readers and writers to transform data before it is written to the final output. They extend the behavior of the core Read-Write components and integrate seamlessly with supported writers.

Column Mode Modifier

The ColumnModeModifier transforms specific columns during export according to a configured output mode.
This is useful when exporting structured or array-based fields into formats that require flat or string-based representations (CSV, HTML tables, XML attributes, etc.).

You define the transformation mode per column:

Each mode controls how the column value is flattened or serialized.

Supported Modes

1. json

Encodes the value as a JSON string.

Input

Output

Useful for

2. comma-separated

Converts an array into a comma-separated string.

Input

Output

Non-scalar values are JSON-encoded automatically.

Useful for

3. split-dot

Flattens a nested array using dot notation and prefixes keys with the column name.

Input

Output

Useful for

4. split-underlined

Same as split-dot, but uses underscore notation and normalizes the column name.

Input

Output

Useful for

When to Use ColumnModeModifier

Use this modifier when exporting:

It is commonly applied by:

These registries apply the modifier automatically based on their export format.

For custom export pipelines, you may add it manually.

Example Usage

This ensures each configured column is transformed into the appropriate export format.

Dot Notation To Array Modifier

The DotNotationToArrayModifier converts flat row attributes that use dot-notation (e.g. image.src.en) into nested arrays.
This is essential for import pipelines where CSV or flat data sources represent structured fields using dotted keys.

It transforms rows like:

into:

This modifier is typically used during import before writing data into repositories or storage tables that expect nested structures.

What It Does

It uses Arr::unflat() internally to rebuild the nested structure.

When to Use DotNotationToArrayModifier

Use this modifier when importing data that contains:

It is applied automatically by:

It is not applied automatically by generic writers such as:

For those registries, add it manually if your domain requires nested data.

Example Usage

This ensures that all dotted keys in the imported rows are expanded into nested arrays before being passed to the writer.

File Export Modifier

The File Export Modifier transforms file-related fields during export so that internal storage paths are converted into URLs, signed URLs, or base64-encoded data URIs. This ensures exported data contains usable file references instead of internal storage paths.

It supports:

Register it in your export pipeline:

Output Modes

1. raw

Returns the original storage path unchanged:

Useful for internal processing or debugging.

2. url

Converts file paths into public URLs or signed URLs depending on storage visibility.

Public storage example:

Private storage example (signed URL):

Signed URLs expire after the configured number of minutes.

3. base64

Embeds the file content directly in the export:

Useful for:

Supported Field Types

1. CRUD File Fields

Converted into a URL, signed URL, or base64 string.

2. Multilingual File Fields

Each locale is resolved independently.

3. Arrays of Files

Each file is resolved individually.

4. Arrays of Multilingual Files

Fully supported:

Each locale is resolved independently, producing:

When to Use FileExportModifier

Use this modifier when exporting:

The following registries apply the FileExportModifier automatically

Image Html Modifier

Some writers (such as HTML and PDF) support embedding images into the generated output. The Image Modifier resolves file-storage paths into public URLs so that images can be rendered correctly in browsers or PDF engines.

The Image Html Modifier enables:

Image resolution relies on the Media FileDisplay Feature, which exposes files from a storage as HTTP URLs.

Make sure the storage containing your images is registered in the media config file.

Writers that support image embedding reference this modifier automatically.

Supported Input Formats

The Image Modifier supports several image representations commonly produced by ImportExport readers and CRUD systems.

1. CRUD File Format

Multilingual

2. Array of CRUD Files

Multilingual

3. Plain Image Maps

Multilingual

Unsupported or Invalid Values

If the modifier cannot resolve the value (missing src, invalid URL, non-image),
the original value is returned unchanged so other modifiers can handle it.

Modes

Image Resizing

The modifier can automatically scale images to fit the configured maximum width and height:

Resizing Rules

Error Handling

The modifier safely handles invalid or incomplete data:

This ensures the modifier never breaks the export pipeline.

Language Modifier

The Language Modifier allows writers to output localized values based on the selected language. It is used by writers that support multi-language output (e.g., HTML, PDF, JSON, XML).

The Language Modifier enables:

This modifier is provided by the SupportsWriterLanguages trait and is available in writers that include language configuration fields.

Uploaded File Modifier

The Uploaded File Modifier converts import values into UploadedFile instances so that CRUD write operations can treat imported files exactly like files uploaded through forms.

This modifier enables:

It is automatically applied when you register it in your Import Bulk Action:

Only the fields explicitly listed in $withFileFields are processed.

Supported Input Formats

The modifier supports several common file representations used in import pipelines.

1. Remote URLs

The file is downloaded and wrapped in an UploadedFile instance.

2. Data URIs

The base64 payload is decoded and stored as an in‑memory uploaded file.

3. Raw Base64 Strings

If the string is valid base64, it is decoded and converted into an uploaded file.

Field Selection

Only fields explicitly defined in the Import Bulk Action are processed:

This makes the modifier predictable and prevents accidental conversion of unrelated fields.

Supported CRUD File Field Structures

The UploadedFileModifier automatically detects the internal structure of all CRUD file field types and converts their file values into UploadedFileInterface instances. Only the field name needs to be listed (e.g. image, gallery, meta.image); the modifier resolves the correct internal paths automatically.

FileSource Field

new Field\FileSource('image')

Import structure:

A plain string path or URL.
Converted directly into an UploadedFileInterface.

File Field

new Field\File('image')

Import structure:

The modifier converts only the src value.
Other keys (e.g. storage) are ignored during import.

Translatable File Field

new Field\File('image')->translatable()

Import structure:

Each locale value is converted individually.

Files Field

new Field\Files('image')

Import structure:

Each entry is processed and its src value converted.

Translatable Files Field

Import structure:

Each locale value is converted individually.

Multilingual Map (non-CRUD file field)

Useful for custom fields storing localized file paths.

Import structure:

Mapping CRUD File Fields to withFileFields()

CRUD Field Type Example What to put in withFileFields()
FileSource new Field\FileSource('image') ['image']
File new Field\File('image') ['image']
Files new Field\Files('images') ['images']
Multilingual map custom ['manual']

Error Handling

The modifier is designed to fail gracefully:

This ensures robustness even when dealing with inconsistent or user-generated import data.

Example Usage in ImportBulkAction

To enable file importing, you must declare which fields should be treated as file fields using withFileFields(). These fields will later be processed by the UploadedFileModifier.

Declaring withFileFields: ['image'] does not apply the modifier by itself.
It only tells the system which fields should be treated as file fields.

The actual modifier is applied inside the ImportBulkAction's createModifiers() method:

The UploadedFileModifier runs before the writer persists the entity, ensuring that all file fields are already converted into UploadedFileInterface instances and can be handled by CRUD write operations exactly like normal uploaded files.

CRUD Integration

You can also trigger imports and exports directly from CRUD index pages when actions are enabled for a specific controller.

Export Bulk Action

The Export Bulk Action adds an export workflow to any CRUD resource. It allows users to export either the selected rows or all filtered rows directly from the bulk-action menu. When triggered, a modal opens where the user can configure the writer, mapping, and hooks used for the export job, keeping the index page clean and uncluttered.

After the configuration is saved, a new export job is created and listed in the Import/Export feature. The job is then pushed to the queue and processed in the background, ensuring that even large exports do not block the UI or impact performance.

Key capabilities

Example

In your CRUD Controller add the ExportBulkAction in the configureActions method:

Note
The writer automatically applies the job's column mapping and any writer-specific modifiers (e.g., image rendering, language modifiers). The modifiers defined in the ExportBulkAction are merged with the writer's modifiers.

Check out the the Repository Writer for more details.

You may define multiple Export Bulk Actions for the same CRUD resource.
This is useful if you want different sets of modifiers or different predefined configurations.
Each action must have a unique name to avoid conflicts.

A list of available modifiers can be found at:
https://github.com/tobento-ch/service-read-write#modifiers

Example: Customizing Export Fields with modifyFields()

This example shows how to adjust the fields displayed in the export dialog. You can remove default fields that are not relevant for your export scenario and add your own fields to control export behavior.

Import Bulk Action

The Import Bulk Action adds a multi-step import workflow to any CRUD resource. It enables users to upload files such as CSV, JSON, or XML and import data directly into the system through a guided modal interface. The workflow is intentionally split into two steps to keep the index page clean while still allowing users to validate and configure the import before it is executed.

After the configuration is completed, a new import job is created and listed in the Import/Export feature. The job is then dispatched to the queue and processed in the background, ensuring that even large imports do not block the UI or impact performance.

Key capabilities

Example

In your CRUD Controller, add the ImportBulkAction in the configureActions method:

If the primary key field (for example id) is included in withFields and mapped during the import, the RepositoryWriter will attempt to update an existing entity.
If no entity with that ID exists, the update fails and the row is recorded as a failed import.
If the primary key is not mapped or the value is empty, a new entity is created instead.

This behavior is defined by the Repository Writer's logic:

See: https://github.com/tobento-ch/service-read-write#repository-writer

A list of available modifiers can be found at:
https://github.com/tobento-ch/service-read-write#modifiers

Example: Custom Writer

You may optionally create a custom writer to control how imported rows are written into your repository.
Using CrudWriteRepository is recommended because it automatically applies the fields's validation rules, write-actions, and behaviors (such as create/update logic, and policies).
Alternatively, you may directly use your controller's repository.
This gives you maximum flexibility but also requires implementing any additional logic yourself, since validation, behaviors, and write-actions are not applied automatically.

Check out the Crud Write Repository
and the Repository Writer for more details.

Example: Customizing Import Fields with modifyFields()

This example shows how to adjust the fields displayed in the import dialog. You can remove default fields that are not relevant for your import scenario and add your own fields to control import behavior.

Multi-step modal workflow

The Import Bulk Action uses a structured two-step modal process designed for clarity and safety:

  1. Step 1:
    The user selects a reader from a dropdown (for example, CsvFileUploadReader).
    Depending on the selected reader, the form updates live - for file-based readers an upload field appears, and the user must upload a file before continuing to the next step.

  2. Step 2:
    The user configures mapping, options, and hooks.
    Any validation issues keep the modal open so the user can correct them.

  3. Step 2 success:
    When the import configuration is valid, the job is created and queued.

This design keeps the index page clean while still supporting flexible and complex import workflows.

Customization

Multiple Import Bulk Actions may be defined for the same CRUD resource.
This is useful when different readers, mapping presets, or import behaviors are required.
Each action must have a unique name to avoid conflicts.

ACL Permission for Bulk Actions

Bulk actions such as Import/Export Feature. This ensures that only authorized users can trigger data-processing jobs from within a CRUD resource.

Available Permissions

The Import/Export Feature defines the following permissions:

For bulk actions, the most relevant permission is import-export.run, because bulk actions typically execute a job immediately.

Example: Protecting a Bulk Action

Inject the ACL service into your controller and conditionally register the bulk action only if the user has the required permission.

Why ACL for Bulk Actions?

Bulk actions often trigger powerful operations such as importing or exporting large amounts of data. These actions may create, update, or delete many records at once, or start long-running background jobs. Because of this, they should only be available to users who are explicitly allowed to perform such operations.

Using the ACL permissions from the Import/Export Feature ensures that:

By applying the same permission rules across both areas, the system stays predictable, secure, and easy to reason about.

Learn More

Adding Registries Via App

In addition to add registries via App on method to add registries only on demand:

Adding Hooks Via App

In addition to add hooks via App on method to add hooks only on demand:

Notifications for Background Jobs

Import/Export jobs and Reprocess jobs run asynchronously in the queue.
Notifications are handled through the configured notification hooks in the Import Export Config, which are available out of the box and can be selected by the user in the UI.

By default, the Import/Export package ships with several hooks, including:

Users can choose which hooks should run for each job directly in the UI.
Hooks marked with defaultSelected: true (such as notify.current-user) are pre-selected automatically.

To receive browser notifications, the user must have the notifications.browser ACL permission.
All other functionality is already set up and works out of the box.

You may set the permission manually (see ACL Service), or, if you are using the App Backend, you can assign this permission directly on the Roles or Users page.

Credits

All versions of app-import-export with dependencies

PHP Build Version
Package Version
Requires php Version >=8.4
tobento/app Version ^2.0
tobento/app-crud Version ^2.0
tobento/app-http Version ^2.0
tobento/app-file-storage Version ^2.0
tobento/app-migration Version ^2.0
tobento/app-language Version ^2.0
tobento/app-notifier Version ^2.0
tobento/app-pdf Version ^2.0
tobento/app-translation Version ^2.0
tobento/app-logging Version ^2.0
tobento/app-user Version ^2.0
tobento/app-view Version ^2.0
tobento/service-read-write Version ^2.0
tobento/service-repository Version ^2.0
tobento/service-repository-storage Version ^2.0
halaxa/json-machine Version ^1.2
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package tobento/app-import-export contains the following files

Loading the files please wait ...