Versioning

dbu edited this page Feb 2, 2012 · 18 revisions

We build this inside the phpcr-odm because versioning is a core feature of phpcr.

About PHPCR version support

The versioning is implemented, see https://github.com/doctrine/phpcr-odm/pull/96

A couple of nice-to-haves are not (yet) done and are recorded here in case we want to do them later. Most important is the whole version label stuff.

The admin bundle is supposed to support versions soon. See https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle/issues/12

Implementation

Annotations

  • @Document => checkpoint=manual/auto to create a version on every change
  • @Document => atLabel= to load a document at a specified label (i.e. "draft" or "stable"). this makes sense in combination with find with an explicit document name. its however a redundant method other way to make findVersionByLabel
  • Field: @Version(label=) to hold another version of this document at a specific version. (yes, yet another redundant method to get to an old version)
  • Field: @Version(allPredecessors=true) to hold the whole version history of that field (the changelog usecase) (to specific, just use the document manager for this)
  • Fields: @VersionLabels: the labels of the version this frozen document represents

Methods in DocumentManager

Get old versions

//labels will be an empty array. TODO: implement labels once jackalope implements them
public function getAllLinearVersions($document, $limit=-1)

/**
 * Returns a read-only, detached document instance of the document at the
 * specified path with the specified version label.
 *
 * Only supported with documents that have versionable=full
 * TODO: implement once jackalope supports labels
 *
 * @see findVersionByName
 */
 public function findVersionByLabel($doc, $name)

Manage labels

/**
 * Remove the label $label from the version of $doc that has that label.
 *
 * Note: this different from phpcr where you first need to retrieve the version with
 * the label and then remove the label from it. PHPCR-ODM can do this automatically for you
 *
 * Only supported with documents that have versionable=full
 * 
 * @param $label the label to remove
 * @param $doc either a string denoting the path or the document itself
 */
removeLabel($label, $doc)

/**
 * A version can have as many labels as you want, but per document version
 * history, each label may only exist once.
 *
 * Only supported with documents that have versionable=full
 * 
 * @param $label the label to add
 * @param $doc either a string denoting the path or the document itself
 * @param $name the version name (if not specified, the $doc must be a
 *      document and not a path. the version name of $doc is used)
 * @param boolean $autoremove whether to remove the label from the version
 *      history or throw an error if it already exists
 */
addLabel($label, $doc, $name=null, $autoremove=true)