|
| 1 | +# MagicPropertiesTrait |
| 2 | + |
| 3 | +`MagicPropertiesTrait` allows to use magic getters and setters to access model properties and relations. |
| 4 | +It stores properties in the `private array $propertyValues` property and provides magic methods for accessing them. |
| 5 | + |
| 6 | +It also allows to call getter and setter methods as a property if they are defined in the model class |
| 7 | +(e.g. `getFullName()` and `setFullName($fullName)` for `fullName` property). |
| 8 | + |
| 9 | +> [!NOTE] |
| 10 | +> This trait is not required when using private, protected, public or dynamic properties. |
| 11 | +
|
| 12 | +> [!IMPORTANT] |
| 13 | +> - ✔️ It allows accessing relations as properties; |
| 14 | +> - ❌ It doesn't use strict typing and can be a reason of hard-to-detect errors; |
| 15 | +> - ❌ It is slower than explicitly defined properties, it is not optimized by PHP opcache and uses more memory. |
| 16 | +> Sometimes it can be 100 times slower than explicitly defined properties; |
| 17 | +
|
| 18 | +## Methods |
| 19 | + |
| 20 | +The following methods are provided by the `MagicPropertiesTrait`: |
| 21 | + |
| 22 | +- `__get()` retrieves the value of the specified property or relation using magic getter; |
| 23 | +- `__set()` sets the value of the specified property or relation using magic setter; |
| 24 | +- `__isset()` checks if the specified property or relation exists and is not null using magic isset; |
| 25 | +- `__unset()` unsets or sets to null the specified property or relation using magic unset; |
| 26 | +- `hasRelationQuery()` checks if the specified relation query exists; |
| 27 | +- `isProperty()` checks if the specified property exists; |
| 28 | +- `canGetProperty()` checks if the specified property can be gotten; |
| 29 | +- `canSetProperty()` checks if the specified property can be set. |
| 30 | + |
| 31 | +## Usage |
| 32 | + |
| 33 | +```php |
| 34 | +use Yiisoft\ActiveRecord\ActiveRecord; |
| 35 | +use Yiisoft\ActiveRecord\Trait\MagicPropertiesTrait; |
| 36 | + |
| 37 | +/** |
| 38 | + * Entity User. |
| 39 | + * |
| 40 | + * @property int $id |
| 41 | + * @property string $firstName |
| 42 | + * @property string $lastName |
| 43 | + * @property string $fullName |
| 44 | + * |
| 45 | + * The properties in PHPDoc are optional and used by static analysis and by IDEs for autocompletion, type hinting, |
| 46 | + * code generation, and inspection tools. This doesn't affect code execution. |
| 47 | + **/ |
| 48 | +final class User extends ActiveRecord |
| 49 | +{ |
| 50 | + use MagicPropertiesTrait; |
| 51 | + |
| 52 | + public function getProfileQuery(): ActiveQueryInterface |
| 53 | + { |
| 54 | + return $this->hasOne(Profile::class, ['id' => 'profile_id']); |
| 55 | + } |
| 56 | + |
| 57 | + public function getFullName(): string |
| 58 | + { |
| 59 | + return $this->firstName . ' ' . $this->lastName; |
| 60 | + } |
| 61 | + |
| 62 | + public function setFullName(string $fullName): void |
| 63 | + { |
| 64 | + [$this->firstName, $this->lastName] = explode(' ', $fullName, 2); |
| 65 | + } |
| 66 | +} |
| 67 | + |
| 68 | +$user = new User(); |
| 69 | +$user->firstName = 'John'; // Set the property value using magic setter |
| 70 | +$user->fullName = 'John Smith'; // Set the property values using setter method |
| 71 | +echo $user->firstName; // Get the property value using magic getter |
| 72 | +echo $user->fullName; // Get the property value using getter method |
| 73 | +unset($user->firstName); // Unset the property or set it to null using magic unset |
| 74 | +isset($user->firstName); // Check if the property exists and is not null using magic isset |
| 75 | + |
| 76 | +$user->hasRelationQuery('profile') // Check if the relation query exists |
| 77 | +$user->isProperty('fullName') // Check if the property exists (can be read or set) |
| 78 | +$user->canGetProperty('fullName') // Check if the property can be read |
| 79 | +$user->canSetProperty('fullName'); // Check if the property can be set |
| 80 | +``` |
| 81 | + |
| 82 | +Usually `MagicPropertiesTrait` and [MagicRelationsTrait](magic-relations.md) are used together to provide full magic functionality |
| 83 | +for properties and relations. |
| 84 | + |
| 85 | +```php |
| 86 | +final class User extends ActiveRecord |
| 87 | +{ |
| 88 | + use MagicPropertiesTrait; |
| 89 | + use MagicRelationsTrait; |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +See more how to [Create Active Record Model](../create-model.md). |
| 94 | + |
| 95 | +Back to [Extending Functionality With Traits](traits.md). |
0 commit comments