Support child restriction

CHANGELOG.md

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+dev-master
+----------
+
+* **2016-06-08**  [Feature] Allow children of a document to be restricted to a
+                  certain class or forbidden.
+
 1.3.1
 -----
 

composer.json

@@ -46,7 +46,7 @@
     "bin": ["bin/phpcrodm", "bin/phpcrodm.php"],
     "extra": {
         "branch-alias": {
-            "dev-master": "1.3-dev"
+            "dev-master": "1.4-dev"
         }
     }
 }

doctrine-phpcr-odm-mapping.xsd

@@ -44,6 +44,10 @@
         <xs:anyAttribute namespace="##other"/>
     </xs:complexType>
 
+    <xs:complexType name="child-class">
+        <xs:attribute name="name" type="xs:string"/>
+    </xs:complexType>
+
     <xs:complexType name="mixin">
         <xs:attribute name="type" type="xs:NMTOKEN"/>
     </xs:complexType>
@@ -138,6 +142,7 @@
             <xs:element name="document-listeners" type="phpcr:document-listeners" minOccurs="0" maxOccurs="1" />
             -->
             <xs:element name="id" type="phpcr:id" minOccurs="0" maxOccurs="1" />
+            <xs:element name="child-class" type="phpcr:child-class" minOccurs="0" maxOccurs="unbounded" />
             <xs:element name="uuid" type="phpcr:uuid" minOccurs="0" maxOccurs="1" />
             <xs:element name="locale" type="phpcr:locale" minOccurs="0" maxOccurs="1" />
             <xs:element name="field" type="phpcr:field" minOccurs="0" maxOccurs="unbounded"/>
@@ -159,6 +164,7 @@
         <xs:attribute name="translator" type="xs:NMTOKEN"/>
         <xs:attribute name="versionable" type="phpcr:versionable-type" />
         <xs:attribute name="referenceable" type="xs:boolean" default="false" />
+        <xs:attribute name="is-leaf" type="xs:boolean" default="false" />
         <xs:attribute name="node-type" type="xs:NMTOKEN" />
         <xs:attribute name="repository-class" type="xs:string"/>
         <xs:anyAttribute namespace="##other"/>

lib/Doctrine/ODM/PHPCR/Mapping/Annotations/Document.php

@@ -66,4 +66,14 @@ class Document
      * @var boolean
      */
     public $uniqueNodeType;
+
+    /**
+     * @var array
+     */
+    public $childClasses = array();
+
+    /**
+     * @var boolean
+     */
+    public $isLeaf;
 }

lib/Doctrine/ODM/PHPCR/Mapping/ClassMetadata.php

@@ -31,6 +31,7 @@
 use Doctrine\Common\ClassLoader;
 use Doctrine\Instantiator\Instantiator;
 use Doctrine\Instantiator\InstantiatorInterface;
+use Doctrine\ODM\PHPCR\Exception\OutOfBoundsException;
 
 /**
  * Metadata class
@@ -328,6 +329,23 @@ class ClassMetadata implements ClassMetadataInterface
      */
     public $parentClasses = array();
 
+    /**
+     * READ-ONLY: Child class restrictions.
+     *
+     * If empty then any classes are permitted.
+     *
+     * @var array
+     */
+    public $childClasses = array();
+
+    /**
+     * READ-ONLY: If the document should be act as a leaf-node and therefore
+     *            not be allowed children.
+     *
+     * @var boolean
+     */
+    public $isLeaf = false;
+
     /**
      * The inherited fields of this class
      *
@@ -453,6 +471,57 @@ public function validateIdentifier()
         }
     }
 
+    /**
+     * Validate that childClasses is empty if isLeaf is true.
+     *
+     * @throws MappingException if there is a conflict between isLeaf and childClasses.
+     */
+    public function validateChildClasses()
+    {
+        if (count($this->childClasses) > 0 && $this->isLeaf) {
+            throw new MappingException(sprintf(
+                'Cannot map a document as a leaf and define child classes for "%s"',
+                $this->name
+            ));
+        }
+    }
+
+    /**
+     * Assert that the given class FQN can be a child of the document this
+     * metadata represents.
+     *
+     * @param string $classFqn
+     * @throws OutOfBoundsException
+     */
+    public function assertValidChildClass(ClassMetadata $class)
+    {
+        if ($this->isLeaf()) {
+            throw new OutOfBoundsException(sprintf(
+                'Document "%s" has been mapped as a leaf. It cannot have children',
+                $this->name
+            ));
+        }
+
+        $childClasses = $this->getChildClasses();
+
+        if (0 === count($childClasses)) {
+            return;
+        }
+
+        foreach ($childClasses as $childClass) {
+            if ($class->name === $childClass || $class->reflClass->isSubclassOf($childClass)) {
+                return;
+            }
+        }
+
+        throw new OutOfBoundsException(sprintf(
+            'Document "%s" does not allow children of type "%s". Allowed child classes "%s"',
+            $this->name,
+            $class->name,
+            implode('", "', $childClasses)
+        ));
+    }
+
     /**
      * Validate whether this class needs to be referenceable.
      *
@@ -1123,6 +1192,49 @@ public function getParentClasses()
         return $this->parentClasses;
     }
 
+    /**
+     * Return the class names or interfaces that children of this document must
+     * be an instance of.
+     *
+     * @return string[]
+     */
+    public function getChildClasses()
+    {
+        return $this->childClasses;
+    }
+
+    /**
+     * Set the class names or interfaces that children of this document must be
+     * instance of.
+     *
+     * @param string[] $childClasses
+     */
+    public function setChildClasses(array $childClasses)
+    {
+        $this->childClasses = $childClasses;
+    }
+
+    /**
+     * Return true if this is designated as a leaf node.
+     *
+     * @return bool
+     */
+    public function isLeaf()
+    {
+        return $this->isLeaf;
+    }
+
+    /**
+     * Set if this document should act as a leaf node.
+     *
+     * @param bool $isLeaf
+     */
+    public function setIsLeaf($isLeaf)
+    {
+        $this->isLeaf = $isLeaf;
+    }
+
+
     /**
      * Checks whether the class will generate an id via the repository.
      *

lib/Doctrine/ODM/PHPCR/Mapping/ClassMetadataFactory.php

@@ -256,6 +256,7 @@ protected function validateRuntimeMetadata($class, $parent)
         $class->validateIdentifier();
         $class->validateReferenceable();
         $class->validateReferences();
+        $class->validateChildClasses();
         $class->validateLifecycleCallbacks($this->getReflectionService());
         $class->validateTranslatables();
 

lib/Doctrine/ODM/PHPCR/Mapping/Driver/AnnotationDriver.php

@@ -111,6 +111,12 @@ public function loadMetadataForClass($className, ClassMetadata $metadata)
             $metadata->setTranslator($documentAnnot->translator);
         }
 
+        if (array() !== $documentAnnot->childClasses) {
+            $metadata->setChildClasses($documentAnnot->childClasses);
+        }
+
+        $metadata->setIsLeaf($documentAnnot->isLeaf);
+
         foreach ($reflClass->getProperties() as $property) {
             if ($metadata->isInheritedField($property->name)
                 && $metadata->name !== $property->getDeclaringClass()->getName()

lib/Doctrine/ODM/PHPCR/Mapping/Driver/XmlDriver.php

@@ -83,6 +83,18 @@ public function loadMetadataForClass($className, ClassMetadata $class)
             $class->setUniqueNodeType((bool) $xmlRoot['uniqueNodeType']);
         }
 
+        if (isset($xmlRoot['is-leaf'])) {
+            if (!in_array($value = $xmlRoot['is-leaf'], array('true', 'false'))) {
+                throw new MappingException(sprintf(
+                    'Value of is-leaf must be "true" or "false", got "%s" for class "%s"',
+                    $value, $className
+                ));
+            }
+
+            $class->setIsLeaf($value == 'true' ? true : false);
+        }
+
+
         if (isset($xmlRoot->mixins)) {
             $mixins = array();
             foreach ($xmlRoot->mixins->mixin as $mixin) {
@@ -259,6 +271,14 @@ public function loadMetadataForClass($className, ClassMetadata $class)
             $class->mapField($mapping);
         }
 
+        if (isset($xmlRoot->{'child-class'})) {
+            $childClasses = array();
+            foreach ($xmlRoot->{'child-class'} as $requiredClass) {
+                $childClasses[] = $requiredClass['name'];
+            }
+            $class->setChildClasses($childClasses);
+        }
+
         $class->validateClassMapping();
     }
 

lib/Doctrine/ODM/PHPCR/Mapping/Driver/YamlDriver.php

@@ -255,6 +255,14 @@ public function loadMetadataForClass($className, ClassMetadata $class)
             }
         }
 
+        if (isset($element['child_classes'])) {
+            $class->setChildClasses($element['child_classes']);
+        }
+
+        if (isset($element['is_leaf'])) {
+            $class->setIsLeaf($element['is_leaf']);
+        }
+
         $class->validateClassMapping();
     }
 

lib/Doctrine/ODM/PHPCR/UnitOfWork.php

@@ -54,6 +54,7 @@
 use PHPCR\Util\PathHelper;
 use PHPCR\Util\NodeHelper;
 use Jackalope\Session as JackalopeSession;
+use Doctrine\ODM\PHPCR\Exception\OutOfBoundsException;
 
 /**
  * Unit of work class
@@ -2332,6 +2333,8 @@ private function executeInserts($documents)
             }
 
             $parentNode = $this->session->getNode(PathHelper::getParentPath($id));
+            $this->validateChildClass($parentNode, $class);
+
             $nodename = PathHelper::getNodeName($id);
             $node = $parentNode->addNode($nodename, $class->nodeType);
             if ($class->node) {
@@ -2731,6 +2734,9 @@ private function executeMoves($documents)
                 );
             }
 
+            $parentNode = $this->session->getNode(PathHelper::getParentPath($targetPath));
+            $this->validateChildClass($parentNode, $class);
+
             $this->session->move($sourcePath, $targetPath);
 
             // update fields nodename, parentMapping and depth if they exist in this type
@@ -3968,4 +3974,23 @@ public function invokeGlobalEvent($eventName, EventArgs $event)
             $this->eventManager->dispatchEvent($eventName, $event);
         }
     }
+
+    /**
+     * If the parent node has child restrictions, ensure that the given
+     * class name is within them.
+     *
+     * @param NodeInterface $parentNode
+     * @param string $classFqn
+     */
+    private function validateChildClass(NodeInterface $parentNode, ClassMetadata $class)
+    {
+        $parentClass = $this->documentClassMapper->getClassName($this->dm, $parentNode);
+
+        if (null === $parentClass) {
+            return;
+        }
+
+        $metadata = $this->dm->getClassMetadata($parentClass);
+        $metadata->assertValidChildClass($class);
+    }
 }

tests/Doctrine/Tests/Models/CMS/CmsArticleFolder.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Doctrine\Tests\Models\CMS;
+
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCRODM;
+
+/**
+ * @PHPCRODM\Document(childClasses={"Doctrine\Tests\Models\CMS\CmsArticle"})
+ */
+class CmsArticleFolder
+{
+    /**
+     * @PHPCRODM\Id
+     */
+    public $id;
+
+    /**
+     * @PHPCRODM\Children()
+     */
+    public $articles;
+}

tests/Doctrine/Tests/Models/CMS/CmsBlogFolder.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Doctrine\Tests\Models\CMS;
+
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCRODM;
+
+/**
+ * @PHPCRODM\Document(
+ *     childClasses={
+ *         "Doctrine\Tests\Models\CMS\CmsBlogPost"
+ *     }
+ * )
+ */
+class CmsBlogFolder
+{
+    /**
+     * @PHPCRODM\Id()
+     */
+    public $id;
+
+    /**
+     * @PHPCRODM\Children()
+     */
+    public $posts;
+}

tests/Doctrine/Tests/Models/CMS/CmsBlogInvalidChild.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Documents;
+
+namespace Doctrine\Tests\Models\CMS;
+
+use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCRODM;
+use Doctrine\ODM\PHPCR\DocumentRepository;
+use Doctrine\ODM\PHPCR\Id\RepositoryIdInterface;
+
+/**
+ * @PHPCRODM\Document()
+ */
+class CmsBlogInvalidChild
+{
+    /** @PHPCRODM\Id(strategy="parent") */
+    public $id;
+
+    /** @PHPCRODM\NodeName() */
+    public $name;
+
+    /** @PHPCRODM\ParentDocument() */
+    public $parent;
+}