final protected function &_getProperty(
        $propName,
        $createMissingValue = false)
    {
        // Check if the property exists in class/data and get its definition.
        $propDef = $this->_getPropertyDefinition($propName); // Throws.

        // Assign the appropriate reference to the "$value" variable.
        if (array_key_exists($propName, $this->_objectData)) {
            // The value exists in the data, so refer directly to it.
            $value = &$this->_objectData[$propName]; // IMPORTANT: By reference!
        } elseif ($createMissingValue) {
            // No value exists in data yet, AND the caller wants us to create
            // a default NULL value for the data property in that situation.
            // NOTE: This is IMPORTANT so that the returned "default NULL"
            // by-reference value will refer to the correct internal data
            // array entry instead of to an unrelated, temporary variable.
            // NOTE: The downside to this is that we'll fill the object's
            // internal data storage with a bunch of default "NULL" values,
            // which increases memory needs and messes with the "to JSON"
            // output functions later. But it's unavoidable. We obviously
            // CANNOT return a real reference to an internal data entry
            // unless we CREATE the entry. So we MUST unfortunately do it!
            // NOTE: This "pollution" is only a problem if the caller intends
            // to use the property by reference, which isn't the case for
            // default __call() (the virtual functions), but IS necessary
            // in the default __get() (direct property access by reference).
            $this->_objectData[$propName] = null;

            // Now just link to the data array entry we just added.
            $value = &$this->_objectData[$propName]; // IMPORTANT: By reference!
            return $value; // OPTIMIZATION: Skip convert() for missing data.
        } else {
            // No value exists in data yet, but the caller didn't want us to set
            // the missing value. So we'll simply use a default NULL variable.
            // NOTE: If the caller tries to write to this one by reference,
            // they'll just modify this temporary variable instead of the
            // internal data. To link to real they MUST $createMissingValue.
            // NOTE: We MUST return a variable, since "return null" is illegal.
            $value = null; // Copy-on-write. Temporary variable to be returned.
            return $value; // OPTIMIZATION: Skip convert() for missing data.
        }

        // Map the value to the appropriate type and validate it.
        ValueConverter::convert( // Throws.
            ValueConverter::CONVERT_FROM_INTERNAL,
            $value, $propDef->arrayDepth, $propName, $propDef
        );

        // Whatever $value points at will now be returned by-reference.
        return $value; // By-reference due to &function signature.
    }
final protected function &_getProperty(
        $propName,
        $createMissingValue = false)
    {
        // Check if the property exists in class/data and get its definition.
        $propDef = $this->_getPropertyDefinition($propName); // Throws.

        // Assign the appropriate reference to the "$value" variable.
        if (array_key_exists($propName, $this->_objectData)) {
            // The value exists in the data, so refer directly to it.
            $value = &$this->_objectData[$propName]; // IMPORTANT: By reference!
        } elseif ($createMissingValue) {
            // No value exists in data yet, AND the caller wants us to create
            // a default NULL value for the data property in that situation.
            // NOTE: This is IMPORTANT so that the returned "default NULL"
            // by-reference value will refer to the correct internal data
            // array entry instead of to an unrelated, temporary variable.
            // NOTE: The downside to this is that we'll fill the object's
            // internal data storage with a bunch of default "NULL" values,
            // which increases memory needs and messes with the "to JSON"
            // output functions later. But it's unavoidable. We obviously
            // CANNOT return a real reference to an internal data entry
            // unless we CREATE the entry. So we MUST unfortunately do it!
            // NOTE: This "pollution" is only a problem if the caller intends
            // to use the property by reference, which isn't the case for
            // default __call() (the virtual functions), but IS necessary
            // in the default __get() (direct property access by reference).
            $this->_objectData[$propName] = null;

            // Now just link to the data array entry we just added.
            $value = &$this->_objectData[$propName]; // IMPORTANT: By reference!
            return $value; // OPTIMIZATION: Skip convert() for missing data.
        } else {
            // No value exists in data yet, but the caller didn't want us to set
            // the missing value. So we'll simply use a default NULL variable.
            // NOTE: If the caller tries to write to this one by reference,
            // they'll just modify this temporary variable instead of the
            // internal data. To link to real they MUST $createMissingValue.
            // NOTE: We MUST return a variable, since "return null" is illegal.
            $value = null; // Copy-on-write. Temporary variable to be returned.
            return $value; // OPTIMIZATION: Skip convert() for missing data.
        }

        // Map the value to the appropriate type and validate it.
        ValueConverter::convert( // Throws.
            ValueConverter::CONVERT_FROM_INTERNAL,
            $value, $propDef->arrayDepth, $propName, $propDef
        );

        // Whatever $value points at will now be returned by-reference.
        return $value; // By-reference due to &function signature.
    }
final protected function & _getProperty ( $ propName , $ createMissingValue = false ) { // Check if the property exists in class/data and get its definition. $ propDef = $ this -> _getPropertyDefinition ( $ propName ) ; // Throws. // Assign the appropriate reference to the "$value" variable. if ( array_key_exists ( $ propName , $ this -> _objectData ) ) { // The value exists in the data, so refer directly to it. $ value = & $ this -> _objectData [ $ propName ] ; // IMPORTANT: By reference! } elseif ( $ createMissingValue ) { // No value exists in data yet, AND the caller wants us to create // a default NULL value for the data property in that situation. // NOTE: This is IMPORTANT so that the returned "default NULL" // by-reference value will refer to the correct internal data // array entry instead of to an unrelated, temporary variable. // NOTE: The downside to this is that we'll fill the object's // internal data storage with a bunch of default "NULL" values, // which increases memory needs and messes with the "to JSON" // output functions later. But it's unavoidable. We obviously // CANNOT return a real reference to an internal data entry // unless we CREATE the entry. So we MUST unfortunately do it! // NOTE: This "pollution" is only a problem if the caller intends // to use the property by reference, which isn't the case for // default __call() (the virtual functions), but IS necessary // in the default __get() (direct property access by reference). $ this -> _objectData [ $ propName ] = null ; // Now just link to the data array entry we just added. $ value = & $ this -> _objectData [ $ propName ] ; // IMPORTANT: By reference! return $ value ; // OPTIMIZATION: Skip convert() for missing data. } else { // No value exists in data yet, but the caller didn't want us to set // the missing value. So we'll simply use a default NULL variable. // NOTE: If the caller tries to write to this one by reference, // they'll just modify this temporary variable instead of the // internal data. To link to real they MUST $createMissingValue. // NOTE: We MUST return a variable, since "return null" is illegal. $ value = null ; // Copy-on-write. Temporary variable to be returned. return $ value ; // OPTIMIZATION: Skip convert() for missing data. } // Map the value to the appropriate type and validate it. ValueConverter :: convert ( // Throws. ValueConverter :: CONVERT_FROM_INTERNAL , $ value , $ propDef -> arrayDepth , $ propName , $ propDef ) ; // Whatever $value points at will now be returned by-reference. return $ value ; // By-reference due to &function signature. }
Get the value of an object data property.

This function automatically reads the object instance's data and converts
the value to the correct type on-the-fly. If that part of the data-array
is an object, it will be lazy-created the first time it's requested.

`NOTE:` If the object instance's internal data doesn't contain a value, but
it's listed in the class property definition, then it will be treated as
missing and `NULL` will automatically be returned instead. However, if
it's missing from the class definition AND the object instance's data,
then it's treated as an invalid property and an exception is thrown.

Because of the fact that the default return value for internally-missing
but "class-valid" properties is `NULL`, it means that you cannot discern
whether the `NULL` came from actual JSON data or from the default return
value. However, if that distinction matters to you, you should simply
call `_hasPropertyData()` before retrieving the value.

`IMPORTANT:` This function performs return-by-reference, which was done
in order to allow certain ADVANCED programming tricks by the caller. If
you save our return value by reference, you'll then have a direct link to
the internal data for that property and can write directly to it
(including writing invalid data if you want to, since we cannot verify
what you do with your reference). However, you A) don't have to worry
about invalid data, because it will all get validated at the next
`_getProperty()` call again, and B) you have to explicitly bind the
returned value by reference to actually risk affecting the internal
data, as explained below.

Method 1 (recommended for almost 100% of all usages, safest):

```php
$val = $this->_getProperty('foo'); // Copy-on-write assignment to $val.
$val = 'bar'; // Does NOT modify the internal data "foo" property.
```

Method 2 (dangerous, and this example even contains an intentional bug):

```php
$val = &$this->_getProperty('foo'); // Reference assignment to $val.
$val = 'bar'; // Direct link, thus modifies the internal "foo" property.
```

`SERIOUS WARNING:` If you use Method 2, do NOT use the code above. It was
just explained that way to demonstrate a SERIOUS MISTAKE. If you assign
by reference, you obviously intend to link directly to internal data. But
the code above fails if no internal data for that property exists yet. In
that case, the code above will write to a temporary `NULL` variable which
is not linked at all to the object. Instead, you MUST ALWAYS use
`$createMissingValue = true` if you want TRUSTABLE data references.

Method 2 (the CORRECT way of writing it):

```php
$val = &$this->_getProperty('foo', true);
$val = 'bar';
```

That FIXED code will create the property and put `NULL` in it if it's
missing from the internal data, and then returns the reference to the
created internal data entry. It's the ONLY way to ensure REAL references.

Note that there is ZERO PERFORMANCE BENEFIT of assigning our return-value
by reference. ONLY use references if you have an ADVANCED reason for it!
Internally, PHP treats both assignment types identically until the moment
you try to write to/modify the contents of the variable. So if you are
only reading, which is most of the time, then there's no reason to use a
reference. And never forget that modifying via direct reference lets you
write invalid data (which won't be detected until a `_getProperty()`
call attempts to read that bad data again), as mentioned earlier.

There is one final warning: If YOU have a "return-by-reference" function,
then you will AUTOMATICALLY return a direct link to the inner data if you
use us directly in your return statement. Here's an example of that:

```php
public function &myFunction() { // <-- Note the "&" return-by-ref here!
// returns reference to real internal data OR temp var (badly coded)
return $this->_getProperty('foo'); // <-- VERY DANGEROUS BUG!

// returns reference to real internal data (correctly coded)
return $this->_getProperty('foo', true); // <-- CORRECT!

// you can also intentionally break the link to the internal data,
// by putting it in a copy-on-write variable and returning THAT:
$copyOnWrite = $this->_getProperty('foo'); // copy-on-write (no ref)
return $copyOnWrite; // ref to $copyOnWrite but not to real internal
}
```

@param string $propName           The property name.
@param bool   $createMissingValue If `TRUE` then we will create missing
internal object data entries (for
class-defined properties) and store a
`NULL` in them. This will "pollute" the
internal data with default `NULL`s for
every missing property that you attempt
to retrieve, but it's totally NECESSARY
if you intend to use the return-value
by-reference, since we MUST store the
value internally when you want the
returned reference to link to our
actual object's internal data storage!

@throws LazyJsonMapperException If the value can't be turned into its
assigned class or built-in PHP type, or
if the property doesn't exist in either
the class property definition or the
object instance's data.

@return mixed The value as the correct type, or `NULL` if it's either a
literal `NULL` in the data or if no value currently existed
in the internal data storage at all. Note that this
function returns the value by-reference.
Get the value of an object data property .