baxtian/wp_importer

Class to be inherite to create importers

0.3.36 2026-04-18 14:24 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

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

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

0.3.36

• Allow to read ells in date formats from XLSX.

0.3.35

• Allow to change the name of the file to export.
• Allow to change the name of the columns of the files.

0.3.33

• Add action MrkImporter/attach_image.

0.3.31

• Solve bug when WP_http return WP_Error

0.3.30

• Manage terms separated from importer

0.3.28

• Add filters MrkImporter/export_data and MrkImporter/import_data

0.3.26

• Initializate the media array when needed.

0.3.25

• Solve bug that duplicates posts with an '&' in the title.

0.3.24

• Use titles in p2p relationships

0.3.23

• Decode URL for titles in attachments

0.3.20

• Add public functions to import and export.

0.3.19

• Add type thumbnail.

0.3.18

• Add action MrkImporter/row_added.

0.3.17

• Import images.

0.3.16

• Import attachments.

0.3.15

• Allow to import p2p relationships.

0.3.14

• Allow import files in wp_content/uploads

0.3.13

• Options for media and attachment importer

0.3.12

• Timber 2.

0.3.10

• Resolve some bugs.

0.3.9

• Use direct filename for rendering.

0.3.8

• Use loader/paths filter only during rendering.

0.3.7

• Upgrade render to allow multiple merak instances

0.3.6

• Fixed some bugs

0.3.5

• Link styles

0.3.4

• Add link to import anther file

0.3.3

• Include option to save a copy of a filed into a postmeta

0.3.2

• Add jquery-ui if it hasn't been declared

0.3.1

• In case of using this class in multiple providers, allow Composer to set which file to use by default.

0.3.0

• Add testing.

0.2.1

• Refactoring.

0.1.14

• Import calculated cell, not formula.
• Add option to select export type in the import report.

0.1.13

• Fixing bugs

0.1.12

• Allow to use PHP8.0

0.1.11

• Check ID first.

0.1.10

• Improves, fixes and documentation.

0.1.9

• Add more width space to export dialog.

0.1.8

• Import and export excel files.

0.1.7

• Detect codification and Convert to UTF-8 if required.
• Include postmeta_date to type importer.
• Include postmeta_datetime to type importer.

0.1.6

• Manage empty terms on import.

0.1.5

• Include postmeta_textarea to type importer.

0.1.4

• Bug: importer generate errors when CSV have string with line breaks.

0.1.3

• Bug: templates directory not working on some servers.

0.1.2

• Update translations
• Bug: Always importing tha same post type.

0.1.1

• Bug: WP_Importer has been in use by WP.

0.1

• First stable release