Skip to content

Commit 255d7e6

Browse files
author
Andrew Eddie
committed
Added Data package
1 parent b79e348 commit 255d7e6

File tree

3 files changed

+199
-0
lines changed

3 files changed

+199
-0
lines changed

‎manual/en-US/chapters/packages/data.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
## The Data Package
2+
3+
### JData
4+
5+
`JData` is a class that is used to store data but allowing you to access the data by mimicking the way PHP handles class properties. Rather than explicitly declaring properties in the class, `JData` stores virtual properties of the class in a private internal array. Concrete properties can still be defined but these a separate from the data.
6+
7+
#### Construction
8+
9+
The constructor for a new `JData` object can optionally take an array or an object. The keys of the array, or the properties of the object will be bound to the properties of the `JData` object.
10+
11+
```php
12+
// Create an empty object.
13+
$object1 = new JData;
14+
15+
// Create an object with data. You can use an array or another object.
16+
$data = array(
17+
'foo' => 'bar',
18+
);
19+
20+
$object2 = new JData($data);
21+
22+
// The following should echo "bar".
23+
echo $object2->foo;
24+
```
25+
26+
#### General Usage
27+
28+
`JData` includes magic getters and setters to provide access to the internal property store as if they were explicitly declared properties of the class.
29+
30+
The `bind` method allows for injecting an existing array or object into the `JData` object.
31+
32+
The `dump` method gets a plain `stdClass` version of the `JData` object's properties. It will also support recursion to a specified number of levels where the default is 3 and a depth of 0 would return a `stdClass` object with all the properties in native form. Note that the `dump` method will only return virtual properties set binding and magic methods. It will not include any concrete properties defined in the class itself.
33+
34+
The `JsonSerializable` interface is implemented. This method proxies to the `dump` method (defaulting to a recursion depth of 3). Note that this interface only takes effect implicitly in PHP 5.4 so any code built for PHP 5.3 needs to explicitly use either the `jsonSerialize` or the `dump` method before passing to `json_encode`.
35+
36+
The `JData` class also implements the `IteratorAggregate` interface so it can easily be used in a `foreach` statement.
37+
38+
```php
39+
// Create an empty object.
40+
$object = new JData;
41+
42+
// Set a property.
43+
$object->foo = 'bar';
44+
45+
// Get a property.
46+
$foo = $object->foo;
47+
48+
// Binding some new data to the object.
49+
$object->bind(array('goo' => 'car');
50+
51+
// Get a plain object version of the JData.
52+
$stdClass = $object->dump();
53+
54+
// Set a property with a default value if it is not already set.
55+
$object->def('foo', 'oof');
56+
57+
// An alternative technique to get a value or a default.
58+
$foo = $object->foo ?: 'The default';
59+
60+
// Iterate over the properties as if the object were a real array.
61+
foreach ($object as $key => $value)
62+
{
63+
echo "\n$key = $value";
64+
}
65+
66+
if (version_compare(PHP_VERSION, '5.4') >= 0)
67+
{
68+
// PHP 5.4 is aware of the JsonSerializable interface.
69+
$json = json_encode($object);
70+
}
71+
else
72+
{
73+
// Have to do it the hard way to be compatible with PHP 5.3.
74+
$json = json_encode($object->jsonSerialize());
75+
}
76+
```
77+
78+
### JDataSet
79+
80+
`JDataSet` is a collection class that allows the developer to operate on a list of `JData` objects as if they were in a typical PHP array (`JDataSet` implements the `ArrayAccess`, `Countable` and `Iterator` interfaces).
81+
82+
#### Construction
83+
84+
A typical `JDataSet` object will be instantiated by passing an array of `JData` objects in the constructor.
85+
86+
```php
87+
// Create an empty object.
88+
$players = new JDataSet(
89+
array(
90+
new JData(array('race' => 'Elf', 'level' => 1)),
91+
new JData(array('race' => 'Chaos Dwarf', 'level' => 2)),
92+
)
93+
);
94+
```
95+
96+
#### General Usage
97+
98+
Array elements can be manipulated with the `offsetSet` and `offsetUnset` methods, or by using PHP array nomenclature.
99+
100+
The magic `__get` method in the `JDataSet` class effectively works like a "get column" method. It will return an array of values of the properties for all the objects in the list.
101+
102+
The magic `__set` method is similar and works like a "set column" method. It will set all a value for a property for all the objects in the list.
103+
104+
```php
105+
// Add a new element to the end of the list.
106+
$players[] => new JData(array('race' => 'Skaven', 'level' => 2));
107+
108+
// Add a new element with an associative key.
109+
$players['captain'] => new JData(array('race' => 'Human', 'level' => 3));
110+
111+
// Get a keyed element from the list.
112+
$captain = $players['captain'];
113+
114+
// Set the value of a property for all objects. Upgrade all players to level 4.
115+
$players->level = 4;
116+
117+
// Get the value of a property for all object and also the count (get the average level).
118+
$average = $players->level / count($players);
119+
```
120+
121+
`JDataSet` supports magic methods that operate on all the objects in the list. Calling an arbitrary method will iterate of the list of objects, checking if each object has a callable method of the name of the method that was invoked. In such a case, the return values are assembled in an array forming the return value of the method invoked on the `JDataSet` object. The keys of the original objects are maintained in the result array.
122+
123+
```php
124+
/**
125+
* A custom JData.
126+
*
127+
* @package Joomla\Examples
128+
* @since 12.1
129+
*/
130+
class PlayerObject extends JData
131+
{
132+
/**
133+
* Get player damage.
134+
*
135+
* @return integer The amount of damage the player has received.
136+
*
137+
* @since 12.1
138+
*/
139+
public function hurt()
140+
{
141+
return (int) $this->maxHealth - $this->actualHealth;
142+
}
143+
}
144+
145+
$players = new JDataSet(
146+
array(
147+
// Add a normal player.
148+
new PlayerObject(array('race' => 'Chaos Dwarf', 'level' => 2,
149+
'maxHealth' => 40, 'actualHealth' => '32')),
150+
// Add an invincible player.
151+
new JData(array('race' => 'Elf', 'level' => 1)),
152+
)
153+
);
154+
155+
// Get an array of the hurt players.
156+
$hurt = $players->hurt();
157+
158+
if (!empty($hurt))
159+
{
160+
// In this case, $hurt = array(0 => 8);
161+
// There is no entry for the second player
162+
// because that object does not have a "hurt" method.
163+
foreach ($hurt as $playerKey => $player)
164+
{
165+
// Do something with the hurt players.
166+
}
167+
};
168+
```
169+
170+
### JDataDumpable
171+
172+
`JDataDumpable` is an interface that defines a `dump` method for dumping the properties of an object as a `stdClass` with or without recursion.
173+
174+
### Revision History
175+
176+
The `JData` and `JDataSet` classes were introduced in version 12.3 of the Joomla Platform.

‎manual/en-US/chapters/packages/object.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## The Object Package
2+
3+
### Revision History
4+
5+
The `JObject` class was introduced in version 1.5 of the Joomla CMS and formed part of version 11.1 of the Joomla Platform.
6+
7+
Its primary use was to provide some features that were not present in PHP4:
8+
9+
* an anonymous constructor,
10+
* getters and setters, and
11+
* toString.
12+
13+
It was used as a basic object instead of the basic PHP object `stdClass` (hence the name `JObject`). Many classes in the whole Joomla Framework were derived from it because it provided the PHP 5-like functionality and compatibility. Because JObject was ubiquitous in the framework it was a handy place to handle errors in times before exception handling was available.
14+
15+
The following method was removed in version 12.3:
16+
17+
* `__toString`
18+
19+
The following methods are marked as deprecated and will be removed in 13.1:
20+
21+
* `getError` & `getErrors` - Throw exceptions instead of relying on these methods.

‎manual/en-US/menu.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
- Chapters
22
- [Introductions](chapters/introduction.md)
33
- [JCrypt](chapters/packages/crypt.md)
4+
- [JData](chapters/packages/data.md)
45
- [JDatabase](chapters/packages/database.md)
56
- [JGithub](chapters/packages/github.md)
67
- [JGoogle](chapters/packages/google.md)
@@ -9,6 +10,7 @@
910
- [JKeychain](chapters/packages/keychain.md)
1011
- [JLog](chapters/packages/log.md)
1112
- [MVC](chapters/packages/mvc.md)
13+
- [JObject](chapters/packages/object.md)
1214
- [JProfiler](chapters/packages/profiler.md)
1315
- [Testing](chapters/testing.md)
1416

0 commit comments

Comments
 (0)