Merge pull request doctrine#72 from doctrine/add-parent-annotation-wi…

…th_cleanups

Add parent annotation with cleanups

README.markdown

@@ -125,6 +125,12 @@ By default the assigned id generator is used, which requires manual assignment
 of the path to a field annotated as being the Id.
 You can tell doctrine to use a different strategy to find the id.
 
+A document id can be defined by the Nodename and the ParentDocument annotations.
+The resulting id will be the id of the parent concatenated with '/' and the
+Nodename.
+
+If you supply a ParentDocument annotation, the strategy is automatically set to parent. This strategy will check the parent and the name and will fall back to the id field if either is missing.
+
 Currently, there is the "repository" strategy which calls can be used which
 calls generateId on the repository class to give you full control how you want
 to build the path.
@@ -168,7 +174,8 @@ Available annotations
 <tr><td> Uuid:          </td><td>The unique id of this node. (only allowed if node is referenceable). </td></tr>
 <tr><td> Version:       </td><td>The version of this node, for versioned nodes. </td></tr>
 <tr><td> Node:          </td><td>The PHPCR NodeInterface instance for direct access. This is populated as soon as you register the document with the manager using persist(). (This is subject to be removed when we have mapped all functionality you can get from the PHPCR node.) </td></tr>
-<tr><td> Nodename:          </td><td>The name of the PHPCR node (this is the part of the path after the last '/' in the id). This property is read only except on document creation with the parentandname strategy. For new nodes, it is populated during the persist() operation.</td></tr>
+<tr><td> Nodename:          </td><td>The name of the PHPCR node (this is the part of the path after the last '/' in the id). This property is read only except on document creation with the parent strategy. For new nodes, it is populated during the persist() operation.</td></tr>
+<tr><td> ParentDocument:          </td><td>The parent document of this document. If a type is defined, the document will be of that type, otherwise Doctrine\ODM\PHPCR\Document\Generic will be used. This property is read only except on document creation with the parent strategy.</td></tr>
 <tr><td> Child(name=x): </td><td>Map the child with name x to this field. </td></tr>
 <tr><td> Children(filter=x): </td><td>Map the collection of children with matching name to this field. Filter is optional and works like the parameter in PHPCR Node::getNodes() (see the <a href="http://phpcr.github.com/doc/html/phpcr/nodeinterface.html#getNodes()">API</a>)</td></tr>
 <tr><td> ReferenceOne(targetDocument="myDocument", weak=false):  </td><td>Refers a document of the type myDocument. The default is a weak reference. By optionaly specifying weak=false you get a hard reference.</td></tr>

lib/Doctrine/ODM/PHPCR/Configuration.php

@@ -21,7 +21,8 @@
 
 use Doctrine\ODM\PHPCR\Mapping\Driver\Driver;
 use Doctrine\ODM\PHPCR\Mapping\Driver\BuiltinDocumentsDriver;
-use Doctrine\ODM\PHPCR\DocumentNameMapperInterface;
+use Doctrine\ODM\PHPCR\DocumentClassMapperInterface;
+use Doctrine\ODM\PHPCR\DocumentClassMapper;
 
 /**
  * Configuration class
@@ -43,7 +44,7 @@ class Configuration
         'writeDoctrineMetadata' => true,
         'validateDoctrineMetadata' => true,
         'metadataDriverImpl' => null,
-        'documentNameMapper' => null,
+        'documentClassMapper' => null,
         'proxyNamespace' => 'MyPHPCRProxyNS',
         'autoGenerateProxyClasses' => true
     );
@@ -151,21 +152,24 @@ public function getMetadataDriverImpl()
     /**
      * Gets the cache driver implementation that is used for metadata caching.
      *
-     * @return \Doctrine\ODM\PHPCR\DocumentNameMapperInterface
+     * @return \Doctrine\ODM\PHPCR\DocumentClassMapperInterface
      */
-    public function getDocumentNameMapper()
+    public function getDocumentClassMapper()
     {
-        return $this->attributes['documentNameMapper'];
+        if (empty($this->attributes['documentClassMapper'])) {
+            $this->setDocumentClassMapper(new DocumentClassMapper());
+        }
+        return $this->attributes['documentClassMapper'];
     }
 
     /**
      * Sets the cache driver implementation that is used for metadata caching.
      *
-     * @param \Doctrine\ODM\PHPCR\DocumentNameMapperInterface $documentNameMapper
+     * @param \Doctrine\ODM\PHPCR\DocumentClassMapperInterface $documentClassMapper
      */
-    public function setDocumentNameMapper(DocumentNameMapperInterface $documentNameMapper)
+    public function setDocumentClassMapper(DocumentClassMapperInterface $documentClassMapper)
     {
-        $this->attributes['documentNameMapper'] = $documentNameMapper;
+        $this->attributes['documentClassMapper'] = $documentClassMapper;
     }
 
     /**

lib/Doctrine/ODM/PHPCR/Document/File.php

@@ -18,6 +18,12 @@ class File
     /** @PHPCRODM\Node */
     protected $node;
 
+    /** @PHPCRODM\Nodename */
+    protected $nodename;
+
+    /** @PHPCRODM\ParentDocument */
+    protected $parent;
+
     /** @PHPCRODM\Date(name="jcr:created") */
     protected $created;
 
@@ -47,6 +53,48 @@ public function getId()
         return $this->id;
     }
 
+    /**
+     * The node name of the file.
+     *
+     * @return string
+     */
+    public function getNodename()
+    {
+        return $this->nodename;
+    }
+
+    /**
+     * Set the node name of the file. (only mutable on new document before the persist)
+     *
+     * @param string $name the name of the file
+     */
+    public function setNodename($name)
+    {
+        $this->nodename = $name;
+    }
+
+    /**
+     * The parent Folder document of this document.
+     *
+     * @param object $parent Folder document that is the parent of this node.
+     */
+    public function getParent()
+    {
+        return $this->parent;
+    }
+
+    /**
+     * Set the parent document of this document. Only mutable on new document
+     * before the persist.
+     *
+     * @param object $parent Document that is the parent of this node. Must be
+     *      a Folder or otherwise resolve to nt:folder
+     */
+    public function setParent($parent)
+    {
+        $this->parent = $parent;
+    }
+
     /**
      * getter for created
      * The created date is assigned by the content repository
@@ -81,7 +129,7 @@ public function setFileContentFromFilesystem($filename)
         $this->getContent();
         $stream = fopen($filename, 'rb');
         if (! $stream) {
-            throw new \Exception("File $filename not found");
+            throw new \RuntimeException("File '$filename' not found");
         }
 
         $this->content->setData($stream);

lib/Doctrine/ODM/PHPCR/Document/Folder.php

@@ -8,6 +8,9 @@
  * This class represents a Folder in the repository, aka nt:folder
  * @see http://wiki.apache.org/jackrabbit/nt:folder
  *
+ * To add files or folders to a folder, create the new File/Folder and set
+ * this document as parent, then persist the new File/Folder.
+ *
  * @PHPCRODM\Document(alias="folder", nodeType="nt:folder")
  */
 class Folder
@@ -18,6 +21,15 @@ class Folder
     /** @PHPCRODM\Node */
     protected $node;
 
+    /** @PHPCRODM\Nodename */
+    protected $nodename;
+
+    /** @PHPCRODM\ParentDocument */
+    protected $parent;
+
+    /** @PHPCRODM\Children */
+    protected $children;
+
     /** @PHPCRODM\Date(name="jcr:created") */
     protected $created;
 
@@ -44,6 +56,61 @@ public function getId()
         return $this->id;
     }
 
+
+    /**
+     * The node name of the file.
+     *
+     * @return string
+     */
+    public function getNodename()
+    {
+        return $this->nodename;
+    }
+
+    /**
+     * Set the node name of the file. (only mutable on new document before the persist)
+     *
+     * @param string $name the name of the file
+     */
+    public function setNodename($name)
+    {
+        $this->nodename = $name;
+    }
+
+    /**
+     * The parent document of this document.
+     *
+     * If there is information on the document type, the document is of the
+     * specified type, otherwise it will be a Generic document
+     *
+     * @param object $parent Document that is the parent of this node.
+     */
+    public function getParent()
+    {
+        return $this->parent;
+    }
+
+    /**
+     * Set the parent document of this document. Only mutable on new document
+     * before the persist.
+     *
+     * @param object $parent Document that is the parent of this node.
+     */
+    public function setParent($parent)
+    {
+        $this->parent = $parent;
+    }
+
+    /**
+     * The children File documents of this Folder document
+     *
+     * @return list of File documents
+     */
+    public function getChildren()
+    {
+        return $this->children;
+    }
+
     /**
      * getter for created
      * The created date is assigned by the content repository

lib/Doctrine/ODM/PHPCR/Document/Generic.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace Doctrine\ODM\PHPCR\Document;
+
+use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCRODM;
+
+/**
+ * This class represents an arbitrary node
+ *
+ * It is used as a default document, for example with the ParentDocument annotation.
+ * You can not use this to create nodes as it has no type annotation.
+ *
+ * @PHPCRODM\Document(alias="odm_generic")
+ */
+class Generic
+{
+    /** @PHPCRODM\Id */
+    protected $id;
+
+    /** @PHPCRODM\Node */
+    protected $node;
+
+    /** @PHPCRODM\Nodename */
+    protected $nodename;
+
+    /** @PHPCRODM\ParentDocument */
+    protected $parent;
+
+    /** @PHPCRODM\Children */
+    protected $children;
+
+    /** @PHPCRODM\Referrers */
+    protected $referrers;
+
+    /**
+     * Id (path) of this document
+     *
+     * @return string the id
+     */
+    public function getId()
+    {
+        return $this->id;
+    }
+
+    /**
+     * The node name of the document.
+     *
+     * @return string
+     */
+    public function getNodename()
+    {
+        return $this->nodename;
+    }
+
+    /**
+     * The parent document of this document.
+     *
+     * If there is information on the document type, the document is of the
+     * specified type, otherwise it will be a Generic document
+     *
+     * @return object Document
+     */
+    public function getParent()
+    {
+        return $this->parent;
+    }
+
+    /**
+     * The children documents of this document
+     *
+     * If there is information on the document type, the documents are of the
+     * specified type, otherwise they will be Generic documents
+     *
+     * @return object documents
+     */
+    public function getChildren()
+    {
+        return $this->children;
+    }
+
+    /**
+     * The documents having a reference to this document
+     *
+     * If there is information on the document type, the documents are of the
+     * specified type, otherwise they will be Generic documents
+     *
+     * @return string
+     */
+    public function getReferrers()
+    {
+        return $this->referrers;
+    }
+}

lib/Doctrine/ODM/PHPCR/Document/Resource.php

@@ -18,6 +18,9 @@ class Resource
     /** @PHPCRODM\Node */
     protected $node;
 
+    /** @PHPCRODM\ParentDocument */
+    protected $parent;
+
     /** @PHPCRODM\Binary(name="jcr:data") */
     protected $data;
 
@@ -33,6 +36,27 @@ class Resource
     /** @PHPCRODM\String(name="jcr:lastModifiedBy") */
     protected $lastModifiedBy;
 
+    /**
+     * The parent File document of this Resource document.
+     *
+     * @param object $parent File document that is the parent of this node.
+     */
+    public function getParent()
+    {
+        return $this->parent;
+    }
+
+    /**
+     * Set the parent document of this document. Only mutable on new document
+     * before the persist.
+     *
+     * @param object $parent Document that is the parent of this node.
+     */
+    public function setParent($parent)
+    {
+        $this->parent = $parent;
+    }
+
     /**
      * setter for the data property
      * This property stores the content of this resource