没有不值得去解决的问题,也没有不值得去学习的技术!

PublishPress Series 3.1.3 Upgrade Log: PHP 8.5 Issue Fixed, but a Gutenberg Series Numbering Regression Emerges

[Figure 1: The PublishPress Series PHP 8.5 compatibility Issue #1163 submitted on August 6 has been closed by upstream]

After upgrading to PHP 8.5 previously, I ran a dedicated round of WordPress plugin compatibility checks.

The troubleshooting notes from that round can be found here:

During that round of troubleshooting, PublishPress Series Free 3.1.2 repeatedly produced Deprecated warnings related to SplObjectStorage under PHP 8.5.

The typical messages included:

Plaintext
SplObjectStorage::attach() is deprecated since 8.5
SplObjectStorage::contains() is deprecated since 8.5

After further inspecting the source code, I confirmed that AbstractCollection.php in the plugin directly called these two methods deprecated in PHP 8.5 in multiple places.

At the time, I did not directly modify the plugin source code in the installation directory. Instead, I submitted the issue to the official PublishPress Series GitHub repository:

https://github.com/publishpress/publishpress-series/issues/1163

For me, this approach was more appropriate.

If I had modified it directly:

Plaintext
wp-content/plugins/organize-series/

The local modifications would easily be overwritten during the next plugin update.

Therefore, the principle at the time was:

If an issue can be resolved upstream, let upstream handle it; locally, keep the plugin in its original state as much as possible.

Unexpectedly, about two weeks later, this issue finally saw a follow-up.

Issue #1163 Has Been Closed by Upstream

Reopening the Issue I submitted back then shows:

Plaintext
PHP 8.5 deprecation warnings from
SplObjectStorage::attach() and contains()

#1163

Closed

On the right side of the page, you can also see the 3.13: Bug Fixes Milestone, along with related development records and v3.1.3 version information.

[Figure 1: The PublishPress Series PHP 8.5 compatibility Issue #1163 submitted on August 6 has been closed by upstream]
[Figure 1: The PublishPress Series PHP 8.5 compatibility Issue #1163 submitted on August 6 has been closed by upstream]

This means that, based on the GitHub Issue status, the submitted problem had entered an official fix release.

However, the Issue being closed did not necessarily mean the production environment was free of the problem.

So after the upgrade, I continued to inspect the version and source code actually installed on the server.

PublishPress Series Upgraded to 3.1.3

The current production environment uses:

Plaintext
PublishPress Series Free 3.1.3

The plugin status is normal:

Plaintext
version  3.1.3
status   active

I then re-inspected:

Plaintext
wp-content/plugins/organize-series/src/domain/interfaces/AbstractCollection.php

The code previously causing the PHP 8.5 Deprecated warnings:

PHP
$this->attach(...)
$this->contains(...)

was completely gone.

The actual inspection result was:

Plaintext
OK: no attach()/contains() calls found

The corresponding locations had been replaced with:

PHP
$this->offsetSet(...)
$this->offsetExists(...)

These included the locations 39, 41, 120, 201, 261, 279, 283, and others mentioned in the previous Issue.

[Figure 2: PublishPress Series 3.1.3 in the production environment has replaced all old attach()/contains() calls]
[Figure 2: PublishPress Series 3.1.3 in the production environment has replaced all old attach()/contains() calls]

From the source code perspective, the problem reported in Issue #1163 had been fully resolved.

After Disabling WordPress Debug, You Cannot Rely Solely on Logs to Determine if an Issue Has Disappeared

There is another point here that can easily lead to misjudgment.

Just the day before, I had cleaned up WordPress site health issues and disabled WordPress Debug.

Therefore, simply observing that “Deprecated” no longer appeared in the PHP logs was not sufficient to prove that the PublishPress Series issue was fixed.

There was another possibility:

The messages were simply no longer displayed or no longer logged the way they were before because Debug was disabled.

So this time, instead of relying solely on error logs, I proactively ran a PHP 8.5 runtime test.

During the test, I re-enabled E_ALL and specifically captured:

Plaintext
E_DEPRECATED
E_USER_DEPRECATED

I then actually created the AbstractCollection used by PublishPress Series and called:

Plaintext
add()
hasObject()

The final result was:

Plaintext
add(): OK
hasObject(): OK
DEPRECATIONS: 0
RESULT: Issue #1163 not reproduced
[Figure 3: After proactively capturing E_DEPRECATED and running the relevant code, Issue #1163 can no longer be reproduced]
[Figure 3: After proactively capturing E_DEPRECATED and running the relevant code, Issue #1163 can no longer be reproduced]

Only after this round of testing could I clearly confirm:

The PublishPress Series PHP 8.5 compatibility Issue #1163 I submitted on August 6 had been fixed in the currently used version 3.1.3.

From submitting the Issue, to waiting for upstream, to re-verifying after the official version upgrade, this issue was finally closed loop.

However, this plugin upgrade did not end there.

After the Upgrade, the Series Selection Method in Gutenberg Changed

After upgrading PublishPress Series, a very intuitive change was:

In the past, the series in the post editor could only be single-selected.

Now, the “Series” panel on the right side of Gutenberg had changed to a tag-like selection method, making it look like a post could be added to multiple series simultaneously.

At first, I suspected that the plugin had automatically enabled the Multiple Series feature.

But after further inspection, I found that the current version was PublishPress Series Free 3.1.3, and “Multiple Series” in the backend was still a Pro feature. The free version could not toggle this option via settings.

In other words, the multi-select interface seen in Gutenberg now did not mean the free version had actively enabled Pro’s Multiple Series.

After continuing to compare the implementations of 3.1.2 and 3.1.3, I found that the way Gutenberg handled the Series taxonomy had changed after the upgrade.

This also became an important clue for another problem later on.

Chinese Posts Suddenly All Became “No Part Number”

When I continued publishing posts after the upgrade, I quickly noticed a more practical issue.

Chinese posts could still select a series normally, but the “Series” column in the post list started showing:

Plaintext
No part number

More interestingly, the English versions of the same batch of posts were completely normal.

For example, the Chinese post showed:

Plaintext
A Tour of Go Multilingual Translation Project (No part number)

While the corresponding English post still displayed normally:

Plaintext
A Tour of Go Multilingual Translation Project
(Part 36 of 38)
(Part 37 of 38)
(Part 38 of 38)

The two BeWild posts published today were the same.

Chinese:

Plaintext
BeWild Real-World Testing Series (No part number)

English:

Plaintext
BeWild Real-World Testing Series
(Part 5 of 6)
(Part 6 of 6)
[Figure 4: After the upgrade, newly published Chinese posts still belong to the correct series, but the Series Part shows "No part number"]
[Figure 4: After the upgrade, newly published Chinese posts still belong to the correct series, but the Series Part shows “No part number”]
[Figure 5: The same batch of English posts still generate Series Part numbers normally]
[Figure 5: The same batch of English posts still generate Series Part numbers normally]

This contrast was very important.

It showed that:

The entire PublishPress Series numbering feature had not failed.

At least the English workflow could still write numbers normally.

The problem was more concentrated on the save workflow for Chinese Gutenberg posts.

Series Affiliation Was Not Lost, What Was Truly Missing Was _series_part_*

I then checked these posts directly at the WordPress database level.

The result showed that the Series taxonomy relationships for the Chinese posts were completely normal.

In other words, they did indeed belong to the correct series.

What was truly missing was post meta like the following:

Plaintext
_series_part_41899
_series_part_42451
_series_part_42197

PublishPress Series uses the Series taxonomy to store “which series a post belongs to”, while the Series Part is stored separately in the post meta.

Therefore, a state like this would occur:

Plaintext
Post belongs to series: Normal
Series Part: Does not exist

Ultimately, the backend displayed it as:

Plaintext
No part number

In the corresponding English posts, the same data existed normally.

For example:

Plaintext
Chinese 26935
Series term: Normal
Series Part: EMPTY

English 26943
Series Part: 29

Today’s two BeWild posts had the same situation:

Plaintext
Chinese 26987: EMPTY
English 26994: 5

Chinese 26997: EMPTY
English 27002: 6

Full Site Scan Found Only 6 Affected Posts

To avoid only fixing the few posts I saw in front of me, I then ran a read-only scan on all published posts that belonged to a Series.

The final result was very clean.

Only 6 posts site-wide had:

Plaintext
Already belong to a Series
But the corresponding _series_part_* does not exist

They were:

Plaintext
26935
26947
26958
26968
26987
26997

And all of them were Chinese posts published after the plugin upgrade.

The numbers for the corresponding English posts were:

Plaintext
26935 → 29

26947 → 36
26958 → 37
26968 → 38

26987 → 5
26997 → 6

More importantly, before fixing them, I also checked whether these target numbers were occupied by other Chinese posts.

All 6 were:

Plaintext
OK

Therefore, they could be safely restored.

Restoring 6 Chinese Posts Based on English Corresponding Numbers

I did not simply append these abnormal posts to the end of the current series.

Because the corresponding English posts had already saved the correct numbers.

So the most reliable method was to restore the Chinese Series Parts directly based on the corresponding English posts.

The final restoration result was:

Plaintext
26935 → 29

26947 → 36
26958 → 37
26968 → 38

26987 → 5
26997 → 6

After the fix was completed, I ran a full site scan again:

Plaintext
TOTAL EMPTY SERIES PART: 0
[Figure 6: All 6 affected Chinese posts have been restored to their correct numbers, and there are no longer any published posts missing a Series Part site-wide]
[Figure 6: All 6 affected Chinese posts have been restored to their correct numbers, and there are no longer any published posts missing a Series Part site-wide]

At this point, all historical abnormal data had been fixed.

But if I only fixed these 6, the next Chinese post published could still encounter the same issue.

So the future publishing workflow also needed to be handled.

No Plugin Downgrade, No PublishPress Series Source Code Modification

There were several possible approaches here.

The first was to downgrade back to 3.1.2.

But 3.1.3 had already resolved the PHP 8.5 compatibility issue. Downgrading again to restore the old Gutenberg behavior meant the recently resolved Deprecated issue might reappear.

The second was to directly modify the PublishPress Series 3.1.3 source code.

This was also not an approach I wanted to adopt.

Because after future plugin upgrades, local modifications could easily be overwritten.

The third was to restore the old 3.1.2 single-select Series editor interface.

This approach was doable, but after further consideration, I found it unnecessary.

Although it now looked like multiple Series could be selected simultaneously in Gutenberg, my own usage rule had always been:

One post is added to only one series.

Categories and tags inherently supported multiple selections, while “a series represents a single continuous content line” was the content organization method I wanted to maintain long-term.

Therefore, whether the editor interface enforced single-selection was not that important to me.

What was truly important was:

After publishing a post, it should automatically become the last part of the selected series.

Ultimately, Only a Very Small MU Plugin Was Added

PublishPress Series itself actually still retained the auto-ordering function:

PHP
set_series_order()

When the passed Part was 0, and the post had already been published, it could read the number of the last post in the current series, and then automatically execute:

Plaintext
Last Part + 1

Therefore, I ultimately did not reimplement a Series ordering algorithm.

I only added a very small MU Plugin:

Plaintext
swq-publishpress-series-auto-part.php

It hooks into:

Plaintext
rest_after_insert_post

Which is after the Gutenberg REST save completely finished.

The logic was very simple:

Plaintext
Post has been published
↓
Post belongs to exactly one Series
↓
Current Series Part does not exist
↓
Call PublishPress Series's own set_series_order()
↓
Automatically append to the last position of the current series

Several safety conditions were also retained.

If the post already had a Series Part:

Plaintext
Exit directly

It would not overwrite the existing number.

If the post had no Series selected:

Plaintext
Exit directly

If two or more Series were mistakenly selected:

Plaintext
Exit directly

It would not guess which series to assign a number to.

After creating the MU Plugin, a PHP syntax check was performed:

Plaintext
No syntax errors detected

WordPress had also recognized it normally:

Plaintext
swq-publishpress-series-auto-part    must-use

The PublishPress Series functions and hooks required at runtime were also all normal:

Plaintext
set_series_order: OK
SERIES_PART_KEY: _series_part
rest_after_insert_post priority 20: REGISTERED

Throughout this process, the PublishPress Series plugin source code was not modified, nor was the version downgraded.

At the same time, a full W3 Total Cache purge was not performed due to this adjustment.

This Post Itself Completed the Final Real Production Verification

At this point, the historical data had been restored:

Plaintext
TOTAL EMPTY SERIES PART: 0

The MU Plugin had also entered the production environment.

After restoring the historical data, I still needed to verify whether future Chinese posts published via Gutenberg could also automatically receive a Series Part again.

I did not create a temporary post just for testing. This post itself is the first real production verification post after the fix. This both avoids creating extra test content and directly verifies whether the daily publishing workflow has been restored.

When publishing this post, I still followed my usual method and selected only one Series: WordPress Performance Optimization Notes, without manually filling in the Series Part.

After publishing was completed, I reopened the post list and saw that this post had automatically displayed as WordPress Performance Optimization Notes (Part 21 of 21).

This showed that the newly added MU Plugin had taken effect in the real Gutenberg publishing workflow: the 6 historical abnormal posts had been restored, and new Chinese posts had regained the ability to be automatically appended to the last position of the series.

[Figure 7: After this post was published as the first real Chinese post after the fix, it automatically became Part 21 of "WordPress Performance Optimization Notes"]
[Figure 7: After this post was published as the first real Chinese post after the fix, it automatically became Part 21 of “WordPress Performance Optimization Notes”]

Conclusion

This PublishPress Series 3.1.3 upgrade experience was rather special.

For the PHP 8.5 Deprecated issue discovered on August 6, I did not modify the plugin source code at the time, but chose to submit an upstream Issue.

Two weeks later, re-inspecting confirmed that:

Plaintext
Issue #1163 closed
Old calls in source code replaced
Runtime DEPRECATIONS: 0

This proved that the choice to wait for an upstream fix was effective.

But at the same time, after upgrading to the new version that resolved the old issue, a new Gutenberg Series Part save abnormality appeared.

Ultimately, through database inspection, it was confirmed that:

Plaintext
Series taxonomy normal
Series Part missing

There were 6 affected Chinese posts site-wide.

After restoration:

Plaintext
TOTAL EMPTY SERIES PART: 0

For future posts, I did not downgrade the plugin or modify the third-party plugin source code. Instead, I added a very small MU Plugin that continued to call PublishPress Series’s own existing auto-ordering function.

This post then directly served as the first real Chinese post after the fix to complete production verification. When publishing, I only selected “WordPress Performance Optimization Notes”, did not manually set the Series Part, and after publishing was completed, it automatically became Part 21 of 21.

This experience also demonstrated once again:

A plugin upgrade does not end simply after clicking “Update”.

After an old issue is fixed, the new version still warrants an actual production verification.

Especially for data issues like series numbering, which do not directly cause site errors but quietly alter the content structure, if the difference between the Chinese and English backends had not been observed, it would likely have gone unnoticed until many more posts were published.

And this time, from the upstream Issue fix, to the new version regression troubleshooting, to the historical data restoration, future publishing compatibility, and the final verification with a real post, everything was ultimately completed without modifying the PublishPress Series plugin source code.

At this point, this issue was completely closed loop: the PHP 8.5 compatibility issue in Issue #1163 was fixed by upstream; the Gutenberg Series Part regression that appeared after the upgrade was localized and historical data was restored; the minimal MU Plugin handles auto-numbering for future posts; and this post, as the first real production post, ultimately verified that auto-numbering had returned to normal.

关于作者 · 持续学习与技术实践

我是一名拥有 15 年以上开发经验的技术从业者,自 2013 年起持续运营个人技术博客,记录工作与个人项目中遇到的真实问题,以及解决问题过程中的探索、实践和思考。

除了技术写作,我也在持续开发和维护自己的独立项目,探索新技术和新工具在实际场景中的应用。我始终相信,没有不值得去解决的问题,也没有不值得去学习的技术。

如果这篇文章对你有所帮助,欢迎浏览博客中的其他文章,也欢迎交流技术经验与想法。

关于我  ·  GitHub  ·  邮件联系