baxtian/wp_importer

Class to be inherite to create importers

0.3.49 2026-07-21 22:50 UTC

Requires

• php: >=7.4
• baxtian/php-singleton: ^0.6.6
• phpoffice/phpspreadsheet: ^1.24
• psr/simple-cache: ^1

Requires (Dev)

• brain/monkey: ^2.6
• php-mock/php-mock: ^2.3
• phpunit/phpunit: ^9.5
• timber/timber: ^2.0

GPL-3.0-or-later

Published on Packagist.org on 2026-07-21 22:50 UTC

README

Base class for creating WordPress importers/exporters (CSV + XLSX). Appears under Tools → Import in the WordPress admin.

Usage

class MyImporter extends \Baxtian\WP_Importer
{
    use \Baxtian\SingletonTrait;

    protected function __construct()
    {
        $this->tipo   = 'product';        // singular slug
        $this->tipos  = 'products';       // plural slug
        $this->accion = 'import_products';// importer action slug

        add_action('init', [$this, 'init']);
        parent::__construct();
    }

    public function init(): void
    {
        $this->campos = [...];  // define here — translations are loaded
        $this->textos = [
            'import_button'       => __('Import Products', 'domain'),
            'import_file'         => __('Products file', 'domain'),
            'plural'              => __('products', 'domain'),
            'description'         => __('Import products from CSV or XLSX.', 'domain'),
            'mensaje_publicacion' => __('Created: %d, Updated: %d, Linked: %d', 'domain'),
            // ↑ Use commas as separators — JS splits by "," to build a bullet list
        ];
        // For custom DB tables, hook import/export here:
        add_filter('MrkImporter/import_data', [$this, 'handle_import'], 10, 4);
        add_filter('MrkImporter/export_data', [$this, 'handle_export'], 10, 4);
        parent::init();
    }
}

Important: define $campos and $textos inside init(), not the constructor — translations must be loaded first. Call parent::init() at the end of init().

Campo types

type	description
id	Post ID — used for matching on import
field	post_title or any direct post field
thumbnail	Featured image (URL on export, URL/path on import)
term	Taxonomy term (comma-separated on export)
postmeta	Generic postmeta value
postmeta_bool	Boolean postmeta — exports as 1/0
postmeta_textarea	Multiline postmeta
postmeta_date	Date postmeta (Y-m-d)
postmeta_datetime	Datetime postmeta (Y-m-d H:i:s)
p2p	Post-to-post relationship — requires 'p2p' key
ignore	Header/export mapping only — no-op on import

ignore

Declares a field that participates in rename_columns() (so the file header shows a friendly title) and in export, but is never written by the built-in import switch — it's a no-op on import.

Use it when a column's real value must be set through business logic that can't go through a raw update_post_meta() — for example, a value that has to pass through a domain object, trigger side effects, or be resolved by a third-party listener. Hook into MrkImporter/row_added (fired after all other fields of the row are processed) to write the value yourself:

$this->campos = [
    ['name' => 'id',         'type' => 'id'],
    ['name' => 'post_title', 'type' => 'field'],
    ['name' => 'price',      'type' => 'ignore', 'title' => __('Price', 'domain')],
];

add_action('MrkImporter/row_added', function ($post_id, $tipo, $line) {
    if ($tipo === 'product') {
        MyPricingService::set_price($post_id, $line['price']);
    }
}, 10, 3);

Hooks

Hook	Type	Args	When
MrkImporter/import_data	filter	(false, $tipo, $data, $campos)	Before importing — return ['nuevas'=>int, 'modificadas'=>int, 'terminos_nuevos'=>int] to replace built-in import; return false to fall through
MrkImporter/export_data	filter	($data, $tipo, $tipos, $campos)	Before writing the export file — return numeric array of rows (row 0 = header of campo names)
MrkImporter/row_added	action	($post_id, $tipo, $line)	After each imported row (built-in importer only)
MrkImporter/attach_image	action	($attach_id, $attach_data)	After each image is uploaded and processed

Export format

handle_export must return a numeric array where row 0 is the header (campo name values) and rows 1…N are data rows (numeric arrays aligned with the header). rename_columns() translates names → titles for the downloaded file.

$rows   = [['name', 'email', 'webinars']]; // header
$rows[] = ['John', '[e-mail]', 'Webinar 1'];
return $rows;

XLSX date cells

Cells formatted as dates in Excel are automatically converted to Y-m-d H:i:s strings. No manual serial-number handling needed in the importer.

Access control

WordPress restricts Tools → Import to users with the import capability. Grant it explicitly for custom roles:

add_role('my_role', 'My Role', ['read' => true, 'import' => true]);

Maintainers

Juan Sebastián Echeverry [e-mail]

Changelog

See CHANGELOG.md.