Docs & minor improvements

app/DoctrineMigrations/Version20141125173004.php

@@ -47,7 +47,6 @@ public function up(Schema $schema)
         $this->abortIf($this->connection->getDatabasePlatform()->getName() != 'mysql', 'Migration can only be executed safely on \'mysql\'.');
 
         $this->addSql(sprintf('CREATE TABLE %s.saml_entity (entity_id VARCHAR(255) NOT NULL, type VARCHAR(255) NOT NULL, configuration LONGTEXT NOT NULL, PRIMARY KEY(entity_id)) DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci ENGINE = InnoDB', $gatewaySchema));
-//        $this->addSql(sprintf('GRANT EXECUTE ON %s.* TO %s', $gatewaySchema, $middlewareUser));
         $this->addSql(sprintf("GRANT DELETE,INSERT,SELECT,UPDATE ON %s.saml_entity TO %s", $gatewaySchema, $middlewareUser));
     }
 

src/Surfnet/Stepup/Configuration/Configuration.php

@@ -26,6 +26,9 @@
 
 class Configuration extends EventSourcedAggregateRoot
 {
+    /**
+     * There can ever be only one configuration, so using a fixed UUIDv4
+     */
     const CONFIGURATION_ID = '12345678-abcd-4321-abcd-123456789012';
 
     /**
@@ -78,6 +81,8 @@ public function applyConfigurationUpdatedEvent(ConfigurationUpdatedEvent $event)
     }
 
     /**
+     * Used to be able to update the gateway configuration within a single transaction.
+     *
      * @return null|ServiceProvidersUpdatedEvent
      */
     public function getLastUncommittedServiceProvidersUpdatedEvent()
@@ -86,6 +91,8 @@ public function getLastUncommittedServiceProvidersUpdatedEvent()
     }
 
     /**
+     * Cleaning up the possible event, as the uncommittedEvents will be removed as well
+     *
      * @return \Broadway\Domain\DomainEventStream
      */
     public function getUncommittedEvents()

src/Surfnet/Stepup/Configuration/Event/ServiceProvidersUpdatedEvent.php

@@ -20,6 +20,9 @@
 
 class ServiceProvidersUpdatedEvent extends ConfigurationEvent
 {
+    /**
+     * @var array
+     */
     public $serviceProviders;
 
     public function __construct($configurationId, array $serviceProviders)

src/Surfnet/StepupMiddleware/CommandHandlingBundle/Configuration/Command/UpdateConfigurationCommand.php

@@ -28,7 +28,7 @@ class UpdateConfigurationCommand implements Command
     public $UUID;
 
     /**
-     * @var \Surfnet\Stepup\Configuration\Configuration
+     * @var string configuration as json as received in the request
      */
     public $configuration;
 }

src/Surfnet/StepupMiddleware/CommandHandlingBundle/Configuration/CommandHandler/ConfigurationCommandHandler.php

@@ -28,12 +28,12 @@
 class ConfigurationCommandHandler extends CommandHandler
 {
     /**
-     * @var ConfigurationRepository
+     * @var \Surfnet\Stepup\Configuration\EventSourcing\ConfigurationRepository
      */
     private $repository;
 
     /**
-     * @var
+     * @var \Surfnet\StepupMiddleware\GatewayBundle\Service\GatewayConfigurationService
      */
     private $gatewayConfigurationService;
 

src/Surfnet/StepupMiddleware/GatewayBundle/DependencyInjection/Configuration.php

@@ -34,11 +34,7 @@ class Configuration implements ConfigurationInterface
     public function getConfigTreeBuilder()
     {
         $treeBuilder = new TreeBuilder();
-        /*$rootNode = */$treeBuilder->root('surfnet_stepup_gateway_gateway');
-
-        // Here you should define the parameters that are allowed to
-        // configure your bundle. See the documentation linked above for
-        // more information on that topic.
+        $treeBuilder->root('surfnet_stepup_gateway_gateway');
 
         return $treeBuilder;
     }

src/Surfnet/StepupMiddleware/GatewayBundle/Entity/SamlEntity.php

@@ -18,7 +18,6 @@
 
 namespace Surfnet\StepupMiddleware\GatewayBundle\Entity;
 
-use Assert\Assertion as Assert;
 use Doctrine\ORM\Mapping as ORM;
 
 /**
@@ -27,6 +26,9 @@
  */
 class SamlEntity
 {
+    /**
+     * Constants denoting the type of SamlEntity. Also used in the gateway to make that distinction
+     */
     const TYPE_IDP = 'idp';
     const TYPE_SP  = 'sp';
 
@@ -48,17 +50,27 @@ class SamlEntity
     /**
      * @ORM\Column(type="text")
      *
-     * @var string
+     * @var string the configuration as json string
      */
     public $configuration;
 
+    /**
+     * @param string $entityId
+     * @param string $type
+     * @param string $configuration
+     */
     private function __construct($entityId, $type, $configuration)
     {
         $this->entityId = $entityId;
         $this->type = $type;
         $this->configuration = $configuration;
     }
 
+    /**
+     * @param string $entityId
+     * @param array  $configuration
+     * @return SamlEntity
+     */
     public static function createServiceProvider($entityId, array $configuration)
     {
         return new self($entityId, self::TYPE_SP, json_encode($configuration));

src/Surfnet/StepupMiddleware/GatewayBundle/Entity/SamlEntityRepository.php

@@ -23,6 +23,9 @@
 
 class SamlEntityRepository extends EntityRepository
 {
+    /**
+     * Remove all configured SamlEntities
+     */
     public function removeAll()
     {
         $this
@@ -33,6 +36,15 @@ public function removeAll()
             ->execute();
     }
 
+    /**
+     * Replace all configured SamlEntiies with the new SamlEntities.
+     *
+     * Will be updated later, see https://www.pivotaltracker.com/story/show/83532704
+     *
+     * @param $newSamlEntities
+     * @throws Exception
+     * @throws \Doctrine\DBAL\ConnectionException
+     */
     public function replaceAll($newSamlEntities)
     {
         $connection = $this->getEntityManager()->getConnection();

src/Surfnet/StepupMiddleware/GatewayBundle/Service/GatewayConfigurationService.php

@@ -25,13 +25,19 @@
 
 class GatewayConfigurationService extends Projector
 {
+    /**
+     * @var \Surfnet\StepupMiddleware\GatewayBundle\Entity\SamlEntityRepository
+     */
     private $samlEntityRepository;
 
     public function __construct(SamlEntityRepository $samlEntityRepository)
     {
         $this->samlEntityRepository = $samlEntityRepository;
     }
 
+    /**
+     * @param array $serviceProviderConfigurations
+     */
     public function updateServiceProviders(array $serviceProviderConfigurations)
     {
         $spConfigurations = new ArrayCollection();

src/Surfnet/StepupMiddleware/ManagementBundle/Controller/ConfigurationController.php

@@ -43,6 +43,9 @@ public function updateAction(Request $request)
 
             $response = new JsonResponse();
             $response
+                // EntityIDs are almost always URLs. Escaping forward slashes is done for ease of use of json within
+                // <script> tags, which is not done here. This increases readability and searching of errors.
+                // hence we allow unescaped slashes.
                 ->setEncodingOptions($response->getEncodingOptions() | JSON_UNESCAPED_SLASHES)
                 ->setData(['configuration-errors' => $errors])
                 ->setStatusCode(400);

src/Surfnet/StepupMiddleware/ManagementBundle/Tests/Controller/ConfigurationControllerTest.php

@@ -37,6 +37,7 @@ public function setUp()
         $this->client = static::createClient();
         $this->password = $this->client->getKernel()->getContainer()->getParameter('management_password');
     }
+
     /**
      * @test
      * @group management