Saving values in PHP
The facade that reads an entry's values also writes them, one fieldset at a time. Use it when your own code collects the values: a front-end form, an import, a button that changes one field.
php
$book = \VxFramework\Post::get( $post_id );
$result = $book->update_fieldset_values( 'book_details', [
'tagline' => 'A new edition',
] );
if ( ! $result['ok'] ) {
// $result['code'] says why.
}\VxFramework\Term and \VxFramework\User save the same way. So do \VxFramework\Comment and \VxFramework\Option_Page.
Some fields, or the whole fieldset
There are two methods. They differ in what happens to the fields you leave out:
| Method | A field you leave out | A field you send empty |
|---|---|---|
update_fieldset_values() | keeps its value | is cleared |
save_fieldset_values() | is cleared | is cleared |
Use update_fieldset_values() to change some fields of an entry that already has values. Use save_fieldset_values() when you hold every value of the fieldset, as a form showing all of its fields does.
Keys the fieldset has no field for are ignored by both.
What comes back
Both return an array, and ok says whether the save went through:
php
[
'ok' => true,
'values' => [ 'tagline' => 'A new edition' ],
'warnings' => [],
]valueslists each field the save wrote, with the value it holds now. That is not always the value you sent: text is cleaned, and a selection longer than the field allows is cut. Compare it with what you sent to see what changed.warningslists values that broke one of the field's rules and were saved anyway. Each has apath, acodeand amessage. Saving and validation explains which problems are warnings.- When
okis false, nothing was stored.codeisnot_foundfor an unknown fieldset,not_assignedwhen the fieldset doesn't apply to this entry, andvalidation_failed, with anerrorslist, for a value that can't be stored at all, such as a file of a type the field doesn't allow.
A Post Relation or User Relation field checks every link against its settings and against what the current user may see, and drops the ones that don't fit. values holds the links it kept.
Limits
- VX checks the values, not the person. Neither method asks whether the current user may edit the entry. Check that first, with
current_user_can( 'edit_post', $post_id )or a rule of your own. That also makes these the methods to save with on behalf of someone who isn't an administrator, such as a member editing their own post from the front end, once your code has decided they may. - A fieldset whose Location has a Viewer role or Viewer capability condition applies only to those people. A save by anyone else is refused as
not_assigned. - A field that conditional logic hides is not stored.
update_fieldset_values()adds ahidden_by_conditionswarning when you send one. - Values arriving from
$_POSTare slashed by WordPress. Pass them throughwp_unslash()first.
Related
Technical details for LLMs
- Methods:
save_fieldset_values( string $fieldset_key, array $values )andupdate_fieldset_values( string $fieldset_key, array $values )on\VxFramework\Post,TermandUser.$valuesis keyed by top-level field key; a group or repeater is sent whole. - Success:
{ ok: true, values: { key: value }, warnings: [ { path, code, message } ] }.valueshas one key per field written: every visible data field forsave_fieldset_values(), only the keys sent forupdate_fieldset_values(). - Failure:
{ ok: false, code, message?, errors?, status? }. Codes:not_found,unsupported_target,entity_not_found,not_assigned,validation_failed(errorsas warnings are shaped),storage_write_failed. - Empty: a value that is empty for its field type deletes the stored value.
nullclears any field, a Switcher included. - Conditional logic: a full save reads conditions from the submitted values; a partial save reads them from the stored values with the submitted ones on top. A hidden field is skipped, never cleared.
- A Taxonomy field in
native_metaboxmode is left alone bysave_fieldset_values()unless its key is sent.