Repository navigation
QuipXml 1.0: retire xpath(), add QuipXmlElementInterface, round out the iterator - #11
Merged
Merged
Conversation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
marked this pull request as ready for review
October 1, 2026 18:40
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions ca
2F37
nnot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Retirem 8000 ent (PHP 9 readiness)
xpath(),xparent()andxprev()on bothQuipXmlElementandQuipXmlElementIteratornow always throw a\RuntimeExceptionnaming the replacement:qxpath(),qxparent()orqxprev().: never, so overridingSimpleXMLElement::xpath()is now legal PHP and#[\ReturnTypeWillChange]is gone.QuipXmlElementInterface\Countable,\Stringableand\Traversable.QuipXmlElement|QuipXmlElementIterator. The iterator carries@mixin QuipXmlElement, so PHPStan accepts property reads on a set ($set->item).html()andtext()have conditional@phpstan-returntypes: a read is typedstring, a write is typedstatic.Iterator API (#2)
getNamespaces()andgetDocNamespaces()merge every node's results. Where two nodes use the same prefix, the first node's namespace wins.children()andattributes()flatten every node's results into one set.getName(),asXML()andsaveXML()read the first node.addAttribute()andregisterXPathNamespace()apply to every node.append()is new on the 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)
registerXPathNamespace()is registered again on every node Quip returns from that node:qxpath()results, including empty resultschildren(),attributes()andaddChild()setTag()$quip->child, or aforeachover a SimpleXML list. The README says so.Attribute nodes
text()andhtml()read the attribute's value.text()writes the value as text, so&,<and"are escaped.remove()deletes the attribute.htmlOuter()returnsname="value".\LogicException.Behaviour fixes
before(),after()andappend()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()andafter()on the root throw a\LogicException. Without it they would build a document with two root elements.setTag()rebuilds the element through the DOM:<th scope="col">is accepted.unwrap():qxpath()from it still searches that document. This holds even when the empty result was made from anattributes()list.dom()returns FALSE for a missing node. PHP 8.3 throws aValueErrorhere and PHP 8.4 aTypeError; 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 asitem[3]works.remove()returns a bool on a set as well as on one node.Quip::load()error_reportinglevel and the libxml error setting are restored in afinallyblock, so a fallback load no longer leaks them.\InvalidArgumentException.CharacterEncoding,CssStyles,OneLiner, Calendar and Contact@mb_convert_encoding(…, 'HTML-ENTITIES'), deprecated since PHP 8.2, is replaced bymb_encode_numericentity().toHtml()output is identical for every valid UTF-8 code point.strftime(), deprecated since PHP 8.1, is replaced bydate()with the same format.OneLiner::wrap()with a non-string class no longer throws aTypeError.Tooling
php >=8.3.squizlabs/php_codesniffer,phpstan/phpstanandphpunit/phpunit ^12.5 || ^13.3.composer lint,composer analyseandcomposer test. PHPCS checks onlyGeneric.PHP.RequireStrictTypes(no Drupal standard), and PHPStan runs at level 8. Both report zero, with no baseline.tests/(QuipXml\Tests\) and are split by subject.phpunit.xml.distuses the current schema and fails a run on any deprecation, notice or warning.build/andautoload.php.distare deleted.@inheritDoctag. Where a method adds to what it inherits, its own text comes first and@inheritDocfollows.(c) Greg Payne <1994413+stackpr@users.noreply.github.com>.docs/README.mdcovers 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.Generic.Files.HeaderCommentsniff does not exist: PHPCS aborts with "Referenced sniff … does not exist". To enforce it, use PHP-CS-Fixer'sheader_commentrule.getNamespaces()andgetDocNamespaces()on a set. To flip:array_merge()instead of+=.before()andafter()on the root throw rather than do nothing. To flip: return$thisinparentElement()'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
docs/recs/quipxml/delegable-quipxml-php9-xpath-retirement.md, the Phase 2 residue (v1.0.0). Hive 41897. Closes Add SimpleXmlElement methods to QuipXmlElementIterator #2. Closes Preserve registered xpath namespaces when creating new elements #5.__toString()concatenates every node's text.attributes()andchildren()flatten.html()reads the first element andwrap()applies to each.setTag()on an empty element carrying an attribute.QuipXmlElementInterfacewith only the methods both classes share.1994413+stackpr@users.noreply.github.com.Verification
benchmarkgroup passes when run on its own.composer lintandcomposer analysereport zero.aapp_ui,workspace_collab_report,aapp_foundation,aapp_base,aapp_segment,aapp_presentation,aapp_commerce,aapp_userandaapp_lms.TypeErrors or retired-method exceptions.HtmlTableCleaner.php:103passes?SimpleXMLElementintogetFormattedOuter().Deploy notes
v1.0.0.brainite/quipxml: ^1.0and fixesHtmlTableCleaner.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 runof 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) toQuipXmlElement, which PHPStan caught. The import was corrected to the full namespace.2026-10-01 · PHPStan ignores a plain
__geton a class and on an interface;@mixin QuipXmlElementon 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