You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+10-27Lines changed: 10 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,7 +32,7 @@ This _kind of_ works, but with several drawbacks:
32
32
* One would always have to refer to the documentation (if one exists) for the "shape" of the array. This reduces both reusability and productivity.
33
33
* Static code analysis and IDE auto-completion support are greatly hindered.
34
34
35
-
Now imagine instead of using an arbitrary array, we use an object with strongly-typed properties:
35
+
Now imagine instead of using an arbitrary array, we use an object with typed properties:
36
36
37
37
```php
38
38
// UserCreationData.php
@@ -68,6 +68,10 @@ composer require eve/dto
68
68
69
69
This package requires PHP ≥7.4.
70
70
71
+
### Migrate from v1.x
72
+
73
+
v1.x versions of this library include a strict type check—for example, assigning a string to a boolean property will throw an error. Though certainly useful, this feature doesn't belong in the scope of a DTO and has been removed from v2. You're encouraged to use a static analysis tool like [PHPStan](https://github.com/phpstan/phpstan) or [Psalm](https://psalm.dev) for the task instead.
If any of the passed properties doesn't exist in the class definition or if the types don't match (notice that a non-type public property e.g., `public $whatever` accepts all types), an exception will be thrown:
120
+
If any of the passed properties doesn't exist in the class definition, an exception will be thrown:
117
121
118
122
```php
119
123
UserCreationData::make(['nope' => 'bar']); // throws "Public property $nope does not exist in class UserCreationData"
120
-
UserCreationData::make(['email' => new Foo()]); // throws 'UserCreationData::$email must be of type string, received a value of type Foo.',
121
124
```
122
125
123
126
Then we can call the `toArray()` method to transform the object into an associative array:
@@ -126,7 +129,7 @@ Then we can call the `toArray()` method to transform the object into an associat
This is especially handy e.g., if you have a method to patch a database record, as it allows the operation to be totally flexible—you can patch all properties or only a subset of them.
141
144
142
-
### Type Annotations with DocBlock
143
-
144
-
Instead of declaring your properties with built-in types, you can use type annotations with DockBlock. This is particularly useful if the property accepts multiple types—in fact, it's the only way to declare such in PHP<8. All type restrictions will be respected as normal:
145
-
146
-
```php
147
-
use Carbon\Carbon;
148
-
149
-
class NewOrderData extends \Eve\DTO\DataTransferObject
150
-
{
151
-
/**
152
-
* @var string|Carbon
153
-
*/
154
-
public $order_date;
155
-
}
156
-
157
-
NewOrderData::make(['order_date' => '2021-01-02 12:34:56']); // works
158
-
NewOrderData::make(['order_date' => Carbon::now()]); // works
eve/dto is inspired by and shares some similarities with [spatie/data-transfer-object](https://github.com/spatie/data-transfer-object) but the two packages have certain differences, the most significant of which are as follows:
209
+
Though eve/dto is inspired by and shares some similarities with [spatie/data-transfer-object](https://github.com/spatie/data-transfer-object), the two packages have certain differences, the most significant of which are as follows:
227
210
228
-
* spatie/data-transfer-object requires all not-null properties to be supplied right from instantiation. This behavior is not always feasible or desirable (refer to the data patching example above). eve/dto opts for a much more forgiving approach, which allows a DTO to be created with any subset of properties.
229
-
* spatie/data-transfer-object uses a custom RegExp to parse the docblocks. This approach is prone to bugs and has some limitations. For example, the type-hinted class must be an FQCN (Fully Qualified Class Name) i.e. `\App\Models\Author` instead of `Author`. Meanwhile, eve/dto uses the official [ReflectionDocBlock](https://github.com/phpDocumentor/ReflectionDocBlock) and [TypeResolver](https://github.com/phpDocumentor/TypeResolver) packages from phpDocumentor to deal with docblocks and therefore doesn't have these issues.
211
+
* spatie/data-transfer-object requires all not-null properties to be supplied right from instantiation. This behavior is not always feasible or desirable (refer to the data patching example above). eve/dto opts for a much more forgiving approach, which allows a DTO to be created with any subset of properties.
212
+
* spatie/data-transfer-object can't detect or prevent you from assigning a non-existent property directly (e.g., `$userData->non_existent = 'foo'`), which is something eve/dto does to help ensure your object's integrity.
230
213
* spatie/data-transfer-object implements such features as "Data Transfer Object Collection" and "Flexible Data Transfer Objects." To keep things simple and concise, eve/dto doesn't have these implementations.
0 commit comments