Ferreteria/v0.5/varstat

About

The need for this class-family arises when you have an object which contains a number of value-slots that are expected to be accessed in a variety of contexts and which may not have been assigned a value at any given time.

Experience has shown that it's a better practice to wrap {access to {internal variables and (especially) named array-elements}} with access functions, rather than making the variables themselves public. Benefits of this methodology include:

• easier debugging -- you can add messages to inform when a variable is accessed
• better visibility control -- read and write can be different (e.g. the object can write to the value, but others can only read... or vice-versa)
• better access control -- input and output values can be checked for type or range with more precision than type-hinting allows

The simple way to do this wrapping is to implement Get/Set functions. This is useful in many contexts, but:

• is awkward to propagate through additional layers of wrapping (each layer needs its own Get/Set functions for all value-slots it needs to expose).
• also requires implementing a Has wrapper-function ("is this value set?") for each value-slot that might not be set, in order to prevent PHP access errors.
  • In many cases you also want to be able to "clear" the value (unset it), requiring yet a 4th access method for each value-slot.
• leads to access-function proliferation, which makes the code harder to read.
• when the name of a variable-slot changes, this will need to be updated in 2-3 access functions -- and it's easy for a small change like that to be applied inconsistently, leading to error messages whose cause may easily be misapprehended.

This leads us to the creation of a set of value-slot-wrapper classes. At present, I'm typing up this documentation largely in an effort to better understand the needs which lead to these classes so that I can design them better as I rewrite them.

Guidelines:

• It's ok/good to fold methods from old descendant classes up into the parent class if:
  • they don't require any new fields.
  • they make sense in the context of the parent class and its descendants, even if they're only actually used in the more limited context of the old descendant class.