Merge pull request #700 from driehle/feature/form-builder-docs

Added docs for `EntityBasedFormBuilder`

Author: driehle

LICENSE renamed to LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2021 Doctrine Project
+Copyright (c) 2006-2022 Doctrine Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
 documentation files (the "Software"), to deal in the Software without restriction, including without limitation

docs/en/developer-tools.rst

@@ -1,5 +1,5 @@
 Laminas Developer Tools in DoctrineORMModule
-=========================================
+============================================
 
 If you ever tried `Laminas Developer
 Tools <https://github.com/laminas/laminas-developer-tools>`__ you will

docs/en/forms.rst

@@ -0,0 +1,74 @@
+Laminas Forms
+=============
+
+DoctrineModule and DoctrineORMModule provide an integration with `laminas-form <https://docs.laminas.dev/laminas-form/>`_.
+
+Creating Forms using Entity Annotations
+---------------------------------------
+
+With laminas-form, forms can be created using `PHP8 attributes or DocBlock annotations <https://docs.laminas.dev/laminas-form/v3/form-creation/attributes-or-annotations/>`_.
+DoctrineORMModule extends this feature to support Doctrine-specific form elements (see next section).
+
+First, create a form builder instance. By default, this uses the ``AnnotationBuilder`` from laminas-form,
+which uses DocBlock annotations. Alternatively, you can provide an ``AttributeBuilder`` to use PHP8-style
+attributes.
+
+.. code:: php
+
+    // using PhpDoc annotations
+    $entityManager = $container->get(\Doctrine\ORM\EntityManager::class);
+    $builder = new \DoctrineORMModule\Form\Annotation\EntityBasedFormBuilder($entityManager);
+
+    // alternatively, to use PHP8 attributes
+    $entityManager = $container->get(\Doctrine\ORM\EntityManager::class);
+    $attributeBuilder = new \Laminas\Form\Annotation\AttributeBuilder();
+    $builder = new \DoctrineORMModule\Form\Annotation\EntityBasedFormBuilder($entityManager, $attributeBuilder);
+
+Given an entity instance, the form builder can either create a form specification or directly a form instance:
+
+.. code:: php
+
+    $entity = new User();
+
+    // get form specification only
+    $formSpec = $builder->getFormSpecification($entity);
+
+    // or directly get form
+    $form= $builder->createForm($entity);
+
+Extension points for customizing the form builder are the event manager and the form factory, which can
+be accessed as follows:
+
+.. code:: php
+
+    // if you need access to the event manager
+    $myListener = new MyListener();
+    $myListener->attach($builder->getBuilder()->getEventManager());
+
+    // if you need access to the form factory
+    $formElementManager = $container->get(\Laminas\Form\FormElementManager::class)
+    $builder->getBuilder()->getFormFactory()->setFormElementManager($formElementManager);
+
+Doctrine-specific Form Elements
+-------------------------------
+
+DoctrineModule provides three Doctrine-specific form elements:
+
+- ``DoctrineModule\Form\Element\ObjectSelect``
+- ``DoctrineModule\Form\Element\ObjectRadio``
+- ``DoctrineModule\Form\Element\ObjectMultiCheckbox``
+
+Please read the `DoctrineModule documentation on form elements <https://www.doctrine-project.org/projects/doctrine-module/en/current/form-element.html>`_
+for further information.
+
+Doctrine-specific Validators
+----------------------------
+
+DoctrineModule provides three Doctrine-specific validators:
+
+- ``DoctrineModule\Validator\ObjectExists``
+- ``DoctrineModule\Validator\NoObjectExists``
+- ``DoctrineModule\Validator\UniqueObject``
+
+Please read the `DoctrineModule documentation on validators <https://www.doctrine-project.org/projects/doctrine-module/en/current/validator.html>`_
+for further information.

docs/en/index.rst

@@ -59,4 +59,5 @@ Next Steps
     configuration
     cache
     migrations
+    forms
     miscellaneous

docs/en/miscellaneous.rst

@@ -4,31 +4,6 @@ Miscellaneous
 The items listed below are optional and intended to enhance 
 integration between Laminas and Doctrine ORM.
 
-ObjectExists Validator and  NoObjectExists Validator
-----------------------------------------------------
-
-ObjectExists and NoObjectExists are validators similar to
-`Laminas Validators <https://docs.laminas.dev/laminas-validator/>`_.
-You can pass a variety of options to determine validity.
-The most basic use case requires an entity manager, an entity, and
-a field. You also have the option of specifying a query\_builder Closure
-to use if you want to fine tune the results.
-
-.. code:: php
-
-    <?php
-    $validator = new \DoctrineModule\Validator\NoObjectExists([
-        // object repository to lookup
-        'object_repository' => $serviceLocator->get('doctrine.entitymanager.orm_default')   
-            ->getRepository('Db\Entity\User'),
-
-        // fields to match
-        'fields' => ['username'],
-    ]);
-
-    // following works also with simple values if the number of fields to be matched is 1
-    echo $validator->isValid(['username' => 'test']) ? 'Valid' : 'Invalid. A duplicate was found.';
-
 Authentication Adapter
 ----------------------
 

docs/en/sidebar.rst

@@ -7,4 +7,5 @@
     configuration
     cache
     migrations
+    forms
     miscellaneous