Skip to content

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:

MethodA field you leave outA field you send empty
update_fieldset_values()keeps its valueis cleared
save_fieldset_values()is clearedis 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' => [],
]
  • values lists 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.
  • warnings lists values that broke one of the field's rules and were saved anyway. Each has a path, a code and a message. Saving and validation explains which problems are warnings.
  • When ok is false, nothing was stored. code is not_found for an unknown fieldset, not_assigned when the fieldset doesn't apply to this entry, and validation_failed, with an errors list, 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 a hidden_by_conditions warning when you send one.
  • Values arriving from $_POST are slashed by WordPress. Pass them through wp_unslash() first.
Technical details for LLMs
  • Methods: save_fieldset_values( string $fieldset_key, array $values ) and update_fieldset_values( string $fieldset_key, array $values ) on \VxFramework\Post, Term and User. $values is keyed by top-level field key; a group or repeater is sent whole.
  • Success: { ok: true, values: { key: value }, warnings: [ { path, code, message } ] }. values has one key per field written: every visible data field for save_fieldset_values(), only the keys sent for update_fieldset_values().
  • Failure: { ok: false, code, message?, errors?, status? }. Codes: not_found, unsupported_target, entity_not_found, not_assigned, validation_failed (errors as warnings are shaped), storage_write_failed.
  • Empty: a value that is empty for its field type deletes the stored value. null clears 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_metabox mode is left alone by save_fieldset_values() unless its key is sent.

Documentation for the VX Framework.