Converter.php

<?php
/**
 * Wordpress XML to Kirby Markdown Content Converter CLI application.
 *
 * Reads the eXtended RSS file generated by WordPress export and transforms
 * page, post and attachment items into separate Kirby Markdown files.
 * Kirby content folders are based on WP page and post URLs.
 *
 * Does not handle:
 * - menubar structure (uses pages and posts URLs only)
 * - comments (xmlns:wfw)
 * - custom fields
 * - plugin data (galleries, forms,...)
 *
 * Works with XML export wxr_version 1.2
 *
 * @version 0.1.0 2020-01-21
 * @license WTFPL 2.0
 * @author  Rene Serradeil <serradeil@webmechanic.biz>
 */

namespace WebMechanic\Converter;

use DOMElement;
use Kirby\Cms\App;

use League\HTMLToMarkdown\HtmlConverter;

// grouped use declaration
use WebMechanic\Converter\Kirby\{Author,Page,Site};
use WebMechanic\Converter\Wordpress\{Attachment,Channel,Post,WXR};

/**
 * Manages a Wordpress XML to Kirby (v3) content conversion.
 * Delegates tasks to other 'Wordpres' and 'Kirby' classes doing the actual work.
 */
class Converter
{
	/** @var WXR $WXR access to WXR date */
	protected $WXR;

	/** @var Converter */
	public static $converter;

	/** @var Site $site the Kirby\Site `site.txt` with possible useful WordPress settings */
	protected $site;

	/** @var array  list of WebMechanic\Kirby\Pages from Wordpress\Post's */
	protected $pages = [];

	/** @var array  list of WebMechanic\Kirby\Author from Wordpress users/creators */
	protected $authors = [];

	/** @var array  list of WebMechanic\Kirby\Files (assets) from Wordpress\Attachment's */
	protected $files = [];

	/** @var array optional Transform objects */
	protected $transforms;

	/** @var App optional instance of a Kirby App from an active installation to gather some useful information */
	public static $kirby;

	/** @var HtmlConverter optional instance of `League\HTMLToMarkdown` form HTML to Markdown conversion */
	public static $HTML;

	/**
	 * title: Kirby Field used to store the Post's title.
	 * text: Kirby Field used to store the Post's content body.
	 *
	 * blueprints: a list of WP '_wp_page_template' mapped to Kirby blueprints
	 *
	 * write_html: whether to store the original item contents as .html files.
	 *
	 * resolve_urls: rules on how to handle and transform internal URLs
	 *
	 * ignore_fields: list of element names ignored during conversion.
	 *
	 * paths: rules for path handling and list with folders to use for output
	 *  - create: create (nested) content paths based on Item URL
	 *  - ordering: add (zero padded) numeric ordering to folder name
	 *                if original Page item has a `menu_order` > 0
	 *  - kirby: root folder (contains 'content' and 'site ' folders)
	 *  - content: alternative path for content output files
	 *  - assets: alternative path for images (WP uploads)
	 *  - site: alternative path for blueprint and account output files
	 *
	 * delegate: XML Element names handled by specific classes.
	 * 'nav_menu_item': The WP Mainmenu.
	 *        Only useful to recreate the same structure in Kirby.
	 *        Due to its complexity, this should be handled in a separate class,
	 *        i.e. Wordpress\Menu (not provided), rebuilding the node tree based
	 *        on the `wp:postmeta` information in all <item>s.
	 *
	 * discard_type: XML Element names ignored during conversion.
	 * 'display_type': unknown
	 * 'ngg_pictures', 'ngg_gallery', 'gal_display_source',
	 * 'slide', 'lightbox_library': gallery stuff
	 * 'wooframework': a fat staple in WP installations
	 *
	 * @see getOption()
	 */
	protected static $options = [
		'title' => 'title',
		'body' => 'text',

		// that's where the output goes. Kirby App config may override
		'paths' => [
			'create' => false,
			'ordering' => false,
			'kirby' => __DIR__ . '/migration/',
			'content' => null,
			'assets' => null,
			'site' => null,
		],

		/* a list of WP '_wp_page_template' mapped to Kirby blueprints, i.e.
			['contact' => 'default']
		 */
		'blueprints' => [],

		/* also write original `content` to separate .html backup */
		'write_html' => false,

		/** [WIP] Concept: how to handle self-referring URLs. @see Item::cleanUrl()
			This affects XML element values like <link> and HTML markup inserted into content such as <a>, <img>, <source>.
			- strip: true|false, remove protocol and domain from URLs (overrides www, https)
			- https: true|false, make URL https
			- www  : true|false, drop subdomain from URL */
		'resolve_urls' => [
			'link'          => '{"www":false, "https":true}',
			'base_site_url' => '{"strip":true}',
			'base_blog_url' => null,
		],

		// ignored elements on assign()
		'ignore_fields' => ['guid', 'comment_status', 'ping_status'],

		// delegated item types (need implementation classes)
		'delegate' => ['nav_menu_item' => null],

		// discarded plugin data 'post_type'
		'discard_type' => ['display_type','wooframework','ngg_pictures','ngg_gallery','gal_display_source','slide','lightbox_library'],

		// League\HTMLToMarkdown config options
		'html2md' => [
			'header_style' => 'atx',
			'hard_break' => false,
			],
	];

	protected $debug = false;

	/**
	 * Converter constructor.
	 * To get going call `$this->convert()` in your derived class.
	 *
	 * @param string $xml_path
	 */
	protected function __construct(string $xml_path)
	{
		$this->WXR       = new WXR($xml_path);
		self::$converter = $this;

		foreach (array_keys(static::$options['resolve_urls']) as $key) {
			if (is_string(static::$options['resolve_urls'][$key])) {
				static::$options['resolve_urls'][$key] = json_decode(static::$options['resolve_urls'][$key], false);
			}
		}

		$this->checkFolders();
	}

	/**
	 * Check and build output paths.
	 * Will use $options['paths']['kirby'] as the root for 'content', 'assets',
	 * and 'site'. Individual paths for each will be used if they exist.
	 * @throws \InvalidArgumentException, \RuntimeException
	 * @return void
	 */
	private function checkFolders() : void
	{
		static::$options['paths'] = (array)static::$options['paths'];
		if (is_dir(static::$options['paths']['kirby'])) {
			/* will also throw on Windows where "Kirby" and "kirby" are treated the same */
			if (is_file(static::$options['paths']['kirby'] .'/Content.php')) {
				throw new \InvalidArgumentException(
					'Cannot use program folder '. static::$options['paths']['kirby'] .' as output directory for Kirby files.');
			}
			if (!is_writable(static::$options['paths']['kirby'])) {
				throw new \RuntimeException(
					'Folder '. static::$options['paths']['kirby'] .' is not writeable.');
			}
		} else {
			if (true === static::$options['paths']['create']) {
				if (!mkdir($optionFolder = static::$options['paths']['kirby'], 0750, true) && !is_dir($optionFolder)) {
					throw new \RuntimeException(sprintf('Directory "%s" was not created', $optionFolder));
				}
			} else {
				throw new \InvalidArgumentException(
					'Please provide a valid, existing and writeable Kirby output directory: ' .
					PHP_EOL . static::$options['paths']['kirby'] . ' is not.'
				);
			}
		}

		foreach (['content', 'assets', 'site', 'site/accounts', 'site/blueprints', 'site/templates'] as $folder) {
			if ( empty(static::$options['paths'][$folder]) || !is_dir(static::$options['paths'][$folder]) )
			{
				static::$options['paths'][$folder] = static::$options['paths']['kirby'] . '/' . $folder;
			}

			if ( true === static::$options['paths']['create'] && !is_dir(static::$options['paths'][$folder]) )
			{
				if (!mkdir($optionFolder = static::$options['paths'][$folder], 0750, true) && !is_dir($optionFolder)) {
					throw new \RuntimeException(sprintf('Directory "%s" was not created', $optionFolder));
				}
			}

			static::$options['paths'][$folder] = realpath(static::$options['paths'][$folder]);
		}
	}

	/**
	 * @param string|null $key
	 * @param null        $default
	 * @return mixed|null
	 */
	public static function getOption(?string $key, $default = null)
	{
		if ($key === null) {
			return static::$options;
		}
		if (!isset(static::$options[$key])) {
			static::$options[$key] = $default;
		}
		return static::$options[$key];
	}

	public function __destruct()
	{
		// will close XMLReader
		unset($this->WXR);
	}

	/**
	 * Extend this method in your subclass to customise Kirby settings
	 * like target paths and Transform filters for some RSS values PRIOR
	 * calling this one with `parent::convert();`
	 *
	 * @return Converter
	 * @see Transform
	 */
	public function convert(): Converter
	{
		$this->WXR->parse($this);
		return $this;
	}

	public function getHtml(): HtmlConverter
	{
		$options =  static::getOption('html2md');
		return static::$HTML = static::$HTML ?? new HtmlConverter($options);
	}

	/**
	 * @param string $elementName an element name incl. its namespace / or a suitable key
	 *
	 * @return Transform
	 */
	public function getTransform(string $elementName): Transform
	{
		if (isset($this->transforms[$elementName])) {
			return $this->transforms[$elementName];
		}
		// empty to allow chaining w/o causing any harm.
		return new Transform();
	}

	/**
	 * @return App the Kirby App instance used for configuration
	 */
	public function getKirby(): App
	{
		return static::$kirby = static::$kirby ?? App::instance();
	}

	/**
	 * If you assign a valid Kirby App instance, settings will be pulled from
	 * your Kirby installation and output files will be written to its content
	 * and media folders (if possible).
	 *
	 * @param App $kirby a properly configured Kirby (CLI) instance
	 */
	public function setKirby(App $kirby): void
	{
		static::$kirby = $kirby;
	}

	/**
	 * @return Site
	 */
	public function getSite(): Site
	{
		return $this->site;
	}

	/**
	 * Creates basic Site information from the WXR `<channel>` element.
	 * To customize the Site object implement `setSiteOptions()` in your
	 * Converter subclass, e.g. to add blueprints or to change the default
	 * output filename. The method will be called before data from $channel
	 * is eventually assigned.
	 *
	 * @param Channel $channel
	 *
	 * @return Converter
	 * @see Site::assign()
	 * @uses setSiteOptions()
	 */
	public function setSite(Channel $channel): Converter
	{
		$this->site = new Site();

		$this->setSiteOptions(true);
		$this->site->assign($channel);
		$this->setSiteOptions(false);

		return $this;
	}

	/**
	 * Override in your subclass to customize some Site properties.
	 * Called within setSite().
	 *
	 * @param bool $pre_assign  state of assign() call
	 * @return Converter
	 * @see setSite()
	 */
	protected function setSiteOptions(bool $pre_assign): Converter	{ return $this;	}

	/**
	 * An array of Wordpress\Post's to be transformed into Kirby\Page's.
	 *
	 * @return array
	 */
	public function getPages(): array
	{
		return $this->pages;
	}

	/**
	 * Store a Wordpress\Post by its ID to be transformed into a Kirby\Page.
	 *
	 * @param Post $post
	 *
	 * @return Converter
	 */
	public function setPage(Post $post): Converter
	{
		$this->pages[$post->id] = (new Page())->assign($post);
		return $this;
	}

	/**
	 * An array of Kirby\Author objects for all converted Wordpress users
	 * ready to be converted (excl. passwords).
	 *
	 * @return array of Kirby\Author
	 */
	public function getAuthors(): array
	{
		return $this->authors;
	}

	/**
	 * The Author object of the Wordpress $username.
	 *
	 * @param string $username
	 * @return ?Author
	 */
	public function getAuthor(string $username): ?Author
	{
		return $this->authors[$username] ?? null;
	}

	/**
	 * Store a new Kirby\Author derived from a Wordpress user.
	 * The <dc:creator> of an <item> refers to the username, so this is used as the key.
	 *
	 * @param DOMElement $wp_author
	 * @return Converter
	 */
	public function setAuthor(DOMElement $wp_author): Converter
	{
		$author = new Author();
		$author->parseNode($wp_author);
		$this->authors[$author->getUsername()] = $author;
		return $this;
	}

	/**
	 * @return array
	 */
	public function getFiles(): array
	{
		return $this->files;
	}

	/**
	 * Store a Wordpress file Attachment/Upload to be transformed into
	 * a new Kirby\File or Kirby\Image.
	 *
	 * @param Attachment $file
	 *
	 * @return Converter
	 */
	public function setFile(Attachment $file): Converter
	{
		$this->files[$file->id] = $file;
		return $this;
	}

	/**
	 * Proxy to `setFile()`
	 *
	 * @param Attachment $image
	 * @return Converter
	 * @see setFile()
	 */
	public function setImage(Attachment $image): Converter
	{
		return $this->setFile($image);
	}

	/**
	 * If Converter $option 'ordering' is true, checks the `order` property of
	 * a Page and prefixes the filepath with the menu order taken from WP. This
	 * also enables a status of "listed" in Kirby, whereas folders not starting
	 * with a number are considered "drafts".
	 *
	 * @return Converter
	 * @todo implement for nested paths, apply order to inner item only.
	 */
	public function setOrdering(): Converter
	{
		$ordering = (bool) self::getOption('paths', ['ordering' => false])['ordering'];
		if (false === $ordering) {
			return $this;
		}

		# loop through $pages
		# for pages with $order > 0 collect their filepath
		# split path into folders, log nesting depth
		# apply $order to a new "virtual" folder name property; "NN_folder-name"
		# walk folder hierarchy
		# rename references of intermediate (middle) folders
		# repeat until all full paths are renamed
		# apply new names recursively

		return $this;
	}

	/**
	 * Cuts off a maximum of $maxlen characters using sentence boundaries (. : ;).
	 * The resulting sentence might be shorter than $maxlen characters.
	 *
	 * @param $text
	 * @param $maxlen
	 * @return string
	 */
	public function splitSentence($text, $maxlen): string
	{
		$sentenz = trim(strip_tags($text));
		if (preg_match_all('/[.;:?!]/', $sentenz, $pars, PREG_OFFSET_CAPTURE)) {
			$p = 0;
			foreach ($pars[0] as $p => $para) {
				if ($para[1] >= $maxlen) {
					break;
				}
			}
			$len     = ($p > 0) ? $pars[0][$p - 1][1] : $pars[0][$p][1];
			$char    = ($p > 0) ? $pars[0][$p - 1][0] : $pars[0][$p][0];
			if (strpos(' ;:', $char) >= 1) {
				$char = '.';
			}
			$sentenz = substr($sentenz, 0, $len) . $char;
		}
		return $sentenz;
	}

	public function __toString()
	{
		return (string) print_r([
			'pages' => array_keys($this->pages),
			'files' => array_keys($this->files),
			'authors' => array_keys($this->authors)
		], true);
	}
}