Properly sideload child images and account for some common use cases when converting images

CHANGELOG.md

@@ -1,7 +1,24 @@
+
 # Changelog
 
 All notable changes to `WP Block Converter` will be documented in this file.
 
+## 1.5.0
+
+### Added
+
+- Add collection of attachments that are created during the conversion process.
+  Two methods now exist on the converter to help:
+  - `get_created_attachment_ids()` - Returns the attachment IDs that were created.
+  - `assign_parent_to_attachments()` - Assigns a parent post to all attachments.
+
+### Changed
+
+- Nested images are now properly sideloaded and converted to image blocks where
+  appropriate. For example, an image inside a figure tag will now be converted
+  to an image block. An image within a paragraph tag will be sideloaded but
+  won't be converted to an image block.
+
 ## 1.4.0
 
 - Drops support for PHP 8.0.

README.md

@@ -1,7 +1,6 @@
 # WP Block Converter
 
-[![Coding Standards](https://github.com/alleyinteractive/wp-block-converter/actions/workflows/coding-standards.yml/badge.svg)](https://github.com/alleyinteractive/wp-block-converter/actions/workflows/coding-standards.yml)
-[![Testing Suite](https://github.com/alleyinteractive/wp-block-converter/actions/workflows/unit-test.yml/badge.svg)](https://github.com/alleyinteractive/wp-block-converter/actions/workflows/unit-test.yml)
+[![Testing Suite](https://github.com/alleyinteractive/wp-block-converter/actions/workflows/all-pr-tests.yml/badge.svg)](https://github.com/alleyinteractive/wp-block-converter/actions/workflows/all-pr-tests.yml)
 
 Convert HTML into Gutenberg Blocks with PHP
 
@@ -13,9 +12,9 @@ You can install the package via Composer:
 composer require alleyinteractive/wp-block-converter
 ```
 
-This project is built to be used in a WordPress environment, so it is
-recommended to use this package in a WordPress plugin or theme. Using it in
-isolation is not supported at this time.
+This project is built to be used in a WordPress environment, so it is recommended to use this
+package in a WordPress plugin or theme. Using it in isolation is not supported at this time. This
+package does not use any NPM library such as `@wordpress/blocks` to convert HTML to blocks.
 
 ## Usage
 
@@ -26,7 +25,7 @@ use Alley\WP\Block_Converter\Block_Converter;
 
 $converter = new Block_Converter( '<p>Some HTML</p>' );
 
-$blocks = $converter->convert();
+$blocks = $converter->convert(); // Returns a string of converted blocks.
 ```
 
 ### Filtering the Blocks
@@ -61,6 +60,24 @@ add_filter( 'wp_block_converter_document_html', function( string $blocks, \DOMNo
 }, 10, 2 );
 ```
 
+### Attachment Parents
+
+When converting HTML to blocks, you may need to attach the images that were
+sideloaded to a post parent. After the HTML is converted to blocks, you can get
+the attachment IDs that were created or simply attach them to a post.
+
+```php
+$converter = new Block_Converter( '<p>Some HTML <img src="https://example.org/" /></p>' );
+$blocks = $converter->convert();
+
+// Get the attachment IDs that were created.
+$attachment_ids = $converter->get_created_attachment_ids();
+
+// Attach the images to a post.
+$parent_id = 123;
+$converter->assign_parent_to_attachments( $parent_id );
+```
+
 ### Extending the Converter with Macros
 
 You can extend the converter with macros to add custom tags that are not yet