Changelog
Here is some information about the versions of IDML-Creator, when they were released and what changes there were.
5.7.0 2026-09-14
Tags
The IDML-Creator now supports the XML structure of an InDesign document. Tags connect the layout with XML data: every part of the document can carry a tag, so that InDesign can export the layout to XML or import XML data into the layout, while the tag ↔ style mapping keeps the formatting intact.
-
Custom tags are defined with the new
XMLTagclass. It is created and registered via theFactory:<?php use BitAndBlack\IdmlCreator\Content\Enum\Color; use BitAndBlack\IdmlCreator\Factory; $factory = new Factory(); $xmlTag = $factory->createXmlTag('Body'); $xmlTag->setTagColor(Color::ORANGE);Every tag gets a color, so it can be told apart from other tags in InDesign. The color is chosen randomly by default and can be set explicitly with
setTagColor(), using the new enumColor. The formerTagclass is deprecated.A default root tag is created automatically; every custom tag is placed below it in the XML structure.
-
A tag itself does not contain content. The new
XMLElementclass combines a tag with the tagged content:<?php use BitAndBlack\IdmlCreator\Content\Xml\XMLElement; $xmlElement = new XMLElement($xmlTag, $paragraphStyleRange);An
XMLElementaccepts paragraphs (ParagraphStyleRange), runs of text (CharacterStyleRange), tables and cells, otherXMLElements — so tags can be nested into a hierarchy — and other page elements like text frames.As the XML elements have to stay in the same order as the laid-out content, an
XMLElementcan be inserted directly into the content of aParagraphStyleRangeorCharacterStyleRange. That makes inline tags possible, for example to tag a single word inside a paragraph:<?php use BitAndBlack\IdmlCreator\Content\Story\CharacterStyleRange; use BitAndBlack\IdmlCreator\Content\Story\Text; new CharacterStyleRange( null, new XMLElement( $xmlTagInline, new CharacterStyleRange( $boldRed, new Text('IDML-Creator'), ), ), ); -
XML attributes, comments and processing instructions can be attached to an element:
XMLAttributeadds an attribute to an element. The attribute name is converted to camel case automatically; namespaced names such asaid:sourceare kept intact.XMLCommentadds a comment to the XML structure.XMLInstructionadds an XML processing instruction, for examplexml-stylesheet.
<?php use BitAndBlack\IdmlCreator\Content\Xml\XMLAttribute; use BitAndBlack\IdmlCreator\Content\Xml\XMLComment; use BitAndBlack\IdmlCreator\Content\Xml\XMLInstruction; $xmlElement ->addXmlAttribute(new XMLAttribute('Class', 'headline')) ->addXmlComment(new XMLComment('Generated by IDML-Creator')) ->addXmlInstruction(new XMLInstruction('xml-stylesheet', 'type="text/xsl" href="structure.xsl"')) ; -
Tagged tables and cells. Tables and cells do not have marker characters in the laid-out document, so their
XMLElementgets theNoTextMarkerattribute set totrueautomatically. -
Tagged page items. A
Rectangle,Oval,Polygon,GraphicLineorTextFramecan be associated with an XML element:$rectangle->setXmlElement($xmlElement); -
Automatic tag ↔ style mapping. Every tag that shares its name with a paragraph or character style is matched to it automatically. For each pair, an
XMLExportMapentry together with the matching import map is written to the optionalXML/Mapping.xmlfile, which is then referenced from thedesignmap.xml:$factory->createParagraphStyle('Body'); $factory->createXmlTag('Body'); -
The XML structure is written to
XML/BackingStory.xml. Neither theBackingStorynor theContainerneeds to be created manually anymore — theContentobject creates them automatically.
To see everything in context, have a look at the new example using-xml-tags, which demonstrates every situation in which tags can appear inside a document.
Added
-
Enums have been added for the attribute values of the content classes. They cover colors, gradients, content types, frame types, strokes, the page setup and the character, paragraph, object and table styles. The enums live in the namespace
\BitAndBlack\IdmlCreator\Content\Enum, for example:<?php use BitAndBlack\IdmlCreator\Content\Enum\Color\Model; use BitAndBlack\IdmlCreator\Content\Enum\Styles\Capitalization; $color->setModel(Model::PROCESS); $characterStyle->setCapitalization(Capitalization::SMALL_CAPS); -
New interface
\BitAndBlack\IdmlCreator\Content\InDesignVersionAwareInterfacethat is implemented by every object which carries the InDesign version it was built for. -
The documentation has been restructured and extended with new chapters about the enums, the quickstart, shapes, text frames, tables, styling text and styling objects.
-
The
Factoryhas been extended with a new methodcreateObjectStyle(), so object styles are created with the factory like every other style:<?php $objectStyle = $factory->createObjectStyle('Fancy Frame'); -
The
Factorynow offersgetDesignMap()andgetPreference(). As theDesignMapand thePreferenceare singleton objects in the document, the getters create them on first access and they no longer need to be set up manually. -
With the automatic creation of the
BackingStoryand theContainer, those two objects do not need to be set up manually anymore.
Changed
-
The setters for the newly added enum values accept both the enum and the former string value. Calling a setter with a string is deprecated, emits an
E_USER_DEPRECATEDnotice and will be removed in v6.0. Please use the matching enum instead. -
All examples now use the
Factoryand no longer set up theContent,Container,BackingStory,DesignMaporPreferencemanually. -
The documentation has been refactored to use the factory pattern consistently; the chapters about the
DesignMapand the tags document the new XML handling. -
Styles, colors, tints, mixed inks and the graphic XML entries are now sorted case-insensitively and alphabetically, so they appear in this order in InDesign. Accented characters like umlauts sort with their base letters ("Öffnungszeiten" appears between the "N" and the "P" instead of at the end), and numbers keep their natural order ("Body 2" appears before "Body 10"). Tints are placed directly after their base color, ordered from dark to light ("Red", "Red 80%", "Red 20%"). When the
intlextension is available, the locale-aware Unicode collation of ICU is used; otherwise, an equivalent pure-PHP comparison is used as a fallback. -
Generating IDML files is now considerably faster for documents with many objects, in particular tables. The property schema of a class — its property names and their annotations — is parsed only once per class and then cached instead of on every rendered object. In the test benchmark a story with 5000 table cells renders about 3.7x faster and 100 paragraph styles about 5.2x faster (see
benchmarks/performance.md).
Deprecated
-
The
Tagclass andFactory::createTag(). They have been replaced by theXMLTagclass andFactory::createXmlTag(). An existingTagcan simply be removed. -
Content::setTag(). UseContent::addXmlTag()with anXMLTaginstead. -
Factory::createPreference()andFactory::createDesignMap(). UseFactory::getPreference()andFactory::getDesignMap()instead. -
Factory::createBackingStory(). TheBackingStoryis created automatically. -
Setting the
BackingStoryor theContainermanually (Content::setBackingStory(),Content::setContainer()and the corresponding getters). Both objects are created automatically and the calls can be removed. -
The enum
Colorhas been moved toColor. -
The enums that describe styles have been moved into the common namespace
\BitAndBlack\IdmlCreator\Content\Enum\Styles. The classes of the former namespaces...\Enum\ObjectStyle,...\Enum\ParagraphStyleand...\Enum\CharacterStyleremain available as deprecated aliases and will be removed in v6.0. Please use the new location instead, for example\BitAndBlack\IdmlCreator\Content\Enum\Styles\Capitalizationinstead of\BitAndBlack\IdmlCreator\Content\Enum\ParagraphStyle\Capitalization.
Fixed
- Fixed abstract class
\BitAndBlack\IdmlCreator\Content\SplineItem\TransparencySetting\AbstractTransparencySettingnot being declared as abstract. Its setters now returnstaticinstead ofself. - Corrected the values of the enums
\BitAndBlack\IdmlCreator\Content\Enum\ObjectStyle\ArrowHeadAlignmentand\BitAndBlack\IdmlCreator\Content\Enum\ObjectStyle\EndJointhat contained stray quotes, and added missing values to several existing enums.
5.6.0 2026-02-11
Added
-
The IDML-Creator now supports placing InDesign documents (
.indd) like they were images. To make this possible, a new classInddhas been added:<?php use BitAndBlack\IdmlCreator\Content\Enum\Image\ImportedPageCrop; use BitAndBlack\IdmlCreator\Content\Enum\Unit; use BitAndBlack\IdmlCreator\Content\Image\Indd; use BitAndBlack\IdmlCreator\Content\Rectangle; $indd = new Indd() ->setSrc('myfile.indd') ->setPosition(0, 0) ->setSize(210, 297, Unit::MILLIMETERS) // Use the trim box of the InDesign document ->setImportedPageCrop(ImportedPageCrop::CROP_CONTENT) ; $rectangle = new Rectangle() ->setImage($indd) // Do more here... ;
5.5.0 2026-01-21
Added
-
The IDML-Creator can now handle the baseline grid. This can be done using the
Preferenceclass, for example<?php /** @var \BitAndBlack\IdmlCreator\Content\Preference $preference */ $preference // Start at 12.5mm from top ->setBaselineStart(12.5, Unit::MILLIMETERS) // Repeat grid every 12pt. ->setBaselineDivision(12.0) ; -
Optical margin and optical alignment can now be handled inside object styles:
<?php /** @var \BitAndBlack\IdmlCreator\Content\Style\ObjectStyle $objectStyle */ $objectStyle // Enable the optical margin alignment ->setOpticalMarginAlignment(true) // Set the optical margin size to 12pt. ->setOpticalMarginSize(12.0) ;
5.4.0 2025-10-28
Changed
- Set latest InDesign version to
2026(21.0). - Updated dependencies.
5.3.0 2025-10-08
Added
-
Added a lot more properties to the
CharacterStyleclass. -
Added transparent color
[None]to the color panel. It can be used now like any other color:<?php use BitAndBlack\IdmlCreator\Content\Color\NoneColor; use BitAndBlack\IdmlCreator\Content\Style\CharacterStyle; $characterStyle = new CharacterStyle(); $characterStyle->setFillColor(new NoneColor());
5.2.1 2025-05-23
Fixed
- Change type
inttofloatfor second parameter$bridgein methodsetColumns()in classTextFrame.
5.2.0 2025-05-23
Changed
- Improved table border color handling:
- Setters and getters have been added in class
TableStyle. - Values can be set to null in class
Table.
- Setters and getters have been added in class
5.1.0 2025-02-22
Changed
- Improved support for PHP 8.4.
5.0.0 2024-12-19
Changed
- PHP >=8.2 is now required.
- The namespace has been changed from
IDMLtoBitAndBlack\IdmlCreator. - Dependencies have been upgraded:
bitandblack/iccprofile^1.0is now required.bitandblack/idml-writer^2.0is now required.bitandblack/image-information^3.0is now required.bitandblack/qr-code^1.0is now required.
4.2.0 2024-10-14
Changed
- Updated dependencies.
- Set latest InDesign version to
2025(20.0).
4.1.1 2024-09-03
Fixed
- Fixed wrong handling of CIELab colors.
4.1.0 2024-07-30
Fixed
- Changed how grouped elements are getting placed. This fixes the possibly wrong positions of images inside Rectangles.
- Fixed wrong calculation of table rows, that could lead to wrong cell heights.
Added
- Add
Composerenum for Paragraph Styles. - Add table style properties
ColumnFillsPriority,StartColumnFillColorandEndColumnFillColor.
4.0.0 2024-02-08
Changed
- PHP >=8.1 is now required.
- All Enum Classes have been replaced by native Enums. This changes, how they need to be written. For example, instead of writing
PagePosition::RIGHT()you need to writePagePosition::RIGHTnow.
Added
-
A class
Factoryhas been added, that allows handling IDML components easier. Instead of initializing every object manually and also adding it to theContentobject manually, the Factory takes care of that.Before
<?php use IDML\Content; use Content\Style\ParagraphStyle; $content = new Content(); $paragraphStyle = new ParagraphStyle('Body Text'); $paragraphStyle ->setPointSize(12) ->setLineHeight(14.4) ; $content->add($paragraphStyle);After
<?php use IDML\Factory; $factory = new Factory(); $paragraphStyle = $factory->createParagraphStyle('Body Text') ->setPointSize(12) ->setLineHeight(14.4) ; -
The
Contentclass has been extended with a new methodadd(). The method is a shorthand for every otherset*oradd*method. So for example, instead of writing$content->addSpread($spread), you can write$content->add($spread)now.
3.10.0 2025-10-02
Changed
- Improved deprecation handling.
3.9.0 2024-10-14
Changed
- Updated dependencies.
- Set latest InDesign version to
2025(20.0).
3.8.2 2024-09-03
Fixed
- Fixed wrong handling of CIELab colors.
3.8.1 2024-07-30
Fixed
- Fixed wrong calculation of table rows, that could lead to wrong cell heights.
3.8.0 2024-06-27
Added
- Add
Composerenum for Paragraph Styles.
3.7.2 2024-06-13
Fixed
- Changed, how grouped elements are getting placed. This fixes the possibly wrong positions of images inside Rectangles.
3.7.1 2024-06-13
Added
- Add table style property
ColumnFillsPriority.
3.7.0 2024-06-13
Added
- Add table style properties
StartColumnFillColorandEndColumnFillColor.
3.6.0 2024-01-23
Changed
- Update dependencies.
3.5.0 2023-12-14
Changed
- The method
fitImageToFramehas been deprecated and was replaced byfillFrameWithImageProportional. - When setting an image the a
Rectangle,PolygonorOval, the methodsetSrcaccepts now a second parameter with an different file path. This allows to use other paths when creating an IDML document than in Adobe InDesign itself.
Added
- The method
fitImageToFrameProportionalhas been added to the classesRectangle,PolygonandOval.
3.4.1 2023-11-30
Fixed
- Fix handling of GraphicLines.
3.4.0 2023-11-23
Fixed
- Fix positioning of elements that could lead to wrong (ordered) element edges.
Changed
bitandblack/image-information>=2.0.1is now required.- The
Imageclass can now be initialized with a class that allows caching of image information. The easiest way is to use the library's default Cache class (which implements thesymfony/cachelibrary), but any other (custom) class implementing theCacheInterfacecan be used too. - Stories can be cloned now.
- Format styles as well as colors will be sorted alphabetically now.
Added
- The
Contentclass now provides the three default colorsPaper,BlackandRegistration. Their color model depends on theDocumentIntentsetting and isRGBorCMYK. The colors can be used by callingContent::getDefaultWhite(),Content::getDefaultBlack()andContent::getRegistrationColor().
3.3.0 2023-10-27
Added
-
Added properties to Table Styles:
StartRowFillColorStartColumnStrokeColorStartColumnFillCountEndRowFillColorEndColumnStrokeColorEndColumnFillCount
-
Added properties to TextFrames and Rectangles:
TopLeftCornerOptionTopRightCornerOptionTopLeftCornerRadiusTopRightCornerRadiusBottomLeftCornerOptionBottomRightCornerOptionBottomLeftCornerRadiusBottomRightCornerRadius
Fixed
- Fixed the wrong inheritance of Paragraph Styles in Cells.
- Fixed the wrong order of attributes when setting an inset space for a TextFrame.
- Fixed the wrong row count when adding headers and footers to Tables.
- Fixed calculation of anchor points that could cause inset spacing and border radius to get ignored.
3.2.0 2023-10-17
Changed
- Changed the handling of annotations in the
PropertyReaderclass, that brings a massive performance improvement.
Added
- Added the method
setCacheItemPoolin thePropertyReaderclass, so the annotation reading can be cached. This can improve the performance on large IDML documents.
3.1.0 2023-10-12
Changed
- Updated the
InDesignVersionenum to the latest InDesign version with the propertyINDESIGN_2024. IDML files will contain the new version number19.0when no other definition has been set. - Dependencies have been updated.
3.0.1 2023-10-06
Fixed
- Fix wrong namespace causing autoload problems.
3.0.0 2023-07-18
Changed
- PHP
>=8.0.2is now required. - Deprecations have been removed.
2.22.0 2024-01-23
Changed
- Update dependencies.
2.21.0 2023-07-07
Changed
- Changed some methods from
privatetopublicin classFontStyle.
2.20.0 2023-02-01
Fixed
- Added missing InDesign version property in
FontStyleandParagraphStyle. - Added missing null type in
ParagraphStyle. - Added base64 encoding to all image classes to improve file handling.
Changed
- Added methods
getPagesandgetPageCountto classAbstractSpread. - Added method
getElementsto classPage. - Added method
removeElementto classPage. - Added method
isSinglePageto classPreference. - IDML-Creator sets the preference attributes
PreserveLayoutWhenShufflingandAllowPageShuffleby its own depending on the page count and layout mode. This improves the handling of pages in InDesign.
2.19.0 2022-11-14
Changed
- Updated the
InDesignVersionenum to the latest InDesign version with the propertyINDESIGN_2023. IDML files will contain the new version number18.0when no other definition has been set.
2.18.1 2022-08-05
Fixed
- Fixed unlikable Layers.
2.18.0 2022-05-19
Added
- Gradients are now supported.
2.17.1 2022-02-11
Fixed
- Fixed version number for
bitandblack/qr-code.
2.17.0 2022-02-11
Fixed
- Replace character
/with character-in Story file names to prevent broken IDML files. - Improved rotation of elements.
- Improved deprecation handling in class
Content.
Changed
- Sort all kind of styles by their names.
Added
- Added class
MixedInkto handle mixed inks. - Added possibility to handle position in Polygons.
- Allow all types of page items as anchored objects.
- Added class
ParentSpreadin addition to the currentMasterSpreadto follow Adobes inclusive language. - Added method
fitFrameToContent.
2.16.0 2021-10-27
Changed
- Updated the
InDesignVersionenum to the latest InDesign version with the propertyINDESIGN_2022. IDML files will contain the new version number17.0when no other definition has been set.
2.15.0 2021-10-06
Added
HEXcolors can now be added too.Polygons are ready to use now.- Added methods
getCharacterStyleandsetCharacterStyletoCharacterStyleRange. - Added method
addContenttoCharacterStyleRangeto allow adding content to a later point. - Added method
addCharacterStyleRangetoParagraphStyleRangeto allow adding content to a later point. - The document indent can now be defined as
Web,PrintorMobile. It may be added when initializing aContentobject. This effects the color space and the default black which will be in CMYK or RGB now. Default isPrint.
Changed
- Changed deprecation messages, so they are using error level
E_USER_DEPRECATIONnow. Story::setContenthas been replaced withStory::addContent.- Page elements are not rendered until the page itself is rendered. This has been changed to allow page elements to be changed after they have been attached to a page.
- The annotation reader has been moved. This means that it's no longer needed to create a
Contentobject at first before using any other classes.
2.14.1 2021-01-13
Added
- Added missing values in class
CharacterStyle.
2.14.0 2020-11-30
Added
- Added the
Ovalclass to create circles and ovals.
Changed
- Added support for PHP 8.
2.13.0 2020-11-03
Added
- The
InDesignVersionEnum supports now version 2021. - Images can be embedded into an IDML document now. This can be done with the new
embedImage()method. It is available in the classesImage,EPS,PDFandSVG. - IDML-Creator can add meta information to an IDML now. The new class
MetaDataprovides some methods for adding authors and contact information. - When using an image without setting its source, the
ImageSrcNotSetExceptionwill be thrown now.
2.12.5 2020-10-14
Fixed
- Fixed wrong variable type.
2.12.4 2020-10-14
Fixed
- Added missing attribute
fillColorto classImage.
2.12.3 2020-10-13
Fixed
- Added missing getters.
2.12.2 2020-10-02
Fixed
- The library
bitandblack/composer-helperhas been updated, and it's usage too. This fixes some incompatibilities with different environments.
2.12.1 2020-10-01
Changed
- Updated library
bitandblack/image-informationto^1.5to makeext-imagickoptional.
2.12.0 2020-09-29
Fixed
- Fixed several bugs that could result in wrongly placed elements when rotating them.
Added
- Added the possibility to set the blend mode and all related settings for Rectangles, GraphicLines, Polygons and TextFrames. This works with the new
TransparencySettingclass. - Groups are now possible by using the new class
IDML\Content\Group. - PDFs can now be places using the
PDFclass. Crop mode and the page can be defined. - Added class
TransformAttributeOptionto improve the work with ObjectStyles.
Changed
- When adding elements to a Page, there's only one method for all elements:
addElement. - The
IDML\Content\CalculatorTraithas been replaced with theCalculatorclass. Spread::insertPage()has been replaced withSpread::addPage().Content::addDesignMap()has been replaced withContent::setDesignMap().Page::addTextFrame()has been replaced withPage::addElement().Page::addRectangle()has been replaced withPage::addElement().Page::addGraphicLine()has been replaced withPage::addElement().TextWrapPreference::setTextWrapOffset()has been replaced withTextWrapPreference::setTopOffset(),TextWrapPreference::setRightOffset(),TextWrapPreference::setBottomOffset()andTextWrapPreference::setLeftOffset().- It is no longer possible to add duplicates to the
IDML\Contentclass. - Enums are now final.
- The
QRCodeclass has some setters and getters now. - The style classes
CellStyle,CharacterStyle,ObjectStyle,ParagraphStyle, andTableStylehave a second parameter in their methodsetBasedOn(). If set to true, the inheritance will actively change to children's classes values. The inheritance can by manually triggered by calling the methodupdateInheritance(). Also, there's a new methodaddChild()what is the opposite ofsetBasedOn().
2.11.1 2020-02-24
Fixed
- Changes of the namespace in
bitandblack/idml-writercaused error messages. This has been fixed now.
2.11.0 2020-02-18
Added
-
GREP expressions can be added to Paragraph Styles now.
-
Added possibility to set a characters as subscript or superscript in two ways:
-
Instead of adding
new Text()into a CharacterStyleRangenew Subscript()ornew Superscript()can be used. -
CharacterStyles have
setPosition()now. Its values come from thePositionEnum.
-
2.10.0 2020-02-13
Added
-
A lot of Enums have been added.
-
Variable fonts can be used now. See
example/variable-fonts.phpfor a use case. -
SVGimages can be added now. -
The color of borders above and below a paragraph can be set.
-
Paragraphs can have borders and shadings now.
-
Paragraphs can have column rules now.
Changed
-
When a property has been set with the help of an Enum, its getter method will also return the Enum.
-
In class
Contentsome setters have been renamed to make their behaviour clearer:addDesignMaptosetDesignMapaddTagtosetTagaddBackingStorytosetBackingStoryaddContainertosetContaineraddPreferencetosetPreferencegetContainerstogetContainergetBackingStoriestogetBackingStory
-
composer.lockhas been removed. Also some dependencies have been updated.
2.9.4 2020-02-07
Changed
- In class
ParagraphStylethe propertystrikeThruis now from typebool.
Fixed
- A lot of properties and methods in class
ParagraphStylehadintvalues when they should befloat. This has been fixed now.
2.9.3 2019-12-09
Fixed
- Fixed wrong color value in QR codes when no foreground color was set.
2.9.2 2019-12-03
Fixed
- Fixed a bug that caused empty content elements.
2.9.1 2019-11-26
Fixed
-
Fixed handling of spanned or splitted columns and added
SpanColumnTypeto define the column type in paragraph styles. -
Fixed the handling of special characters.
2.9.0 2019-11-22
Added
-
Added a lot of classes for a better handling of special characters. They are all under the namespace
IDML\Content\SpecialChars:- AutoPageNumber
- EndNestedStyleHere
- IndentToHere
- NextPageNumber
- NonJoinerCharacter
- PreviousPageNumber
- RightIndentTab
- SectionMarker
- Tabulator.php
All of them can be used inside a
CharacterStyleRange, for example:<?php use IDML\Content\Story\Story; use IDML\Content\Story\ParagraphStyleRange; use IDML\Content\Story\CharacterStyleRange; use IDML\Content\SpecialChars\AutoPageNumber; $story = new Story(); $story->setContent( new ParagraphStyleRange( null, new CharacterStyleRange( null, new AutoPageNumber() ) ) );
Changed
-
Tabulators have been refactored and can be used with the new class
IDML\Content\Style\Tabulator.To make it clearer that multiple tabulators can be added to a paragraph style, the method
setTabulatorhas been renamed toaddTabulator.