PHPackages                             alingsas-kommun/data-importer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. alingsas-kommun/data-importer

ActiveWordpress-plugin[Utility & Helpers](/categories/utility)

alingsas-kommun/data-importer
=============================

1.0.3(2w ago)07GPL-2.0-or-laterPHP

Since May 12Pushed 2w agoCompare

[ Source](https://github.com/Alingsas-Kommun/data-importer)[ Packagist](https://packagist.org/packages/alingsas-kommun/data-importer)[ RSS](/packages/alingsas-kommun-data-importer/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (1)Versions (6)Used By (0)

Data Importer & Visualizer
==============================

[](#data-importer--visualizer)

Receive JSON data via REST API, store it in custom database tables, and render it anywhere on your site with PHP templates and shortcodes.

---

Introduction
------------

[](#introduction)

Data Importer & Visualizer is a WordPress plugin for teams that need to publish structured, frequently-updated data on a website without building a custom integration from scratch. You define one or more **data sources**, push JSON to a per-source REST endpoint, and display the records using flexible **PHP templates** rendered through a simple shortcode.

Typical use cases:

- Publishing real-time or scheduled data feeds (events, open data, listings, status boards).
- Bridging an external system (CRM, ERP, open-data API) with a WordPress front-end.
- Displaying tabular or card-based data that is maintained outside WordPress.

---

Requirements
------------

[](#requirements)

RequirementMinimumWordPress5.8PHP7.4MySQL / MariaDBany version supported by your WordPress installNo third-party services or external API subscriptions are required. All data is stored in the local WordPress database.

---

What's Possible
---------------

[](#whats-possible)

### Data sources

[](#data-sources)

- Create any number of independent data sources, each with its own slug, one or more API keys, and import settings.
- Choose an **import mode** per source:
    - `replace` — deletes all existing records then inserts the new payload (default).
    - `append` — adds incoming records without touching existing ones.
    - `upsert` — inserts or updates records matched by one or more key columns.
- Manually import JSON directly from the admin for testing.

### REST API import

[](#rest-api-import)

- Push JSON to a dedicated endpoint per source: `POST /wp-json/data-importer/v1/import/{source-slug}`
- Authenticate with a per-source API key sent in the `X-API-Key` header.
- Restrict imports with optional per-key IP or CIDR allowlists.
- Accepts both a single JSON object `{}` and arrays of objects `[{}, {}]`.
- Override the source's import mode for a single request with the `mode` query parameter (`replace`, `append`, or `upsert`).

### Templates

[](#templates)

- Build multiple PHP templates per source.
- Each template has a **wrapper before**, a **per-row template**, and a **wrapper after** section.
- Reference any field in the imported JSON directly as a PHP variable inside the template.
- Attach custom CSS/JS assets to a template (loaded only on pages that use the shortcode).
- Preview a template against live data directly inside the admin.

### Shortcode

[](#shortcode)

- Render any source/template combination anywhere in WordPress with `[data_importer]`.
- Filter records from the shortcode without changing the template: `where_key`, `where_op`, `where_value` with support for dot-notation for nested fields.
- Control pagination with `limit`, `offset`, and `order` attributes.
- Fetch a single record by database ID with `id`.

### Security & operations

[](#security--operations)

- API key authentication with hashed secrets stored at rest.
- Optional per-key IP/CIDR allowlists for import endpoints.
- Per-source rate limiting with configurable count/window.
- Payload size and max-record guardrails.
- Dedicated **Log** tab per source with three sections: **Import Log** (latest 20 imports), **Security Log** (latest 50 blocked/rejected attempts), and **Template Error Log** (latest 20 PHP template errors).
- **Safe mode** — disables all PHP template execution in the frontend with one click while you fix a broken template.
- All security controls are tunable via WordPress filter hooks without patching the plugin.

---

Installation
------------

[](#installation)

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate through **Plugins → Installed Plugins** in wp-admin.
3. Go to **Settings → Data Importer**.
4. Click **Add new source**, give it a name and choose an import mode.
5. Copy the **Endpoint URL** and the newly created **API Key** from the **API** tab immediately, since the plaintext key is only shown once.

---

Uninstallation
--------------

[](#uninstallation)

Deactivate and delete the plugin through **Plugins → Installed Plugins** in wp-admin. The uninstall routine will remove:

- All custom database tables created by the plugin.
- All plugin options (source configuration, import/security/template error logs, safe mode setting).
- All plugin transients (rate-limit counters, API key reveal tokens, manual import drafts).

> **Note:** Content generated by PHP templates — such as files or external records written by template code — is not tracked by the plugin and will not be removed automatically.

---

Testing
-------

[](#testing)

Run the integration suite from the plugin directory with:

```
composer test
```

For readable per-test output, use:

```
composer test:verbose
```

To list the discovered tests without running them, use:

```
composer test:list
```

The PHPUnit bootstrap loads the local WordPress install, then exercises the plugin's real REST, manual-import, shortcode, safe-mode, and logging flows.

---

Getting Started
---------------

[](#getting-started)

### 1. Create a data source

[](#1-create-a-data-source)

Go to **Settings → Data Importer → Add new source**. Fill in:

- **Name** — human-readable label.
- **Slug** — used in the REST endpoint URL (auto-generated from name).
- **Import mode** — `replace`, `append`, or `upsert`.

### 2. Push data

[](#2-push-data)

Send a `POST` request with a JSON body to the source endpoint.

```
curl -X POST https://example.com/wp-json/data-importer/v1/import/my-source \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '[
    { "id": 1, "title": "First item", "status": "active" },
    { "id": 2, "title": "Second item", "status": "draft" }
  ]'
```

A successful import returns:

```
{
  "inserted": 2,
  "updated": 0,
  "deleted": 0
}
```

### 3. Build a template

[](#3-build-a-template)

Open the source, go to the **Template** tab and create a new template. Example per-row markup:

```