A few years back I started a downstream fork of Horde to develop features I needed for foss and customer deployments without upstream dependencies. It went successful, was a great learning opportunity and a good exercise in critiquing our old tool chain and approaches. We had some well-known downstream users and contributors but I’d say it has run its course. It’s time to sunset Maintaina in a controlled way that’s fair towards our user base. As we are nearing a beta and prod release of horde 6 proper mostly built from Maintaina, we want to provide a smooth transition.
Horde 6 (upstream) is focusing on supporting PHP 8.4 without spamming warning¬ices while Maintaina was originally targeted at PHP 7.4 through 8.1 – Still supporting anything before 8.2 is not a priority with upstream anymore. I will have to discuss with other maintainers of the fork.
Problems to solve:
Archive libraries which haven’t been touched for long
Coordinate upstreaming libraries with recent changes and archive them
Provide a feasible approach to consume only select maintaina packages and mostly upstream packagist
Clarify the future of changes downstream users want to keep but which compete with Horde upstream solutions
Invite maintainers of downstream code to maintain some upstream libraries to prevent stalling their own needs
PHP 8.0 introduced null and false as members of union types but disallowed them as standalone parameter types. PHP 8.2 changed that and allowed null as standalone parameter types. What is this good for? Should they extend this to “never” one day? Why do I call standalone null parameters poor man’s generics?
What’s a null parameter? What’s a nullable parameter?
A null parameter is a parameter of type null which can only ever have one value null. Its core meaning is “not a value” as opposed to “empty string” or “false” or “zero”.
A union type which has other values but can also contain null is called nullable. For example, boolean is not a nullable type. It has the possible values true and false. If we want to allow a third state, we can create a new nullable type bool|null which has the possible values true, false and null. In modern php, bool is a union type of true, which can only have the value true, and false, which can only have the value false. So bool|null is equivalent to true|false|null. Union types including null can also be written with a preceding question mark: bool|null is equivalent to ?bool
Isn’t this a bit pointless?
A null parameter by itself is not very interesting. After all, we know its only possible value. It is valuable as a type which can be extended. According to Liskov substitution principle parameters of subtypes should be contravariant to parent types. If the parent type accepts null as a parameter, the child type must accept null as a parameter but may accept anything else. The opposite is true for return types. The child class may have a more specific return type than the parent class but must not return anything the parent would not allow. This is called covariance. In PHP, the top type is called mixed and allows basically everything, even null values. The null type is at the other end of the scale. If the parent returns null, the child must not return anything else. There is one more restricted return type, never. A function of type never must not return at all. It is either an infinite loop or may only exit the whole program. But never is not an allowed parameter type. There is also a return type voidwhich is in between the two. Void may return from functions, but it returns semantically nothing. Not even null.
What is it good for?
Defining an interface parameter as null is allows to define an almost generic interface which might be substantiated in derived classes. Let’s look at an example.
<?php
interface A {
public function get(null $value): mixed;
}
class B implements A
{
public function get(null $value): ?object;
{
return $value
}
}
class C extends B
{
public function get(A|null $value): XmlElement;
{
if (is_null($value)
{
$value = new SimpleXmlElement("Not Null");
}
return $value;
}
}
class D implements A
{
public function get(B $value)
{
}
}
If you don’t see the point, let me explain. interface A defines that any implementing class must have a method get(null $value) which has only one mandatory parameter. This parameter must accept null as a value. Any additional parameters must be optional. Any derived class may make the first parameter accept more types and even make it optional. The only drawback: Class D cannot be implemented because function get does not accept null as its first parameter $value.
Generics: I wish I had a little more nothing
This is as close to actual generics as one gets with PHP. Generics are code templates which do not have specific parameter and return types until an actual class is created from them. Some other languages do have them but PHP doesn’t. Larry Garfield and others have made the case for them over and overagain.
There are some challenges in the engine which make them hard to implement. It would matter less if we had some tbd or changeme type which can only exist in interfaces and can be overridden by any other type. But we don’t. At least we have standalone null.
Ria Weyprecht befasst sich seit über zwei Jahrzehnten mit Web-Gestaltung und Technik – ob nun mit WordPress, anderen Plattformen, Inhouse-Frameworks oder ganz frei. Mindestens seit der Halbzeit spielt auch Barrierefreiheit zunehmend eine Rolle. Mit großem Interesse lese ich seit einiger Zeit auch ihren deutschsprachigen Blog “stolperfrei.digital”. Dort stellt sie immer wieder Techniken vor, mit denen man die Barrierefreiheit von Webseiten verbessern und unnötige Schwierigkeiten vermeiden kann. Ob Zugänglichkeit für Sehbehinderte und Benutzer von Screen Readern, ob Leichte Sprache oder die Vermeidung von Reizüberflutung, immer nah am Stand der aktuellen Forschung und mit Blick auf die Praxis.
Mein beruflicher Schwerpunkt hat sich von Frontend-Belangen immer weiter weg entwickelt. Arbeite ich dann in der Freizeit an Projekten wie Horde Groupware oder JMRI, dann bekommen Profis und Betroffene wahrscheinlich das Grauen. Die technische Basis ist trotz vieler Neuerungen nicht ganz taufrisch und auch das Wissen um den richtigen Einsatz von Gestaltungsmitteln braucht immer mal wieder eine kleine Auffrischung. Es fehlt mir im Frontend auch die handwerkliche Routine und Praxis, die ich tiefer in der Applikation mühelos vorweisen kann. Wie gut, dass im Stolperfrei-Blog immer wieder kleine und große Themen aufgerissen werden. Ich kann direkt überprüfen: Gibt es hier für mich etwas zu tun? Kann ich das Gezeigte anwenden? Oft finde ich auch Hinweise auf weiterführende Themen.
In the last few evenings there was great despair. Trying to solve one problem would reveal yet another one. As a result, I hesitated to release some of the changes immediately. I don’t want to make people suffer, having to deal with new improved problems of the day whenever they run an update on their horde installations. I’m glad feedback on the mailing list has improved quite a lot, sometimes coming with patches and suggestions and even people telling me things start to just work. That’s great. But whenever you see the light, there’s a new challenge on the horizon. Or rather something very old lurking in the shadows.
Break it till you make it
So recently we felt confident enough to switch our local installation from a frozen state to the latest version of the wicked wiki and the whups bug tracker. We also updated the PHP container, the database version and the likes. This turned into a great opportunity to test the rollback plan. 🙄 Issues were cascading.
Bullets you might have dodged
Generally having both the composer autoloader and the horde autoloader work together creates some friction. This is complicated when the exact order in which they are initialized is not the same in all scenarios. As reported previously, Horde’s apps are not strictly conforming the PSR-0 autoloading standard while the libraries mostly do. Newer releases of the apps autoload using a class map instead of PSR-0 logic. But that class map was not restricted enough in the first iterations. Thus you might have the canonical locations of classes in the autoloader, but also the version in the /web/ dir or, in case of custom hook classes, the version from the /var/config/ directory. Torben Dannhauer suggested to restrict the rules and we will do that with the next iteration. The first attempt to fix this unfortunately broke overriding the mime.local.php config file. An update is in the git tree and will be released as a version later this week. But I’m glad we ran into this as it revealed another dark secret
We part, each to wander the abyss alone
Turned out the wicked wiki software carried a little library Text_Wiki in its belly. Hailing from PHP 4 days, it’s archaic in its structure and its way of implementing features. Parts of the test suite predate phpunit and the way it’s packaged is clearly not from our times. This library also exists as a separate package horde/text_wiki. Which also exists as pear/text_wiki both in the classic PEAR archive and the modern github repository. While the base package does not exist in packagist, the extension driver for mediawiki format does. Odd enough. It’s really a shame the software from the old PEAR ecosystem is slowly fading away because of its ossification. They all share ancestry and they were all largely written and maintained by the same set of people but they are all different in subtle ways.
Text_Wiki works great when it works. But it’s a real treasure trove of incompatibilities with modern PHP versions. Over the years, unicode support has evolved along with the strictness of PHP’s core. While I am very much willing to contribute back any changes to the official pear version, I have my doubts if they will be accepted or handled at all.
Rising again like the phoenix
I really, really did not want to deal with any of this. Creating a fourth version out of three splinters feels like madness. But what can you do? The result is an upcoming version of horde/text_wiki and horde/wicked which is a radical break. The new text/wiki has no PSR-0 lib/ content. It’s all PSR-4, it’s namespaced, every single class name and file name has changed. A new test suite has been started but only a tiny fraction of unit tests have been ported so far. The different extension drivers for mediawiki and tiki dialects have been incorporated into the base package as I did not want to maintain a hand full of packages.
The whole thing couples as little to horde as possible. It has its own exceptions based on the PHP builtin exception tree, so no dependency on horde/exception. I even stripped the dependency on Pear_Exception as there is no value in keeping that nowadays. Anything which ties this revamped library into the horde ecosystem now lives in horde/wicked. Extra markup rules which render horde portal blocks into a wiki page. Adapters querying the database if a linked page already exists or must be created. Dynamic links created from the registry and application states. None of this glue belongs into the text_wiki library.
Many incompatibilities with modern PHP have been solved. Often this was a matter of mixing and matching bits from the three different splinter versions out in the wild. Some of it is just a chore to do. Of course, the pear XML files are gone and the composer file is fully compliant with packagist and most recent composer. At least this part has been contributed back already.
Dawn, finally
It will be another few evenings until the new horde/wicked and the new horde/text_wiki are ready for a tagged release, probably along with some of the changes to other libraries I explained above. There’s probably something that will break and need fixing. But that shouldn’t block progress for too long.
Horde 5 relied on the PEAR ecosystem ripping apart their packages and putting everything where it needs to be. But PEAR is a thing of the past. Horde 6 integrates with the composer installer using an additional piece called the horde/horde-installer-plugin. This composer plugin links together pieces from the installed composer packages into the right places and adds auto-generated configuration to make sure everything is found even though stuff is NOT mixed together the way PEAR did. This was a good starting point early in Horde 6 development when we took great pains not to break the previous distribution installs (which relied on PEAR or PEAR like behaviour) and installs based on horde-git-tools.
However, by now this is much less a priority and we are absolutely willing to move forward and make things less complicated, potentially breaking and changing code that relied on these older schemes. Much less code and assets are going to be exposed through the /web/ folder.
In proxy mode composer will not symlink whole apps to the web dir but only create folders and files outside lib/, src/, test/ and a fairly large exclusion list. The endpoint php files will forward requests to the actual code in /vendor dir. This should reduce code duplication and makes it more obvious where related files need to be looked up
A new constant HORDE_CONFIG_BASE is written to the autogenerated registry snippets.
The composer autoloader is directly loaded by the proxy php files before delegating to the actual file in the vendor dir. If you see unexpected class not found messages when testing proxy mode, please upgrade your horde/core package.
Currently proxy mode is a one-off. However, in an upcoming version the last used mode will be persisted to the composer.json file and reused on subsequent commands without an explicit mode option. Proxy mode is supposed to become the default in horde-installer-plugin 3.0.
Benefits of proxy mode
Proxy mode is the first step towards clarifying the intended architecture. Until recently much of our detection logic needed to behave differently if called through a file in the webroot or the same file but in its original vendor/horde/$app location. The new proxy files always perform the same way:
First load the composer autoloader because the file always knows where the autoloader is relative to its own path.
Then load the actual file in the vendor/horde/$app location
Horde’s own internal PSR-0+ autoloader would only be loaded after composer’s autoloader. It hits action less and less often and will probably be removed from the default setup altogether.
This means the actual class files can rely on __FILE__ pointing to a predictable scheme and much less guess work and protection code is needed. On the other hand, it reveals some hidden problems and complications which developers can now fix before making this new mode the default. Unexpected lowercase class names (as found in whups and Horde Forms), complicated chicken/egg issues in the Registry, duplicate class names and parts of the error handling broken by subtle changes in newer PHP versions can now be seen and fixed.
As a consequence of spotting bugs and loading issues as I go along, starting with version 2.7.1 the composer plugin will check if a file var/config/autoload-extra.php exists. If it does, it will be included after the composer autoloader. This allows selectively hardcoding some class files until fixed versions of apps become available – or to actively undefine something for tests.
Some years ago I reasoned about upgrading unit tests from ancient PHPUnit 4 to then-recent PHPUnit 9. Back then Horde’s unit test suite would use a Horde_Test class inheriting from the actual phpunit test cases. Even then I was fairly certain that this approach was not very practical in the long run. Why extending PHPUnit might be wrong – ralf-lang.de
Turns out this is right. With many new or refactored components I started to use plain PHPUnit 9 and only resorted to Horde_Test when I strictly needed it. This simplified things a lot. The Horde organisation houses a dozen or so apps, almost 200 library repositories and some auxillary stuff. Having Horde_Test in the inheritance hierarchy makes any upgrades awkward. Need to be more strict about signatures for a new PHP release? Fix it all at once. Want to adopt a newer phpunit framework? Do it wholesale. Hook into some internal PHPUnit mechanism? They told us not to and they use their freedom to break internal classes very liberally. Tough luck.
So instead I am mostly abandoning the Horde_Test_Case base class and everything that comes with it.
PHPUnit hooks right into the composer autoloader. No more AllTests.php, autoload.php or bootstrap.php
I use the PHPUnit version I see fit. If I rarely update a component and it’s supposed to run on old PHP 7.4 through PHP 8.4, then I am fine when the tests work with PHPUnit 10.
If I develop something bleeding edge which does not need to work on PHP 8.2 and older, I simply start out at PHPUnit 12.
If I want to abstract out a test helper which is useful beyond the limits of an individual repo, I try to avoid building new bases classes. Instead I build it as a utility
Many libraries which get a wholesale upgrade no longer depend on Horde/Test. This is good because Horde/Test pulls in too many implicit dependencies anyway.
This comes at a price though. Our custom test runner relied on a specific structure of horde tests. The internal quality check pipeline in the horde-components tool also relied on a specific phpunit version and library layout. These are now broken and I won’t try that approach again.
So the new layout looks fairly standard.
Tests are in the /test/ subdirectory
Unit tests which are intended to run on most platforms are in /test/unit. Tests which require external resources, expensive calculations or rarely used PHP extensions get their own lowercase test suite directory /test/ldap/ /test/pam/ /test/kolab/ /test/integration/
The horde-components tool autodetects these test suites and sets up the appropriate PSR-4 autoload-dev rules in the composer.json file
If you want to run horde-components on a version of PHP which is not yet reflected in packagist.org released versions:
me@mine:~/horde/components$ composer config minimum-stability dev me@mine:~/horde/components$ composer install –ignore-platform-reqs
No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information. Loading composer repositories with package information Updating dependencies Lock file operations: 90 installs, 0 updates, 0 removals
Installing horde/text_diff (dev-FRAMEWORK_6_0 f7cfbc2): Extracting archive 73 package suggestions were added by new dependencies, use composer suggest to see details. Package php-extended/polyfill-php80-stringable is abandoned, you should avoid using it. Use php >= 8.0 instead. Generating autoload files Applying /presets for absent files in /var/config Looking for registry snippets from apps Writing app configs to /var/config dir Linking app configs to /web Dir Linking javascript tree to /web/js Linking themes tree to /web/themes
Beware, these constraints are there for a reason. Expect things to break in unexpected ways if versions are actually incompatible.
Scenario:
You run a linux or wsl-equipped windows development machine where you do 90% of work for organization A using github.com and 10% for “other” and you strictly must not use the same github account. Both types of work require multiple repos so handling access per-repo is tedious.
Scenario B: Privilege separation
You have an account with high privilege on certain repos which you need to keep, i.e. to override CI failure on time critical issues, be able to block access on short notice or do things you would not allow the juniors to do. But you want to saveguard your 95% daily work against accidentally doing something to the wrong repo
Approach: Have two separate operating system users. Actual access control on the filesystem is not the issue we want to tackle but separation of accounts. You can even “share” the code
Logout again. After this point you don’t need to login to different browser sessions all the time.
You can also use prepared github personal tokens of each users and save the web browser hassle. I chose to go the UI way this time.
You can freely connect IDE’s to repos using your primary account for both types of repos. The only thing you must avoid is pushing and PRing through the IDE.
Instead have a terminal window for each type of account and do it there
git push — # This should not be possible to get wrong. Github will not allow you to push to a repo the account does not have access to.
gh pr create –fill # Create PRs without hitting the browser and avoid all the login handling. Alternatively you can use another browser profile or browser install, i.e. use Firefox for your oddball account and your primary browser (probably something chromium based) for the main use case.
Making plans is great but it’s just words. How are things going? Clearly moving towards goals but in unexpected ways.
Trains don’t only run on railroad tracks but supposedly on schedule. Commuters shall know every stop, arrival and departure, the order of cars and their position on the platform. If trains regularly arrive delayed, at another platform, composed of different or differently ordered cars it is a source of frustration. If they skip a station or get relayed to another course, it’s even worse. Software projects, on the other hand, are expected to detour regularly in very similar ways but hopefully arrive at certain way points more or less on time. Sometimes they get unplanned additional cars along the way. Sometimes you have to replace the engine. It never gets boring.
What is the goal?
In January, I anticipated there were some unknowns ahead but I did not detail how to tackle this.
Improve JMRI‘s support for the Märklin MCAN protocol and particularly the Mobile Station 2, Central Station 3 and Can-Digital-Bahn products. This might become a bit controversial.
The Märklin Hardware Throttles (Mobile Station 2) implement hot plugging and negotiate which one acts as the primary. They send a regular PING command announcing their type and serial and expect a PONG response from other devices on the bus. The most senior serial number is agreed to be the primary throttle even if the other one was the primary or single throttle until now. The primary offers its roster to the other throttles. If higher end Central Station systems are on the bus, one of the central station will always be the primary device and the throttles all behave a little different. This allows JMRI to passively listen to traffic and detect bus devices or actively send a PING and collect the PONGs.
The Can-Digital-Bahn devices have a similar PING/PONG mechanism used by their configuration utilities. Unfortunately there are different configuration utilities for different generations of their sensors, relays, turnout controllers, light controllers, switchboard components, mixed devices. These utilities are closed source Windows programs and you need different versions of the program for different versions of the components. Unfortunately, not all of the programs properly run on recent Windows systems.
What if I just had to push a button in the web browser and see all my MCAN throttles and devices in a table, loading the right configuration screen for each of them? Sounds much better, but how to achieve that?
Moving through the stack
To send the PING messages and receive the PONG messages a program needs to connect to the MCAN bus. This can be achieved by connecting the CC-Schnitte interface to the USB port of the computer or connecting to a Central Station device over TCP/IP. Both methods expose the raw MCAN bus to the software. Both options are already implemented in JMRI.
Next the necessary bus messages and response need to be added to the software. The MCAN PING command is already implemented but JMRI doesn’t implement the desired reactions to the answers. For can-digitial-bahn messages, support is still missing.
To use the found devices, a program needs to memorize some representation of them. JMRI currently does not have a generic way of handling external bus devices as such. Throttles and sensors are tracked in their specific roles, covering their common aspects as throttles or as sensors. For CBUS type connections, there is a node manager which looks very similar to what is needed for MCAN but the UI code and the table format probably deviates a bit. This is where it becomes a bit complicated.
Users need some kind of GUI to interact with found devices. There are many reasons to start out with a browser based UI instead of building it in JMRI’s native Java GUI. The browser based ui just works on any tablet or laptop connected to the network. It’s well decoupled from JMRI’s core. It can be styled or completely recomposed as needed without touching JMRI itself. JMRI does not need to bundle variants for different use cases but they can be installed separately, developed on their own schedule. JMRI only needs to expose the necessary interface protocol which also drives other parts of the browser based UI.
JMRI’s interface protocol is composed from JSON messages between the browser client and the JMRI server. These can be sent over the HTTP server port or through a separate WebSocket implementation. The latter provides better performance and less overhead.
JMRI’s WebSockets and HTTPS API
This is what I ended up doing. To familiarize myself with the API I built a simple demo use case to manipulate the displayed railroad company name. Previously this was only possible through the preferences screen in the native Java GUI. I ended up not integrating it in the regular browser based GUI but implement a separate demo page. JMRI core developers pointed out that special care is needed and unauthenticated calls to the API must not actually persist the changed configuration into JMRI.
Obviously this would not work for actually handling hardware. While JMRI already has a permissions and user authentication system, it is fairly new and does not cover the actual API messages. So my next step would be to implement the necessary messages in the JSON WebSocket API for retrieving an authentication token. This token would then be used to authorize further WebSocket calls which actually change something in JMRI. These new calls need to carry the authorization token as part of the data.
I plan to detail this development in a separate article later this month as I move through the process.
Seems like I should be getting somewhere
This free time project is a great adventure into the unknown between where I am and where I want to be next. In some ways this is similar to professional work. I commit to goals and target dates and I have a very clear understanding of next week and some ideas about the week after. Beyond that the way points and schedule dates become rarer.
It’s sometimes very challenging to tell project managers that there won’t be many super detailed milestones beyond the horizon of immediate next steps. Gladly, at work I have very smart project managers who know when to trust me and when to challenge me. Sadly, in free time I have a very harsh and unforgiving project manager who often won’t take no for an answer.
Paradox Development Studios is famous for their grand strategy games including the flagship Europa Universalis franchise. While a new main version is developed under code name Project Caesar, the latest Europa Universalis IV still gets new expansion packs (Download Content) and updates to the base game. Paradox even backported several former add-ons into the latest version of the base games. We are talking about a product originally released in 2013, almost a teenager now.
Their 2019 spin off Imperator: Rome turned out to be a much smaller commercial success. After a few add-ons and updates it got cancelled in 2021 due to dwindling sales. It was not their first foray into ancient history. Europa Universalis: Rome debuted in 2008 but it was not a long lived installment. Only one download content got produced before the product was relegated to the back catalog.
While Imperator: Rome is based on technology introduced for Europa Universalis 4 and the concurrent generation of spinoffs, Europa Universalis: Rome is clearly a member of the Europa Universalis 3 generation of the engine, UI design and scripting approaches. Imperator debuted the Jomini middleware between the Clausewitz engine and the actual game content. Jomini has since been used in later installments of various Paradox Grand Strategy games.
Even though Imperator product development has been cancelled in 2021, Paradox employees have still worked on bug fixes and feature patches. In April 2024, a new version 2.0.4 has been released for all supported platforms after it was available as an opt-in beta version for several months. In December 2024 a new patch 2.0.5 has been made available as public beta. The patch contains minor UI tweaks, some fixes to the computer player AI, some bug fixes and many additional hooks and exposed variables for the scripting engine. This allows builders of unofficial game modifications (“Mods”) to add new behaviours to the game like Trade Embargoes or forbidding some game characters to inherit provinces. Imperator: Invictus is the most prominent modification for the official Imperator game. It works both with the latest version of the base game and optionally all available official addons.
I find it very motivating and inspiring when a vendor continues to work with fans and open source community and supports their efforts to add more value to their discontinued commercial product.
As of January 2025 Imperator: Rome and all individual add-ons are available at a heavy discount from Paradox’ own store. At the moment they offer the individual components for less money than the official bundle. I am in no way affiliated with Paradox but I like the way they do this and the game is really fun.