Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/devgeniem/wp-geniem-importer
An object-oriented WordPress importer.
https://github.com/devgeniem/wp-geniem-importer
acf advanced-custom-fields importer php polylang wordpress wordpress-development wordpress-importer wordpress-plugin
Last synced: 6 days ago
JSON representation
An object-oriented WordPress importer.
- Host: GitHub
- URL: https://github.com/devgeniem/wp-geniem-importer
- Owner: devgeniem
- License: gpl-3.0
- Created: 2017-02-20T11:07:35.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2021-03-12T11:27:39.000Z (almost 4 years ago)
- Last Synced: 2024-04-09T22:09:39.186Z (9 months ago)
- Topics: acf, advanced-custom-fields, importer, php, polylang, wordpress, wordpress-development, wordpress-importer, wordpress-plugin
- Language: PHP
- Size: 143 KB
- Stars: 14
- Watchers: 29
- Forks: 2
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.MD
- License: LICENSE
Awesome Lists containing this project
README
# Enterprise WordPress Importer
Enterprise Importer is a WordPress importer plugin enabling importing WordPress data from external sources through an object-oriented functional API.
## Installation
Install the plugin with Composer by first adding the private repository and then requiring the package:
```
composer config repositories.devgeniem/wp-geniem-importer git [email protected]:devgeniem/wp-geniem-importer.git
composer require devgeniem/wp-geniem-importer
```
Then activate the plugin from the WordPress dashboard or with the WP-CLI.
```
wp plugin activate wp-geniem-importer
```
## Importing post objects
The plugin provides a functional API for importing various data types. You can think of the importer as an integration layer between your custom data source and the WordPress database. Your job is to format the data to meet the importer object specification. If you are lucky and your external data source can provide the data in the importer data format, your job is as simple as decoding the data into a PHP object and then passing it through the API.
An import is a two step process. First you must set the data for the importer `\Geniem\Importer\Post` object instance and then you call its save method to store the object data into the WordPress database.
An example of importing a single post can be found [here](docs/examples/example-post.php).
### \Geniem\Importer\Post - Methods
#### __construct() `public`
To start a new import process call the Post class constructor and pass a unique id for it. This creates a new instance of the class and identifies it. If this is an update, the WP post matching the id is fetched and the post object data is loaded as default values for the import. *To ensure the time values are updating they are unset from the post object at this point.*
##### Parameters
- `$gi_id` *(string) (Required)* An id uniquely identifies the object in the external data source.
##### Example usage
```php
$post = new \Geniem\Importer\Post( 'my_id_1234' );
```
#### set_data() `public`
The first step in the import process is to set the data for the importer. This funtion takes a full importer object as a parameter, validates all fields and sets the data into the corresponding class properties. To check if the data is valid after setting it, you can call the `get_errors()` which will return an array of occurred errors.
##### Parameters
- `$raw_post` *(object) (Required)* An object containing needed `\Geniem\Importer\Post` class properties.
- `post` *(object) (Required)* The basic [WP post](https://codex.wordpress.org/Class_Reference/WP_Post) object data as a `stdClass` object.
- `attachments` *(array) (Optional)* An array of attachment objects containing:
- `id` *(string) (Required)* An unique id identifying the object in the external data source.
- `src` *(string) (Required)* The source from which to upload the image into WordPress.
- *The plugin currently supports only image files!*
- `alt` *(string) (Optional)* The alt text for the image. This is saved into postmeta.
- `caption` *(string) (Optional)* The file caption text.
- `descrpition` *(string) (Optional)* The file description text.
- `meta` *(object) (Optional)* An object where all the keys correspond to meta keys and values correspond to meta values.
- `taxonomies` *(array) (Optional)* An array of taxonomy objects containing:
- `slug` *(string) (Required)* The taxonomy term slug.
- `name` *(string) (Required)* The taxonomy term display name.
- `taxonomy` *(string) (Required)* The taxonomy name, for example `category`.
- `acf` *(array) (Optional)* An array of Advanced Custom Fields data objects containing:
- `type` *(string) (Required)* The ACF field type ([types](https://www.advancedcustomfields.com/resources/#field-types)).
- `key` *(string) (Required)* The ACF field key. This must be the unique key defined for the field.
- `value` *(mixed) (Required)* The data value matching the field type specifications.
- `i18n` *(object) (Optional)* Custom localization information is stored in the property. It must contain an object with the following properties:
- `locale` *(string) (Required)* The language code string, for example `fi`.
- `master` *(string|object) (Required)* A `gi_id` value to be used to fetch a default language post or an array containing a `query_key` value. This is used to link the post as a translation.
#### Example usage
```php
$post->set_data( $my_raw_post_data );
```
##### Example data in JSON format
```json
{
"post": {
"post_title": "The title",
"post_content": "This is a new post and it is awesome!",
"post_excerpt": "This is a new post..."
},
"meta": {
"my_meta_key": "My meta value.",
"my_meta_key2": 1234
},
"attachments": [
{
"mime_type": "image/jpg",
"id": "123456",
"alt": "Alt text is stored in postmeta.",
"caption": "This is the post excerpt.",
"description": "This is the post content.",
"src": "http://upload-from-here.com/123456.jpg",
}
],
"taxonomies": [
{
"slug": "my-term",
"taxonomy": "post_tag"
}
],
}
```
#### save() `public`
Run this function after setting the data for the importer object. This function saves all set data into WordPress database. Before any data is stored into the database the current `Post` object is validated and it throws an `Geniem\Importer\Exception\PostException` if any errors have occurred. After all data is saved into the database the instance is validated again and any save errors throw the same expection. If no errors occurred, the WordPress post id is returned.
##### Parameters
- `$force_save` *(boolean) (Optional)* Set this to `true` skip validation and force saving. You can create custom validations through multiple hooks or by manually inspecting error with by getting them with the `get_errors()` function. Defaults to `false`.
## Plugin settings
The `\Geniem\Importer\Settings\` class is used to set and load all plugin settings. It uses the following settings that are overridable with corresponding constants.
### Available settings
- Setting key `id_prefix`, constant `GI_ID_PREFIX`, default value `'gi_id_'`.
- Setting key `attachment_prefix`, constant `GI_ATTACHMENT_PREFIX`, default value `'gi_attachment_'`.
- Setting key `log_errors`, constant `GI_LOG_ERRORS`, default value `false`.
- Setting key `transient_key`, constant `GI_TRANSIENT_KEY`, default value `'gi_'`.
- Setting key `transient_expiration`, constant `GI_TRANSIENT_EXPIRATION`, default value `HOUR_IN_SECOND`.
- Setting key `tmp_folder`, constant `GI_TMP_FOLDER`, default value `'/tmp/'`.
- Setting key `table_name`, constant `GI_TABLE_NAME`, default value `geniem_importer_log`.
- Setting key `log_status_ok`, constant `GI_LOG_STATUS_OK`, default value `'OK'`.
- Setting key `log_status_fail`, constant `GI_LOG_STATUS_FAIL`, default value `'FAIL'`.
### Accessing settings
Example usage:
```php
$gi_id_prefix = \Geniem\Importer\Settings::get( 'id_prefix' );
```
### Overriding settings
To override the transient expiration time set the following constant before the setting is used the first time.
```php
define( 'GI_TRANSIENT_EXPIRATION', MONTH_IN_SECONDS );
```
## Logging
The plugin creates a custom table into the WordPress database called `wp_geniem_importer_log`. This table holds log entries of all import actions and contains the following columns:
- `id` Log entry id.
- `gi_id` The importer object id.
- `post_id` The WordPress post id of the importer object. Stored only if the `save()` is run successfully.
- `import_date_gmt` A GMT timestamp of the import date in MySQL datetime format.
- `data` The importer object data containing all properties including errors.
- `status` The import status: `OK|FAIL`.
### Rollback
The log provides a rollback feature. If an import fails the importer tries to roll back the previous successful import. If no previous imports with the `OK` status are found, the imported object is set into `draft` state to prevent front-end users from accessing posts with malformed data.
To disable the rollback feature set the `GENIEM_IMPORTER_ROLLBACK_DISABLE` constant with a value of `true`.
## Changelog
[CHANGELOG.md](CHANGELOG.md)
## Contributors
- [Geniem](https://github.com/devgeniem)
- [Ville Siltala](https://github.com/villesiltala)
- [Timi-Artturi Mäkelä](https://github.com/Liblastic)