8000 QuipXml 1.0: retire xpath(), add QuipXmlElementInterface, round out the iterator by stackpr · Pull Request #11 · brainite/quipxml · GitHub
[go: up one dir, main page]

Skip to content

QuipXml 1.0: retire xpath(), add QuipXmlElementInterface, round out the iterator - #11

Merged
stackpr merged 12 commits into
masterfrom
feat/hive-41897-v1
Oct 1, 2026
Merged

stackpr merged 12 commits into
masterfrom
feat/hive-41897-v1

Conversation

@stackpr
@stackpr stackpr commented Oct 1, 2026 •
Copy link
Copy Markdown
Collaborator

Summary

Retirem 8000 ent (PHP 9 readiness)

  • xpath(), xparent() and xprev() on both QuipXmlElement and QuipXmlElementIterator now always throw a \RuntimeException naming the replacement: qxpath(), qxparent() or qxprev().
  • They declare : never, so overriding SimpleXMLElement::xpath() is now legal PHP and #[\ReturnTypeWillChange] is gone.

QuipXmlElementInterface

  • New interface implemented by both classes. It holds only the methods they share, all with native types, and extends \Countable, \Stringable and \Traversable.
  • Query methods return QuipXmlElement|QuipXmlElementIterator. The iterator carries @mixin QuipXmlElement, so PHPStan accepts property reads on a set ($set->item).
  • html() and text() have conditional @phpstan-return types: a read is typed string, a write is typed static.

Iterator API (#2)

  • Casting a set to a string concatenates every node's text.
  • getNamespaces() and getDocNamespaces() merge every node's results. Where two nodes use the same prefix, the first node's namespace wins.
  • children() and attributes() flatten every node's results into one set.
  • getName(), asXML() and saveXML() read the first node.
  • addAttribute() and registerXPathNamespace() apply to every node.
  • append() is new on the set.
  • Reading a property on a set ($set->item) returns every node's children of that name, or an empty result when no node has one. isset() now works on a set.

Registered XPath prefixes carry over (#5)

  • A prefix registered with registerXPathNamespace() is registered again on every node Quip returns from that node:
    • qxpath() results, including empty results
    • children(), attributes() and addChild()
    • nodes renamed by setTag()
    • children and attributes flattened into a set
  • Nodes SimpleXML builds itself don't get the prefix: a property read like $quip->child, or a foreach over a SimpleXML list. The README says so.

Attribute nodes

  • text() and html() read the attribute's value.
  • text() writes the value as text, so &, < and " are escaped.
  • remove() deletes the attribute.
  • htmlOuter() returns name="value".
  • The structural verbs throw a \LogicException.

Behaviour fixes

  • before(), after() and append() now work on a queried element with no children or attributes (ruled). In 0.4 such an element cast to FALSE and the verbs did nothing.
  • before() and after() on the root throw a \LogicException. Without it they would build a document with two root elements.
  • setTag() rebuilds the element through the DOM:
    • An empty element carrying an attribute stays well formed (ruled).
    • The element keeps its prefix and namespace, and attributes keep theirs.
    • An opening tag such as <th scope="col"> is accepted.
    • It returns a set of one, as 0.4 did.
  • unwrap():
    • It moves nodes rather than cloning them, so the returned node stays in the document.
    • It never removes the root.
    • On a set, every parent is read before any is removed, so siblings remove their shared parent once and never the grandparent.
  • An empty result remembers its document, so an absolute qxpath() from it still searches that document. This holds even when the empty result was made from an attributes() list.
  • dom() returns FALSE for a missing node. PHP 8.3 throws a ValueError here and PHP 8.4 a TypeError; both are caught.
  • html() accepts the root element of another document.
  • get() now checks whether a query actually matched, so creating a positional path such as item[3] works.
  • remove() returns a bool on a set as well as on one node.

Quip::load()

  • Typed parameters and return value.
  • The error handler, the error_reporting level and the libxml error setting are restored in a finally block, so a fallback load no longer leaks them.
  • The by-reference assignments and the PHP 5.4 branch are removed, and so is the HHVM comment.
  • An empty document, given as a string or as a file, is refused with an \InvalidArgumentException.

CharacterEncoding, CssStyles, OneLiner, Calendar and Contact

  • Strict types and docblocks throughout.
  • @mb_convert_encoding(…, 'HTML-ENTITIES'), deprecated since PHP 8.2, is replaced by mb_encode_numericentity(). toHtml() output is identical for every valid UTF-8 code point.
  • strftime(), deprecated since PHP 8.1, is replaced by date() with the same format.
  • The purify option throws its documented exception when no purifier is installed. The HTMLPurifier branch now uses the global class names, so that path can actually work.
  • OneLiner::wrap() with a non-string class no longer throws a TypeError.

Tooling

  • php >=8.3.
  • Dev dependencies squizlabs/php_codesniffer, phpstan/phpstan and phpunit/phpunit ^12.5 || ^13.3.
  • composer lint, composer analyse and composer test. PHPCS checks only Generic.PHP.RequireStrictTypes (no Drupal standard), and PHPStan runs at level 8. Both report zero, with no baseline.
  • Tests live in tests/ (QuipXml\Tests\) and are split by subject.
  • phpunit.xml.dist uses the current schema and fails a run on any deprecation, notice or warning.
  • CI runs PHP 8.3 and 8.4. build/ and autoload.php.dist are deleted.
  • Inherited docblocks use the PHPDoc @inheritDoc tag. Where a method adds to what it inherits, its own text comes first and @inheritDoc follows.
  • Every file carries the same license header: (c) Greg Payne <1994413+stackpr@users.noreply.github.com>.
  • docs/README.md covers nodes and sets, prefix carry-over, and a full "Upgrading from 0.x" list.

Picks made

  • "php": ">=8.3", not >=8.1. CI tests 8.3 and 8.4, and PHPUnit 12.5 needs 8.3. To flip: >=8.1, with 8.1 and 8.2 in the matrix and PHPUnit ^10.5 || ^11.
  • The MIT header text is not checked. The suggested Generic.Files.HeaderComment sniff does not exist: PHPCS aborts with "Referenced sniff … does not exist". To enforce it, use PHP-CS-Fixer's header_comment rule.
  • The first node's namespace wins a shared prefix in getNamespaces() and getDocNamespaces() on a set. To flip: array_merge() instead of +=.
  • before() and after() on the root throw rather than do nothing. To flip: return $this in parentElement()'s guard.
  • setTag() on one node returns a set of one, keeping 0.4's return shape. To flip: return the element.
  • eq($n) on one node returns the node for any $n, as before.

Source

Verification

  • 233 tests pass on PHP 8.3.31 (PHPUnit 12.5.37), PHP 8.4.22 (PHPUnit 13.3.6) and PHP 8.5. The benchmark group passes when run on its own.
  • composer lint and composer analyse report zero.
  • The Preserve registered xpath namespaces when creating new elements #5 test fails with the prefix carry-over switched off and passes with it on.
  • aapp-drupal against this branch: installed through a local path repository that is not committed. All nine modules that use QuipXml were run: aapp_ui, workspace_collab_report, aapp_foundation, aapp_base, aapp_segment, aapp_presentation, aapp_commerce, aapp_user and aapp_lms.
    • None of the failures is caused by QuipXml. Four tests lack local seed data. One assumes a Review course is always on sale, and the 2026 sale window closed on 2026-10-01.
    • No QuipXml deprecations, TypeErrors or retired-method exceptions.
    • PHPStan over the 34 aapp-drupal files that use QuipXml found one call to fix on aapp-drupal's side: HtmlTableCleaner.php:103 passes ?SimpleXMLElement into getFormattedOuter().
  • Reviewed at 08aeb67 (default, cap 1): 1 round, stopped at the cap.
    • The review ran in the authoring session, so it is less independent. The correctness reviewer verified by execution, including mutation runs on a scratch copy.
    • The convention review was skipped: its checklist is aapp-drupal's conventions, which a standalone library does not follow.
  • Second readers: r1 GPT 8/8/4 · clean Opus 7/7/2. GPT (gpt-6.1-sol) used about 1.45M tokens (1.31M of them cache reads), 59.7 AI credits.

Deploy notes

  • After merge, tag v1.0.0.
  • aapp-drupal then moves to brainite/quipxml: ^1.0 and fixes HtmlTableCleaner.php:103. php-file-converters v0.2.1 already accepts ^1.0.

Tooling friction

  • 2026-10-01 · There is no PHP on the host, so composer and the tools run through docker run of the ddev web image with the checkout mounted.

  • 2026-10-01 · PHPCBF's automatic fixes added a broken use Exception\NotPermanentMemberException; (an unqualified relative name) to QuipXmlElement, which PHPStan caught. The import was corrected to the full namespace.

  • 2026-10-01 · PHPStan ignores a plain __get on a class and on an interface; @mixin QuipXmlElement on the iterator made property reads on it pass analysis.

  • 2026-10-01 · PHP 8.3 throws ValueError and PHP 8.4 TypeError from dom_import_simplexml() on a missing node, so the 8.4-only local runs missed CI's 8.3 failure · the ddev web image ships /usr/bin/php8.3; a scratch copy with its own PHPUnit 12.5 install runs the suite on 8.3 locally.

🤖 Generated with Claude Code

stackpr and others added 9 commits October 1, 2026 12:55
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…strict types

- xpath(), xparent() and xprev() on both classes throw a RuntimeException
  naming qxpath(), qxparent() and qxprev(); they declare `never`, so the
  SimpleXMLElement override is legal without ReturnTypeWillChange.
- QuipXmlElementInterface holds the API QuipXmlElement and
  QuipXmlElementIterator share, with native types throughout.
- The iterator gains the rest of the SimpleXMLElement API (#2): string cast
  concatenates every node's text, getNamespaces()/getDocNamespaces() merge,
  children()/attributes() flatten, getName()/asXML()/saveXML() read the
  first node, addAttribute()/registerXPathNamespace() apply to each; plus
  append().
- before()/after()/append() work on an empty element; setTag() rebuilds
  through the DOM, so an empty element with an attribute stays well formed;
  unwrap() keeps the node attached, never removes the root, and a set
  unwraps a shared parent once; an empty result keeps its document for an
  absolute qxpath(); dom() returns FALSE for a missing node on PHP 8.
- Attribute nodes: text()/html() read the value, text() writes it, remove()
  deletes it, structural verbs throw a LogicException.
- Quip::load(): typed, error handling restored in a finally, the by-reference
  assignments and the PHP 5.4 branch removed, an empty document refused.
- CharacterEncoding replaces the deprecated mbstring HTML-ENTITIES call;
  Encoding, Css and OneLiner are strict-typed with docblocks.
- PHPStan level 8 and the Drupal standard report zero, no baseline.
- Tests split by subject on PHPUnit 12.5/13.3; CI runs PHP 8.3 and 8.4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Conditional return types: reading returns string, writing returns the
node or set, so a caller's trim($x->html()) analyses without a cast.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SimpleXML keeps a registerXPathNamespace() registration on the one object
it was made on, so every query result needed the prefix registered again
before a nested query could use it. QuipXmlElement now records each
node's registrations and registers them on every node it hands back:
qxpath() results, empty results (and the root an absolute query on one
runs from), children(), attributes() and addChild(). Nodes SimpleXML
makes itself, by property access or by iterating a SimpleXML list, still
start without them; the README says so.

Closes #5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ters

QuipCalendar, the ICS and JSON-feed formatters, QuipContact and the vCard
formatter are typed and documented, with signatures compatible with
QuipXmlFormatter. strftime() (deprecated since PHP 8.1) becomes date()
with the same format; fixDtEnd() and fixUid() no longer return by
reference (nothing used the result); getFormattedOuter() accepts any
SimpleXMLElement as its parent declares. New QuipCalendarTest and
QuipContactTest cover loading (folding, parameters, escapes), the ICS
fixes, the JSON feed and vCard round trips, with invented content.


8000
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…every file

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dom_import_simplexml() rejects a missing SimpleXML node with a ValueError
on PHP 8.3 and a TypeError on 8.4; dom() and contentToDom() caught only
the TypeError, so CI's PHP 8.3 job failed 25 tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- unwrap() on a set reads every parent before removing any, so siblings
  remove their shared parent once and never the grandparent.
- text() on an attribute writes the value as text; assigning value made
  libxml read entities and serialise malformed XML.
- before()/after() on the root throw a LogicException instead of building
  a second root element.
- setTag() keeps the element's prefix and namespace and the attributes'
  namespaces, carries registered prefixes, and returns a set of one as 0.4
  did, so count() still counts the renamed nodes.
- Children and attributes flattened into a set keep registered prefixes
  (#5); a set's missing property is an empty result, with __isset().
- An empty result made from an attributes() list finds its document;
  html() accepts another document's root.
- OneLiner::wrap() no longer measures a non-string class; the formatter
  casts preserveWhitespace.
- Tests: the empty-element verbs test now uses a falsy queried node, the
  formatter test asserts indentation, and new tests cover each fix.
- README: empty results throw on html()/text() writes; the upgrade notes
  list every behaviour and signature change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@stackpr
stackpr marked this pull request as ready for review October 1, 2026 18:40
stackpr and others added 3 commits October 1, 2026 13:57
phpcs.xml.dist keeps only Generic.PHP.RequireStrictTypes; drupal/coder
gives way to squizlabs/php_codesniffer as the dev dependency, and the
phpcs:ignore comments that named Drupal sniffs go with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The PHPDoc tag replaces Drupal's inline {@inheritdoc}. A docblock that adds
to what it inherits keeps that text as its summary, with @inheritdoc and
any @phpstan-return after it. QuipCalendarJsonFeedFormatter's constructor
repeated its parent's docblock word for word, so it inherits it too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Quip::load() with $data_is_url on an empty file fell through SimpleXML to
DOMDocument::loadHTML(''), which throws a ValueError; the HTML fallback now
throws the same InvalidArgumentException an empty string gets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@stackpr
stackpr merged commit 68b6164 into master Oct 1, 2026
2 checks passed
@stackpr stackpr changed the title hive-41897 QuipXml 1.0: retire xpath(), add QuipXmlElementInterface, round out the iterator QuipXml 1.0: retire xpath(), add QuipXmlElementInterface, round out the iterator Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Preserve registered xpath namespaces when creating new elements Add SimpleXmlElement methods to QuipXmlElementIterator

1 participant

0