PHP, Joomla!, and WordPress keep changing. You're locked in a constant uphill battle to react to those changed. It's painful, and draining. There's a better way. You just need to… RTFM!

This is the first video in my (re-)launched YouTube channel. I am talking about web development with Joomla! and WordPress in videos posted once or twice a month.

Video transcript

Intro

If you’re developing software for Joomla or WordPress – or both – you are probably familiar with the following.

There are constant changes in Joomla, WordPress, even PHP itself. Instead of adding and refining features in your software, or even writing new software, you are in a constant uphill battle to react to those changes which keep breaking your software.

This Sisyphian task of eternal updates won’t stop, but it doesn’t have to be painful either.

All you have to do is… read the fine manual.

What manual? Well, that’s what I am here to tell you about! Been there, done that, got the t-shirt.

The Joomla documentation site

Back in the olden days of Joomla all its documentation was hosted on the documentation site at docs.joomla.org.

This was a rather peculiar mix of documentation for end users, site integrators, extension developers, and core developers. It was disorganised, hard to maintain, and even harder to locate anything in there without using a third party search engine.

This mess still exists, and it is the first thing you’ll have the misfortune of coming across when you go to joomla.org and click on Documentation.

It’s a trap!

If you are a developer, you should never use that site. It’s obsolete.

The Joomla developer network

One first-party resource you need to know about is the so-called Developer Network at developer.joomla.org.

Despite the grandiose name and the plethora of information here, there’s only a couple of things which are worth your time.

The first is the announcements on Joomla! unstable releases, below the fold. You can use these to test your software before an official release comes out. This gives you at least a week to catch any weird issues you would otherwise only find out about on a Tuesday evening when a new Joomla! release drops.

The second important bit is the security announcements. They are tucked away to the sidebar, but they are super important even if you do not publish security software. These announcements usually have information about backwards incompatible breaks caused by Joomla! addressing security issues. This information is rarely, if ever, found anywhere else.

I explicitly warn you not to use two things you’ll find on the Joomla! Developer Network.

The Documentation buttons point to automatically generated PHPdoc content which is exactly what you already have in your IDE. Despite being prominent, it’s the least useful piece of information.

The usage statistics are practically useless, as they tend to count updated sites twice – once for the old version of Joomla! and once for the new one. Moreover, they list sites which are essentially dead and no longer part of the market. If you plan your software around these statistics you will suffer.

The Joomla manual

The second, newest, and most important resource for Joomla is the Joomla Manual at manual.joomla.org.

Okay, let me rant for a minute. This is the single most important resource for Joomla! extension developers. However, it’s not linked to in the header or footer of any joomla.org site. The best thing Joomla! has ever done to make the life of developers easier is impossible to find unless someone like me tells you about it on a silly video on YouTube. This is insanity! Joomla, please, do get your act together.

Rant over, let’s get back on track.

If you’re an aspiring Joomla extensions developer, start with the Joomla! manual. It explains how things work, and how to get started writing software. It even has good pointers to fundamental PHP topics you need to know about.

For developers who, like me, have been publishing Joomla! software for a while there’s this absolutely fantastic link right here called Migrations. Here you can find everything that has or will change between Joomla versions.

This gives you at least two whole years of advance warning about what will eventually be backwards compatibility issues. Reading these migration notes and taking action on them today will ensure that your software will run without a problem in future versions of Joomla!.

Other Joomla resources

If you want to stay on top of what Joomla is doing across the board I strongly recommend going into the RSS News Feeds page page, and follow all these feeds. There are a lot of different RSS feed readers out there. I am using Akregator on my Linux desktop. Other popular choices are Feedly, Reeder, Inoreader, NewsBlur, Flipboard, and the almightly Mozilla Thunderbird. Most of the Joomla resources I talked about have feeds. One feed you shouldn’t miss is the Joomla! Community Magazine. Once a month it publishes articles about Joomla, including announcements of upcoming features.

If you are migrating an extension from a legacy Joomla! 3 code base you might need some help to get started. I had written two sets of tools for that.

The first is my Joomla! Typehints repository which helps you understand how the old Joomla! API class names have changed into namespaced ones. For example JFactory becoming . It even comes with Rector rules to automatically upgrade your codebase to these new classnames.

If you don’t know about Rector, you should check it out! It’s a magical tool which allows you to apply rules which refactor your software without the pain of doing so by hand.

Speaking of Rector, I had written a set of Rector rules to handle the annoying bulk of moving files around and converting your classes into namespaces. It’s far from perfect, I am not maintaining it anymore, but it can help you get started fast.

Finally, I wrote an entire book on the new Joomla API introduced with Joomla! 4.0. This book is primarily for people upgrading their code, but it also contains some hints, tips, and tricks I have acquired over a very long career… sorry, wrong movie. Anyway, it predates and now complements nicely the Joomla! manual site.

WordPress resources

Ah, WordPress! Once the best documented CMS for developers. Let’s see how it holds up these days.

The old WordPress Codex site is still there, but it’s no longer maintained. As such, it’s no longer linked to by the main wordpress.org subdomains, and if you accidentally visit it there’s a subtle banner up top telling you to go to…

The Developer Resources site. Nice! WordPress sets the example of how to give developers quick and easy access to everything they need to write software for your platform.

Right at the top there’s a nifty link to find out what’s new in the current minor release of WordPress. At the time this video was produced that was 6.6. Unfortunately, there is no link anywhere to see what was introduced in a past version… but don’t let that stop you. You can construct one yourself. Just replace the version number at the end of the URL with something else. For example, this is how I can see what changed in version 6.3.0.

There is a minor issue here, though. It only lists API changes. It does not talk about how whole features which are spread between several API changes have evolved, or been replaced. We’ll get to that.

Back in the main page of the developer resources, the Documentation and API Reference sections, above the fold, is what new developers need to get started, and older developers to study for using one of the many available features.

Below the fold there’s this often overlooked section called Developer Blog. The developer blog is where you find discussions about how to use entire new and updated features, and where you will find out about major changes affecting more than one small part of the API. It does have an RSS feed which I strongly recommend following.

And yet, this amazing developer resource page is not the whole story. There are changes which are not documented on time, or at all. Like the WordPress 6.3 change in how plugin updates are handled which caused my company a major headache last year. To find out about this kind of changes, and to learn more about upcoming changes, you will have to follow the WordPress Trac entries like a plebian. This puts a rather dark spot on an otherwise excellent developer experience.

PHP resources

But enough with the CMSes themselves. Let’s talk about PHP.

PHP releases a new minor version every year. Each new version gets two years of full development, and – since PHP 8.1 – another two years of security fixes, for a total of four years before it becomes end of life. Each major PHP version gets five of these minor versions, then we get a new major version. Small but sometimes breaking changes are introduced in every minor version. Huge and most definitely breaking changes are introduced in major versions.

First of all, you need to know which PHP versions are supported and up until when. You can find that in the PHP Supported Versions page. This will let you plan your software’s PHP support ahead of time. My company tends to support each new PHP version for however long it’s supported by the PHP project itself, plus six to twelve months. You can’t realistically expect everyone to update instantly.

The second resource you need to know about is the migration notes for each new PHP version. It’s kind of hidden in the PHP documentation’s Appendices. You should also note that it only covers changes in already published PHP versions.

So, how can you prepare for upcoming versions?

That’s surprisingly easy. No change in PHP happens on a whim. There’s a process where a change is proposed in what is called an RFC which stands for Request For Comments. The RFC gets discussed, voted on, and if accepted it gets implemented. You can find all of the RFCs in PHP’s Wiki. If you scroll down to the Implemented section you will see what got implemented in each PHP version, including the upcoming one. Every RFC clearly states backwards incompatible changes, deprecations, and any migration notes necessary for developers using PHP.

Perusing the PHP Wiki is rather chaotic, for sure. There’s the PHP Watch site which can help you navigate the RFCs. They have a monthly newsletter I strongly suggest subscribing to.

Between the migration notes and the RFCs you have excellent information to upgrade your code for newly released and upcoming PHP versions. In my company, we start our preparation for the upcoming PHP version in September, which means that by late November to early December, when the new PHP version drops, we’re mostly if not fully ready.

Don’t panic

As per the poet, the best laid schemes of mice and men often go awry.

Being proactive with your code maintenance and reading the fine manual won’t make you completely immune to any and all backwards compatibility issues. Not all backwards incompatible changes are properly documented as such, or at all. No matter what you do will you ever be able to catch every single one of them ahead of time.

In fact, I can guarantee that you will face backwards incompatible changes which break your software. I can also guarantee that being proactive these problems will be far less common, and far less soul crushing as when you’re constantly playing catch-up with Joomla, WordPress, and PHP.

Such is life.

Outro

Well, that’s it for today.

If you enjoyed this video and would like to listen to me talk more about web development please like this video, subscribe to this channel, and hit that bell button. I’m uploading one to two times every month.

As always, the full transcript of this video, links to resources I mentioned, and any extra information that didn’t make it into the video can be found at my site linked in the video description below.

Until next time, be safe, and be kind to each other.

Beyond the video

Those with good hearing among you will notice that the sound quality in the Joomla docs and developer network segments is… weird. My USB mic had a weird hum during those sections. Everything filmed before and after, in the same session and video file, had perfect sound. I had to remove the noise in those sections which is why the audio quality sucks.

When I wrote the script in early September 2024 the Joomla.org site headers had a single “Documentation” link pointing to docs.joomla.org. During the third week of September, when I was editing the video, the headers have finally changed. The timing, man… Anyway, there is now a dedicated Developer Resources drop-down which links directly to the Joomla! Developer Network and the Security Centre. At the time of this writing (September 18th, 2024) there is still no link to manual.joomla.org anywhere on the joomla.org properties. So, my little rant still has some merit.

Speaking of the rant, I hope you enjoyed the video editing. I am not a professional video editor by any stretch of the imagination, so I went for the good old recipe of “make it so bad it's actually good”. Loved it, or hated it? Let me know in the YouTube comments!