getkirby.com
getkirby.com copied to clipboard
Annotate methods that change content files
Taking the Config
class as an example, it would be helpful if the reference noted if a setter will just virtually apply a value during runtime or if it actually writes data to the file system.
This is also interesting for interactions with pages.
Why that specific focus on whether something is written to the filesystem or not?
Some use cases:
- In a plugin I'd like to change a configuration setting on the fly but don't want the changes to be stored in the config or vice versa. It's important to know if I actually manipulate the config file or not.
- When using something like
$page->clone()
it's important to know if I create a duplicate page in memory or in the file system. - When using something like
$page->changeTitle()
I would like to know if this just changes the title "virtually" in memory (and if I have to run asave()
command to actually write the change to disk) or not.
All of this might be unambiguous when you are experienced with the system (and the specific classes and methods) but it's not when you are a beginner as I know from experience of learning things the hard way.