Clearing up PHP APIs for 9.0
In the past few months we heard a lot of discussions (also on decisions.typo3.org) that TYPO3 Core development is too slow or too fast. After giving some thoughts to it, I think part of it is related to removing / breaking code during minor releases which is necessary but kind of in the grey zone of “according to the deprecation strategy” (= break if it is not possible, or if it unused, or does not fit the new concept) - in the future I’d like to set up a clearer deprecation strategy. However, introducing semver now would keep us from a lot of legacy code (15ys+) which still needs to be redone.
So, before coming up with a final deprecation process (which will certainly go closer to the semver approach), I think we need to make one “major” breaking change for 9.0. That is, to streamline the PHP API once and for all.
This is how it would look like
- Any PHP class which should be considered “final” from the TYPO3 Core, should also be declared final.
- Renaming classes can only happen via class aliases, which will stay until the next major version.
- Removing classes is not possible within minor versions.
PHP interfaces (tbd)
- Interfaces can only change by either introducing new interfaces or removing methods from the interface.
- Instead, new interfaces should be introduced to superseed the original interface.
PHP methods / functions
- Introduce “private” instead of marking everything as “protected” where it really makes sense
- All PHP methods which are certainly only useful for a PHP class itself, should be put to “private” instead of “protected”
- We still keep a lot of public methods which, just by marking them protected, would be breaking. Go over all public methods and mark them as protected (for XCLASSing)
- We have a lot of PHP methods where their method signature changes (= changes behaviour). When the old behaviour can not be kept, this is breaking, and should not be allowed in a minor release.
PHP class members / properties
- All properties which still come from PHP4 times should be migrated to private or protected at least, to ensure the scope.
- This might probably the heaviest load work to do.
Additional phpdoc functionality
All PHP code which should only used within TYPO3 Core (aka within sysexts) should get an @internal or @private (for public properties) and are excluded from the deprecation approach. Remove @api annotations
We still have some other open topics (mostly regarding global arrays and GET/POST variables which might be changed) but this will come at a later stage.
All work will run through me (I know, it’s a huge task, but should be done in one / two weeks full-time), and needs to be done before 9.0. I will make time available for end of september / october to do this task.
- 9.0 will be released after this change has gone through (which might be after a decision and after my work)
- Some extensions might break / XCLASSing might have impact
- If we accidentally changed a property / method from public/protected to protected/private, we can change that back again in 9.1, 9.2 etc. which gives enough time to test.
- A lot less breaking changes in the future in terms of PHP API
- A clear PHP API that is exposed to extension authors, which can be documented properly
- Officially allow private class members / methods in the TYPO3 Core (= is not meant to be XCLASSed).
- Breaking for all random edge cases that people might use TYPO3 for.
- Quite some work for me, but I’d love to do that.
I have some more proposals for the API in a separate doc, which I want to prepare as “deprecation strategy starting with 9.0” which I will continue working on if we find a general consensus on this idea.
Topic Initiator: Benni
Topic Mentor: Benni