Merge branch 'master' into origin/master

DESIGN.md

@@ -1,4 +1,4 @@
-#Design Considerations
+# Design Considerations
 
 This component was designed inline with the [NL API Strategie](https://docs.geostandaarden.nl/api/API-Strategie), [NORA](https://www.noraonline.nl/wiki/Standaarden), [vng.cloud](https://zaakgerichtwerken.vng.cloud/themas/index), [commonground principles](https://vng.nl/onderwerpenindex/bestuur/samen-organiseren-2019/common-ground) and international standards. 
 

INSTALLATION.md

@@ -65,25 +65,25 @@ $ helm dependency update ./api/helm
 
 If you want to create a new instance
 ```CLI
-$ helm install ./api/helm --name protocomponent --kubeconfig="api/helm/kubeconfig.yaml"
+$ helm install --name vtc-dev ./api/helm  --kubeconfig="api/helm/kubeconfig.yaml" --namespace=dev  --set settings.env=dev,settings.debug=1
+$ helm install --name vtc-stag ./api/helm --kubeconfig="api/helm/kubeconfig.yaml" --namespace=stag --set settings.env=stag,settings.debug=0
+$ helm install --name vtc-prod ./api/helm --kubeconfig="api/helm/kubeconfig.yaml" --namespace=prod --set settings.env=prod,settings.debug=0 
 ```
 
 Or update if you want to update an existing one
 ```CLI
-$ helm upgrade protocomponent  ./api/helm --kubeconfig="api/helm/kubeconfig.yaml" 
+$ helm upgrade vtc-dev ./api/helm  --kubeconfig="api/helm/kubeconfig.yaml --namespace=dev  --set settings.env=dev, settings.debug=1" 
+$ helm upgrade vtc-stag ./api/helm --kubeconfig="api/helm/kubeconfig.yaml --namespace=stag --set settings.env=stag, settings.debug=0" 
+$ helm upgrade vtc-prod ./api/helm --kubeconfig="api/helm/kubeconfig.yaml --namespace=prod --set settings.env=prod, settings.debug=0" 
 ```
 
 Or del if you want to delete an existing  one
 ```CLI
-$ helm del protocomponent  --purge --kubeconfig="api/helm/kubeconfig.yaml" 
+$ helm del vtc-dev  --purge --kubeconfig="api/helm/kubeconfig.yaml --namespace=dev" 
+$ helm del vtc-stag --purge --kubeconfig="api/helm/kubeconfig.yaml --namespace=stag" 
+$ helm del vtc-prod --purge --kubeconfig="api/helm/kubeconfig.yaml --namespace=prod" 
 ```
 
-or for the dev enviroments
-$ helm install ./api/helm --name vtc-dev --kubeconfig="api/helm/kubeconfig.yaml"
-$ helm upgrade vtc-dev  ./api/helm --kubeconfig="api/helm/kubeconfig.yaml" 
-$ helm del vtc-dev  --purge --kubeconfig="api/helm/kubeconfig.yaml" 
-
-Note that you can replace commonground with the namespace that you want to use (normally the name of your component).
 
 
 ## Making your app known on NLX

TUTORIAL.md

@@ -1,11 +1,14 @@
 # Tutorial
 
 What do you need for this tutorial?
-* browser
-* github account
-* git client
-* docker account
-* docker for desktop
+* Browser
+* Github account
+* Git client
+* Docker account
+* Docker for desktop
+
+## Before you begin
+For the steps consirning the generation of entities an example entity a availale, feel free to [take a look](https://github.com/ConductionNL/Proto-component-commonground/blob/master/api/src/Entity/ExampleEntity.php) at it if you have trouble figuring out the code.
 
 ## Setting up your enviroment
 
@@ -268,14 +271,60 @@ into this
 
 and your all done
 
-### trouble shooting
+### Rrouble shooting
 If you have already spunn your component including your new entity your going to run into some trouble becouse doctrine is going to try changing your primary key collum (id) from an integer to string (tables tend not to like that). In that case its best to just drop your database and reinstall it using the following commands:
 
 ```CLI
 $ bin/console doctrine:schema:drop
 $ bin/console doctrine:schema:update --force
 ```
 
+## Advanced data sets
+
+Oke lets make it complex, until now we have just added some simple entities to our component, but what if we want to ataches one entity to another? Fortunatly our build in database engine support rather complex senarios called associations. So let [take a look](https://www.doctrine-project.org/projects/doctrine-orm/en/2.6/reference/association-mapping.html) at that.  
+
+Bafled? Wel its rather complex. But remember that Make:entity command that we used earlier? That actuelly accepts relations as a data type. Or to but it simply instead of using the default 'string' we could just type "ManyToOne" and it will just fire up some qoustions that will help it determine how you want your relations to be.
+
+
+### Trouble shooting
+A very common error when linking entities togehter is circle refrances, those will break our serializatoin. Furtunaltly we have a need way to prevent that. Even better symfony gives us exact control of how deep we want the circular refereance to go. To do this we need to use the `MaxDepth()` annotation. So lets import that 
+
+```PHP
+//...
+use Symfony\Component\Serializer\Annotation\MaxDepth;
+//...
+```
+
+And tell our serializer to use it.
+
+```PHP
+//...
+/**
+ * @ApiResource(
+ *     normalizationContext={"groups"={"read"}, "enable_max_depth"=true},
+ *     denormalizationContext={"groups"={"write"}, "enable_max_depth"=true}
+ * )
+ * @ORM\Entity(repositoryClass="App\Repository\ExampleEntityRepository")
+ */
+class ExampleEntity
+	{
+//...
+```
+
+We can now prevent circular referances by setting a max depth on the properties cousing the circular refrance.
+
+//...
+    /**
+     * @var ArrayCollection $stuffs Some stuff that is atached to this example object
+     * 
+     * @MaxDepth(1)
+     * @Groups({"read","write"})
+     * @ORM\ManyToOne(targetEntity="App\Entity\Stuff", inversedBy="examples")
+     */
+    private $stuffs;     
+//...
+```
+
 ## Datafixtures
 For testing cases it can be usefull to use datafixtures a predefined set of data that fills the database of your component at startup. Since we use php classes to describe our objects creating fixtures is easy (you can find an example in your project folder at api/src/DataFixtures). We simply go trough some classes asign values and persist them to the database. Once we have written our fixtures we can use a single command to load them  
 
@@ -301,9 +350,22 @@ When using Github. To set up a webhook, go to the settings page of your reposito
 Now every time you update your repository the commonground dev page will allerted, rescan your repository and do al the apropriate platform actions. It just as easy as that.
 
 
-Automated Testing
+Automated Testing and Deployment (continues integration)
 -------
-adasd
+The following bit of the tutorial requires two additional accounts
+- [https://hub.docker.com/](https://hub.docker.com/) (You might already have this for docker for desktop)
+- [https://travis-ci.org](https://travis-ci.org) (You can use you github account)
+
+The proto component ships with a pre-fab continues integration script based on travis. What does this mean you ask? Continues integration (or CI for short) is an optimized and automated way for your code to become part of your projects. In the case of your commonground component that means that we will automatically validate new code commites or pushes and (if everything checks out) build that code and deploy the containers thereof to docker hub. Making is possible to update al the environments that use those components.
+
+Oke that’s nice, but how do we do that? Actually it is verily simple. First of all make sure you have a docker account, log into [docker hub](https://hub.docker.com/) and have a look around. We don’t need to create anything just yet'but it is nice to get a feeling of the place. As you can see docker hub also uses repositories etc. So that recognizable.
+
+Next we need to prepare our github repository that holds our code. For the travis script to work as intended we need to create a couple of branches(if we don’t have those already) open up yout git interface and create a branch called 'development' and a branch called 'staging'. Don't forget to push the branches so that they are present on github (and not just on your local machine).
+
+Oke just one more place to go and that is travis, head over to [https://travis-ci.org](https://travis-ci.org) and login with your gitacount. If everything is alright you should see your repositoriy there. Activate it by pressing 'activate repository' and then go to 'More options' -> 'Settings' and scroll down to enviroment variables. Here we can present travis wit the variables that it need to execute our build script. Lets first set the common variables that we need for all our branches: `DOCKER_PASSWORD` your docker password,`DOCKER_REGISTRY` docker.io/[your username] ,`DOCKER_USERNAME` your docker user name. This will be used by travis to push the completed containers into docker hub. Next we need to specify a couple of variables that are branch specific. Or to be more exact, set the same variable `APP_ENV` with different values for different branches. It needs to be 'staging'->stag,'master'->prod,'development'->dev.
+
+And all done! Head over back to the code on your computer and make a small change. Then commit push that change into github. Travis should automatically pick op your change and start a build.
+
 
 ### Unit / Behat
 
@@ -312,11 +374,75 @@ adas
 ### Postman
 ad
 
+### Trouble shooting
+Please make sure that your github repositry is set to public, and keep in mind that a complex travis build (and sertenly one that includes a pushing of containers can take up to 20 minutes)
+
+Documentation and dockblocks
+-------
+asdsa
+
 Audittrail
 -------
-as
+As you might expect the proto-component ships with a neat function for generating audit trails, that basically exist of three parts. 
+
+First we need to activate logging on the entities that we want logged (for obius security reasons we don’t log entity changes by default) to do that by adding the `@Gedmo\Loggable` annotation to our php class, which should then look something like:
+
+```PHP
+//...
+/**
+ * @ApiResource(
+ *     normalizationContext={"groups"={"read"}, "enable_max_depth"=true},
+ *     denormalizationContext={"groups"={"write"}, "enable_max_depth"=true}
+ * )
+ * @ORM\Entity(repositoryClass="App\Repository\ExampleEntityRepository")
+ * @Gedmo\Loggable
+ */
+class ExampleEntity
+	{
+//...
+```
+
+Next we need to tell the specific properties that we want to log that they are loggable (again this is a conscious choice, to prevent us from accidently logging stuff like bsn numbers), we do that by adding the `@Gedmo\Versioned` annotation to those specific properties. That would then look something like this:
+
+```PHP
+//...
+    /**
+	 * @var string $name The name of this example property
+	 * @example My Group
+	 * 
+	 * @Assert\NotNull
+	 * @Assert\Length(
+	 *      max = 255
+	 * )
+     * @Gedmo\Versioned
+	 * @Groups({"read","write"})
+     * @ORM\Column(type="string", length=255)
+     */
+    private $name;
+//...
+```
+
+Okay actually we are now good to go, at least we are logging those things that we want logged. But.... How do we view those logs? In commonground we have a [convention](https://zaakgerichtwerken.vng.cloud/themas/achtergronddocumentatie/audit-trail) to expose a /audittrail subresource on resources that are logged. So lets add that trough our `@ApiResource` anotation.
+
+```PHP
+//...
+/**
+ * @ApiResource(
+ *     normalizationContext={"groups"={"read"}, "enable_max_depth"=true},
+ *     denormalizationContext={"groups"={"write"}, "enable_max_depth"=true}
+ * )
+ * @ORM\Entity(repositoryClass="App\Repository\ExampleEntityRepository")
+ * @Gedmo\Loggable
+ */
+class ExampleEntity
+	{
+//...
+```
+
+And now we have a fully nl api strategie integrated audit trail!
+
 
-Setting up continues integration and continues delivery
+Setting up automated deployment (continues delivery)
 -------
 adasd
 

api/helm/Chart.yaml

@@ -1,7 +1,7 @@
 apiVersion: v1
-appVersion: 0.1.0
-description: A Helm chart for an Common Ground VTC API component
-name: vtc
+appVersion: V.0.1
+description: Naast deze JSON rest API is er ook een [graphql](/graphql) interface beschikbaar.
+name: verzoektypecatalogus
 version: 0.1.0
 home: https://common-ground.dev
 icon: https://common-ground.dev/logo-250x250.png

api/helm/templates/api-deployment.yaml

@@ -31,6 +31,11 @@ spec:
                 configMapKeyRef:
                   name: {{ template "fullname" . }}
                   key: php-service
+            - name: NGINX_HOST
+              valueFrom:
+                configMapKeyRef:
+                  name: {{ template "fullname" . }}
+                  key: php-service
           resources:
 {{ toYaml .Values.resources | indent 12 }}
     {{- if .Values.nodeSelector }}

api/helm/values.yaml

@@ -32,15 +32,15 @@ php:
   secret: ""
 
 nginx:
-  repository: docker.io/conduction/vtc-nginx
+  repository: docker.io/conduction/protocomponent-nginx
   tag: latest
   pullPolicy: Always
   replicaCount: 1
 
 varnish:
   enabled: true
-  url: https://vtc-varnish
-  repository: docker.io/conduction/vtc-varnish
+  #url: https://example.com
+  repository: docker.io/conduction/protocomponent-varnish
   tag: latest
   pullPolicy: Always
   replicaCount: 1
@@ -63,7 +63,7 @@ postgresql:
 #    tag: alpine
 
 mercure:
-  enabled: false
+  enabled: true
   publishUrl: http://mercure/hub
   subscribeUrl: https://mercure.example.com/hub
   allowAnonymous: "1"