Problem/Motivation
Project Browser 2.0.0-beta1 will mark the official start of the PHP API, which means we can't break backwards compatibility anymore. Therefore, we need to make it very clear what parts of the PHP code are supposed to be implemented/overridden/extended/used by external code, and which parts are internal and off-limits.
Proposed resolution
Mark every single PHP class in Project Browser with @internal
or @api
, depending on how we intend for hackers to use it.
Tests are excluded from this; they are always internal by default. Our test traits are API. Interfaces, base classes, and public services are also API. Only API classes can have protected methods and properties (although private should be used unless there's a specific reason for something to be protected).
Everything else is internal. Forms are internal, as are plugin implementations. All classes should be final
unless they are abstract base classes that are meant to be extended. All our asset libraries should also be internal, and following core's example, they should be prefixed with internal
(e.g., project_browser/internal.svelte
).
The API classes should have an explainer reading something like:
@api
This class is covered by our backwards compatibility promise and can be safely relied upon.
And the internal classes should say something like:
@internal
This is an internal part of Project Browser and may be changed or removed at any time. It should not be used by external code.