Every data object in Commerce extends the
comSimpleObject object. This extends the
xPDOSimpleObject class, but provides various convenience methods and under-the-hood magic to make the code easier to maintain and more flexible.
comSimpleObject object also uses feature of xPDO to allow derivative objects (basically, sub-classes of the models). This is done by setting the derivative
class_key field on an object instance, available on every object in Commerce, which then automatically loads the right object based on the class key when it is retrieved. The most common example of this feature is the
modResource object which has
modWebLink and other derivatives.
comSimpleObject - and thus all derivatives - also has a
properties field which will store a serialised array of data. This is primarily meant for extended objects that need to store some extra information, but don't need filtering/searching on that information, where a separate table would be more appropriate and performant. See the section Dealing with Properties below.
The base object provides easy access to the Commerce service class through
$this->commerce and the MODX adapter via
$this->adapter. While it also has
$this->xpdo available, we recommend using the adapter as much as possible.
For consistency in output, value formatting is done automatically in the
comSimpleObject class and its derivatives.
For applicable fields, the schema defines a
formatter which is automatically run when all object values are loaded with
$object->toArray(). The automatically formatted values are always suffixed with
_formatted, so a key of
price would be available as
$object->get('price_formatted') will also return the formatted price value.
It is also possible to manually format a value through
$object->formatValue($value, $formatter), where
$formatter is one of the formattes mentioned below.
financial: formats a number that represents a price. The value needs to be in cents. This method uses the php native
number_formatfunction, where the currency sign, decimal point and thousands separator are configurable through the Commerce system settings (
commerce.thousands_separatorrespectively). A value of
1234would in the default situation result in a formatted value of
percentage: formats a number that represents a percentage. The value is expected to be a float or a string with a period (.) to separate the decimal numbers. If the decimals are zero, it will return only the percentage (e.g.
15%), otherwise they are included with as many decimals as the provided value (e.g.
boolean: returns a translated "yes" or "no" value for a boolean-ish value (e.g. 1 or 0).
filesize: formats a number in bytes into a more human readable file size. This will look at the size to determine the right unit (GB, MB etc) and uses the
commerce.decimal_pointsetting to determine the decimal sign.
datetime: formats a unix timestamp into a full date and time string, respecting the systems locale. The default format is
%Y-%m-%d at %H:%M:%S %Zand can be configured to any strftime compatible format with the
date: formats a unix timestamp into a full date string, without the time, respecting the systems locale. The default format is
%Y-%m-%dand can be configured to any strftime compatible format with the
time: formats a unix timestamp into a time string, respecting the systems locale. The default format is
%H:%M:%S %Zand can be configured to any strftime compatible format with the
Dealing with Properties
Do not interact with the properties field directly, to ensure that if we decide to move it to a dedicated table (for, say, better indexing and searchability) your code wont break.
Instead, use the following convenience methods available on every object.
getProperty($key, [$default = null]): gets a single property as indicated by
$key, or the
$defaultvalue if it is not set.
getProperties(): returns an array of all properties that apply to the current object.
setProperty($key, [$value = null]): set a property
setProperties($properties, [$merge = true]): sets an array of properties on the current object. When
$mergeis set to false, it will overwrite existing properties. When
$merge = true, it will first array_merge the current properties.
unsetProperty($key): unsets the property indicated by
$key. This returns the value - if any - the key had prior to being unset.
unsetProperties($keys): unsets - if set - the specified keys.
$keysshould be defined like
array('key1', 'key2', 'key3'). This method will return an array of
$key => $valuepairs for each of the keys with their prior values if they had one.
If an extended object needs to store a lot of data, or if that data needs to be easily searchable or quick to filter on, it's better to define an extra object to hold that additional data, providing convenience methods (or a touch of magic in
$object->toArray()) to retrieve the data.