Augmented classes always return Value instances #5302

jasonvarga · 2022-02-17T19:16:59Z

Another developer UX PR.

Currently when call augmentation methods, you'll get Value instances if the field exists in the blueprint. Otherwise you'd just get the raw value. That made it frustrating since you'd have to do a bunch of instanceof Value checks afterwards.

In this PR, you can now always expect Value instances.

Before

Previously you'd have to do a bunch of instanceof checks for something like this:

$entry->toAugmentedCollection();

// AugmentedCollection([
//  'id' => '123',
//  'content' => Statamic\Fields\Value('the content')
//  'collection' => Statamic\Entries\Collection,
//  'published' => true,
// ]);

$entry->toAugmentedCollection()->map(function ($item) {
  return $item instanceof Value ? $item->value() : $item;
})->all();

// [
//   'id' => '123,
//   'content' => 'the content', 
//   'collection' => Statamic\Entries\Collection, 
//   'published' => true
// ]

$entry->augmentedValue('id'); // 123
$entry->augmentedValue('id')->value(); // Exception: "call to function value() on string"
$entry->augmentedValue('content'); // Statamic\Field\Value
$entry->augmentedValue('content')->value(); // "the content"

After

Now you can assume there will always be a Value.

$entry->toAugmentedCollection();

// AugmentedCollection([
//  'id' => Statamic\Fields\Value('123'),
//  'title' => Statamic\Fields\Value('the content'),
//  'collection' => Statamic\Fields\Value(Statamic\Entries\Collection),
//  'published' => Statamic\Fields\Value(true),
// ]);

$entry->toAugmentedCollection()->map->value()->all();

// [
//   'id' => '123,
//   'content' => 'the content', 
//   'collection' => Statamic\Entries\Collection, 
//   'published' => true
// ]

$entry->augmentedValue('id'); // Statamic\Field\Value
$entry->augmentedValue('id')->value(); // 123
$entry->augmentedValue('content'); // Statamic\Field\Value
$entry->augmentedValue('content')->value(); // "the content"

Breaking change

This is technically a breaking change.

If you were explicitly coding something expecting a non-Value, it will now be a Value.

For example, the entry's published value was just a boolean.

published: false

if ($entry->augmentedValue('published')) {
  // this would not run, because augmenedValue would have returned false
}

if ($entry->toAugmentedArray()['published']) {
  // ditto
}

Now:

if ($entry->augmentedValue('published')) {
  // this *will* run (but you don't want it to) because augmenedValue is now 
  // a Value instance, and in php, "if object" always return true
}

if ($entry->toAugmentedArray()['published']) {
  // ditto
}

A suggested adjustment is to avoid using these methods completely, and use the new magic properties from #5297.

if ($entry->published)

* New Antlers docs (#692) Co-authored-by: Jason Varga <jason@pixelfear.com> * Update blade doc with new `Statamic::tag()` and `Statamic::modify()` usage. (#702) * Frontend form field conditions (#691) * Document conditional fields in front-end forms. * JS. * Finish documenting custom JS drivers. * Suggest more real-world example gist, as well as a link to our built-in Alpine driver. * Tweak the intro Co-authored-by: Jack McDade <jack@jackmcdade.com> * Link to the new parser docs * Mention alternate closing tags * Refactor JSON encoding for form attributes in JS drivers (#723) * fix mobile header overflow issue. Closes #725 * Document newest PHP delimiter * Show the new new site site in the quick start guide * Delete installed.png * initial 3.3 upgrade guide * Blade variables as per statamic/cms#5201 * fix a few code examples * change per statamic/cms#5302 * Improve docs on getting data out of entries * reword * avoid the slash so the example isn't highlighted as a regex. its just an example. * wip * Rely on the automatic TOC * Update fluent tag docs with param setters (#739) * zero impact 3.3 changes * fetch and pagination example * property access * explain void * form submission data change * live preview * live preview * Remove live preview extending page - it's all covered in the regular one * at symbol can escape braces in strings and params * Laravel 8 * explain date field change * Add date where clauses * laravel upgrade guide * Tweak the L7-L8 upgrade guide * A few more tweaks * fix tpyo * enh? * Improve Blade docs * Remove caveats. * Routes and Controller examples for Blade * A little more detail up front Co-authored-by: Jason Varga <jason@pixelfear.com> Co-authored-by: Jesse Leite <jesseleite@gmail.com>

jasonvarga and others added 6 commits February 17, 2022 11:44

Augmented classes always return Value instances

11000be

Allow the method to return its own value instance

e88ba7a

wip

70805ba

remove need to check value class, it's always a value

3145f1a

Apply fixes from StyleCI

c7ba451

changelog

1524255

jasonvarga added a commit to statamic/docs that referenced this pull request Feb 17, 2022

change per statamic/cms#5302

ba4ec44

jasonvarga merged commit 38b2593 into master Feb 18, 2022

jasonvarga deleted the toaugmentedarray-values branch February 18, 2022 14:58

jasonvarga mentioned this pull request Feb 18, 2022

Use template method hotmeteor/inertia-statamic#4

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Augmented classes always return Value instances #5302

Augmented classes always return Value instances #5302

Uh oh!

jasonvarga commented Feb 17, 2022 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Augmented classes always return Value instances #5302

Augmented classes always return Value instances #5302

Uh oh!

Conversation

jasonvarga commented Feb 17, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before

After

Breaking change

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jasonvarga commented Feb 17, 2022 •

edited

Loading