feature #27069 [LDAP] Add "applyOperations" method to EntryManager (m…

…ablae)

This PR was merged into the 4.2-dev branch.

Discussion
----------

[LDAP] Add "applyOperations" method to EntryManager

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | #27039
| License       | MIT
| Doc PR        | symfony/symfony-docs#9715

This PR adds a new method called `applyOperations` to the LDAP `EntryManager` class.
Internally it is mapping the new `UpdateOperation` object to the `ldap_modify_batch` method.

Tests green against openldap.

Thanks for any feedback.

Todo:

  * [x] Add Docs PR

Commits
-------

8fc09c7 Add applyOperations batch method to EntryManager

src/Symfony/Component/Ldap/Adapter/ExtLdap/EntryManager.php

@@ -13,6 +13,7 @@
 
 use Symfony\Component\Ldap\Adapter\EntryManagerInterface;
 use Symfony\Component\Ldap\Entry;
+use Symfony\Component\Ldap\Exception\UpdateOperationException;
 use Symfony\Component\Ldap\Exception\LdapException;
 use Symfony\Component\Ldap\Exception\NotBoundException;
 
@@ -121,4 +122,21 @@ private function getConnectionResource()
 
         return $this->connection->getResource();
     }
+
+    /**
+     * @param iterable|UpdateOperation[] $operations An array or iterable of UpdateOperation instances
+     *
+     * @throws UpdateOperationException in case of an error
+     */
+    public function applyOperations(string $dn, iterable $operations): void
+    {
+        $operationsMapped = array();
+        foreach ($operations as $modification) {
+            $operationsMapped[] = $modification->toArray();
+        }
+
+        if (!@ldap_modify_batch($this->getConnectionResource(), $dn, $operationsMapped)) {
+            throw new UpdateOperationException(sprintf('Error executing UpdateOperation on "%s": "%s".', $dn, ldap_error($this->getConnectionResource())));
+        }
+    }
 }

src/Symfony/Component/Ldap/Adapter/ExtLdap/UpdateOperation.php

@@ -0,0 +1,76 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Ldap\Adapter\ExtLdap;
+
+use Symfony\Component\Ldap\Exception\UpdateOperationException;
+
+class UpdateOperation
+{
+    private $operationType;
+    private $values;
+    private $attribute;
+
+    private $validOperationTypes = array(
+        LDAP_MODIFY_BATCH_ADD,
+        LDAP_MODIFY_BATCH_REMOVE,
+        LDAP_MODIFY_BATCH_REMOVE_ALL,
+        LDAP_MODIFY_BATCH_REPLACE,
+    );
+
+    /**
+     * @param int    $operationType An LDAP_MODIFY_BATCH_* constant
+     * @param string $attribute     The attribute to batch modify on
+     *
+     * @throws UpdateOperationException on consistency errors during construction
+     */
+    public function __construct(int $operationType, string $attribute, ?array $values)
+    {
+        $this->assertValidOperationType($operationType);
+        $this->assertNullValuesOnRemoveAll($operationType, $values);
+
+        $this->operationType = $operationType;
+        $this->attribute = $attribute;
+        $this->values = $values;
+    }
+
+    public function toArray(): array
+    {
+        return array(
+            'attrib' => $this->attribute,
+            'modtype' => $this->operationType,
+            'values' => $this->values,
+        );
+    }
+
+    /**
+     * @param int $operationType
+     */
+    private function assertValidOperationType(int $operationType): void
+    {
+        if (!in_array($operationType, $this->validOperationTypes, true)) {
+            throw new UpdateOperationException(sprintf('"%s" is not a valid modification type.', $operationType));
+        }
+    }
+
+    /**
+     * @param int        $operationType
+     * @param array|null $values
+     *
+     * @throws \Symfony\Component\Ldap\Exception\UpdateOperationException
+     */
+    private function assertNullValuesOnRemoveAll(int $operationType, ?array $values): void
+    {
+        if (LDAP_MODIFY_BATCH_REMOVE_ALL === $operationType && null !== $values) {
+            throw new UpdateOperationException(sprintf('$values must be null for LDAP_MODIFY_BATCH_REMOVE_ALL operation, "%s" given.', gettype($values)));
+        }
+    }
+}

src/Symfony/Component/Ldap/Exception/UpdateOperationException.php

@@ -0,0 +1,16 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Ldap\Exception;
+
+class UpdateOperationException extends LdapException
+{
+}

src/Symfony/Component/Ldap/Tests/Adapter/ExtLdap/LdapManagerTest.php

@@ -13,7 +13,9 @@
 
 use Symfony\Component\Ldap\Adapter\ExtLdap\Adapter;
 use Symfony\Component\Ldap\Adapter\ExtLdap\Collection;
+use Symfony\Component\Ldap\Adapter\ExtLdap\UpdateOperation;
 use Symfony\Component\Ldap\Entry;
+use Symfony\Component\Ldap\Exception\UpdateOperationException;
 use Symfony\Component\Ldap\Exception\LdapException;
 use Symfony\Component\Ldap\Exception\NotBoundException;
 
@@ -238,4 +240,105 @@ public function testLdapAddAttributeValuesError()
 
         $entryManager->addAttributeValues($entry, 'mail', $entry->getAttribute('mail'));
     }
+
+    public function testLdapApplyOperationsRemoveAllWithArrayError()
+    {
+        $entryManager = $this->adapter->getEntryManager();
+
+        $result = $this->executeSearchQuery(1);
+        $entry = $result[0];
+
+        $this->{method_exists($this, $_ = 'expectException') ? $_ : 'setExpectedException'}(UpdateOperationException::class);
+
+        $entryManager->applyOperations($entry->getDn(), array(new UpdateOperation(LDAP_MODIFY_BATCH_REMOVE_ALL, 'mail', array())));
+    }
+
+    public function testLdapApplyOperationsWithWrongConstantError()
+    {
+        $entryManager = $this->adapter->getEntryManager();
+
+        $result = $this->executeSearchQuery(1);
+        $entry = $result[0];
+
+        $this->{method_exists($this, $_ = 'expectException') ? $_ : 'setExpectedException'}(UpdateOperationException::class);
+
+        $entryManager->applyOperations($entry->getDn(), array(new UpdateOperation(512, 'mail', array())));
+    }
+
+    public function testApplyOperationsAddRemoveAttributeValues()
+    {
+        $entryManager = $this->adapter->getEntryManager();
+
+        $result = $this->executeSearchQuery(1);
+        $entry = $result[0];
+
+        $entryManager->applyOperations($entry->getDn(), array(
+            new UpdateOperation(LDAP_MODIFY_BATCH_ADD, 'mail', array('fabpot@example.org', 'fabpot2@example.org')),
+            new UpdateOperation(LDAP_MODIFY_BATCH_ADD, 'mail', array('fabpot3@example.org', 'fabpot4@example.org')),
+        ));
+
+        $result = $this->executeSearchQuery(1);
+        $newEntry = $result[0];
+
+        $this->assertCount(6, $newEntry->getAttribute('mail'));
+
+        $entryManager->applyOperations($entry->getDn(), array(
+            new UpdateOperation(LDAP_MODIFY_BATCH_REMOVE, 'mail', array('fabpot@example.org', 'fabpot2@example.org')),
+            new UpdateOperation(LDAP_MODIFY_BATCH_REMOVE, 'mail', array('fabpot3@example.org', 'fabpot4@example.org')),
+        ));
+
+        $result = $this->executeSearchQuery(1);
+        $newNewEntry = $result[0];
+
+        $this->assertCount(2, $newNewEntry->getAttribute('mail'));
+    }
+
+    public function testUpdateOperationsWithIterator()
+    {
+        $iteratorAdd = new \ArrayIterator(array(
+            new UpdateOperation(LDAP_MODIFY_BATCH_ADD, 'mail', array('fabpot@example.org', 'fabpot2@example.org')),
+            new UpdateOperation(LDAP_MODIFY_BATCH_ADD, 'mail', array('fabpot3@example.org', 'fabpot4@example.org')),
+        ));
+
+        $iteratorRemove = new \ArrayIterator(array(
+            new UpdateOperation(LDAP_MODIFY_BATCH_REMOVE, 'mail', array('fabpot@example.org', 'fabpot2@example.org')),
+            new UpdateOperation(LDAP_MODIFY_BATCH_REMOVE, 'mail', array('fabpot3@example.org', 'fabpot4@example.org')),
+        ));
+
+        $entryManager = $this->adapter->getEntryManager();
+
+        $result = $this->executeSearchQuery(1);
+        $entry = $result[0];
+
+        $entryManager->applyOperations($entry->getDn(), $iteratorAdd);
+
+        $result = $this->executeSearchQuery(1);
+        $newEntry = $result[0];
+
+        $this->assertCount(6, $newEntry->getAttribute('mail'));
+
+        $entryManager->applyOperations($entry->getDn(), $iteratorRemove);
+
+        $result = $this->executeSearchQuery(1);
+        $newNewEntry = $result[0];
+
+        $this->assertCount(2, $newNewEntry->getAttribute('mail'));
+    }
+
+    public function testUpdateOperationsThrowsExceptionWhenAddedDuplicatedValue()
+    {
+        $duplicateIterator = new \ArrayIterator(array(
+            new UpdateOperation(LDAP_MODIFY_BATCH_ADD, 'mail', array('fabpot@example.org')),
+            new UpdateOperation(LDAP_MODIFY_BATCH_ADD, 'mail', array('fabpot@example.org')),
+        ));
+
+        $entryManager = $this->adapter->getEntryManager();
+
+        $result = $this->executeSearchQuery(1);
+        $entry = $result[0];
+
+        $this->{method_exists($this, $_ = 'expectException') ? $_ : 'setExpectedException'}(UpdateOperationException::class);
+
+        $entryManager->applyOperations($entry->getDn(), $duplicateIterator);
+    }
 }