add dev docs

docs/source/development/entity-info.rst

@@ -0,0 +1,203 @@
+
+.. Copyright (C)  2014 Champs Libres Cooperative SCRLFS
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+
+.. _entity-info:
+
+Stats about event on entity in php world
+########################################
+
+It is necessary to be able to gather information about events for some entities:
+
+- when the event has been done;
+- who did it;
+- ...
+
+Those "infos" are not linked with right management, like describe in :ref:`timelines`.
+
+
+“infos” for some stats and info about an entity
+-----------------------------------------------
+
+Building an info means:
+
+- create an Entity, and map this entity to a SQL view (not a regular table);
+- use the framework to build this entity dynamically.
+
+A framework api is built to be able to build multiple “infos” entities
+through “union” views:
+
+-  use a command ``bin/console chill:db:sync-views`` to synchronize view (create view if it does not exists, or update
+   views when new SQL parts are added in the UNION query. Internally, this command call a new ``ViewEntityInfoManager``,
+   which iterate over available views to build the SQL;
+-  one can create a new “view entity info” by implementing a
+   ``ViewEntityInfoProviderInterface``
+-  this implementation of the interface is free to create another
+   interface for building each part of the UNION query. This interface
+   is created for AccompanyingPeriodInfo:
+   ``Chill\PersonBundle\Service\EntityInfo\AccompanyingPeriodInfoUnionQueryPartInterface``
+
+So, converting new “events” into rows for ``AccompanyingPeriodInfo`` is
+just implementing this interface!
+
+Implementation for AccompanyingPeriod (``AccompanyingPeriod/AccompanyingPeriodInfo``)
+-------------------------------------------------------------------------------------
+
+A class is created for computing some statistical info for an
+AccompanyingPeriod: ``AccompanyingPeriod/AccompanyingPeriodInfo``. This
+contains information about “something happens”, who did it and when.
+
+Having those info in table answer some questions like:
+
+-  when is the last and the first action (AccompanyingPeriodWork,
+   Activity, AccompanyingPeriodWorkEvaluation, …) on the period;
+-  who is “acting” on the period, and when is the last “action” for each
+   user.
+
+The AccompanyingPeriod info is mapped to a SQL view, not a table. The
+sql view is built dynamically (see below), and gather infos from
+ActivityBundle, PersonBundle, CalendarBundle, … It is possible to create
+custom bundle and add info on this view.
+
+.. code:: php
+
+   /**
+    *
+    * @ORM\Entity()
+    * @ORM\Table(name="view_chill_person_accompanying_period_info") <==== THIS IS A VIEW, NOT A TABLE
+    */
+   class AccompanyingPeriodInfo
+   {
+     // ...
+   }
+
+Why do we need this ?
+~~~~~~~~~~~~~~~~~~~~~
+
+For multiple jobs in PHP world:
+
+-  moving the accompanying period to another steps when inactive,
+   automatically;
+-  listing all the users which are intervening on the action on a new
+   “Liste des intervenants” page;
+-  filtering on exports
+
+Later, we will launch automatic anonymise for accompanying period and
+all related entities through this information.
+
+How is built the SQL views which is mapped to “info” entities ?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The AccompanyingPeriodInfo entity is mapped by a SQL view (not a regular
+table).
+
+The sql view is built dynamically, it is a SQL view like this, for now (April 2023):
+
+.. code:: sql
+
+   create view view_chill_person_accompanying_period_info
+               (accompanyingperiod_id, relatedentity, relatedentityid, user_id, infodate, discriminator, metadata) as
+   SELECT w.accompanyingperiod_id,
+          'Chill\PersonBundle\Entity\AccompanyingPeriod\AccompanyingPeriodWork'::text AS relatedentity,
+          w.id                                                                        AS relatedentityid,
+          cpapwr.user_id,
+          w.enddate                                                                   AS infodate,
+          'accompanying_period_work_end'::text                                        AS discriminator,
+          '{}'::jsonb                                                                 AS metadata
+   FROM chill_person_accompanying_period_work w
+            LEFT JOIN chill_person_accompanying_period_work_referrer cpapwr ON w.id = cpapwr.accompanyingperiodwork_id
+   WHERE w.enddate IS NOT NULL
+   UNION
+   SELECT cpapw.accompanyingperiod_id,
+          'Chill\PersonBundle\Entity\AccompanyingPeriod\AccompanyingPeriodWorkEvaluation'::text AS relatedentity,
+          e.id                                                                                  AS relatedentityid,
+          e.updatedby_id                                                                        AS user_id,
+          e.updatedat                                                                           AS infodate,
+          'accompanying_period_work_evaluation_updated_at'::text                                AS discriminator,
+          '{}'::jsonb                                                                           AS metadata
+   FROM chill_person_accompanying_period_work_evaluation e
+            JOIN chill_person_accompanying_period_work cpapw ON cpapw.id = e.accompanyingperiodwork_id
+   WHERE e.updatedat IS NOT NULL
+   UNION
+   SELECT cpapw.accompanyingperiod_id,
+          'Chill\PersonBundle\Entity\AccompanyingPeriod\AccompanyingPeriodWorkEvaluation'::text AS relatedentity,
+          e.id                                                                                  AS relatedentityid,
+          cpapwr.user_id,
+          e.maxdate                                                                             AS infodate,
+          'accompanying_period_work_evaluation_start'::text                                     AS discriminator,
+          '{}'::jsonb                                                                           AS metadata
+   FROM chill_person_accompanying_period_work_evaluation e
+            JOIN chill_person_accompanying_period_work cpapw ON cpapw.id = e.accompanyingperiodwork_id
+            LEFT JOIN chill_person_accompanying_period_work_referrer cpapwr ON cpapw.id = cpapwr.accompanyingperiodwork_id
+   WHERE e.maxdate IS NOT NULL
+   UNION
+   SELECT cpapw.accompanyingperiod_id,
+          'Chill\PersonBundle\Entity\AccompanyingPeriod\AccompanyingPeriodWorkEvaluation'::text AS relatedentity,
+          e.id                                                                                  AS relatedentityid,
+          cpapwr.user_id,
+          e.startdate                                                                           AS infodate,
+          'accompanying_period_work_evaluation_start'::text                                     AS discriminator,
+          '{}'::jsonb                                                                           AS metadata
+   FROM chill_person_accompanying_period_work_evaluation e
+            JOIN chill_person_accompanying_period_work cpapw ON cpapw.id = e.accompanyingperiodwork_id
+            LEFT JOIN chill_person_accompanying_period_work_referrer cpapwr ON cpapw.id = cpapwr.accompanyingperiodwork_id
+   UNION
+   SELECT cpapw.accompanyingperiod_id,
+          'Chill\PersonBundle\Entity\AccompanyingPeriod\AccompanyingPeriodWorkEvaluationDocument'::text AS relatedentity,
+          doc.id                                                                                        AS relatedentityid,
+          doc.updatedby_id                                                                              AS user_id,
+          doc.updatedat                                                                                 AS infodate,
+          'accompanying_period_work_evaluation_document_updated_at'::text                               AS discriminator,
+          '{}'::jsonb                                                                                   AS metadata
+   FROM chill_person_accompanying_period_work_evaluation_document doc
+            JOIN chill_person_accompanying_period_work_evaluation e ON doc.accompanyingperiodworkevaluation_id = e.id
+            JOIN chill_person_accompanying_period_work cpapw ON cpapw.id = e.accompanyingperiodwork_id
+   WHERE doc.updatedat IS NOT NULL
+   UNION
+   SELECT cpapw.accompanyingperiod_id,
+          'Chill\PersonBundle\Entity\AccompanyingPeriod\AccompanyingPeriodWorkEvaluation'::text AS relatedentity,
+          e.id                                                                                  AS relatedentityid,
+          cpapwr.user_id,
+          e.maxdate                                                                             AS infodate,
+          'accompanying_period_work_evaluation_max'::text                                       AS discriminator,
+          '{}'::jsonb                                                                           AS metadata
+   FROM chill_person_accompanying_period_work_evaluation e
+            JOIN chill_person_accompanying_period_work cpapw ON cpapw.id = e.accompanyingperiodwork_id
+            LEFT JOIN chill_person_accompanying_period_work_referrer cpapwr ON cpapw.id = cpapwr.accompanyingperiodwork_id
+   WHERE e.maxdate IS NOT NULL
+   UNION
+   SELECT w.accompanyingperiod_id,
+          'Chill\PersonBundle\Entity\AccompanyingPeriod\AccompanyingPeriodWork'::text AS relatedentity,
+          w.id                                                                        AS relatedentityid,
+          cpapwr.user_id,
+          w.startdate                                                                 AS infodate,
+          'accompanying_period_work_start'::text                                      AS discriminator,
+          '{}'::jsonb                                                                 AS metadata
+   FROM chill_person_accompanying_period_work w
+            LEFT JOIN chill_person_accompanying_period_work_referrer cpapwr ON w.id = cpapwr.accompanyingperiodwork_id
+   UNION
+   SELECT activity.accompanyingperiod_id,
+          'Chill\ActivityBundle\Entity\Activity'::text AS relatedentity,
+          activity.id                                  AS relatedentityid,
+          au.user_id,
+          activity.date                                AS infodate,
+          'activity_date'::text                        AS discriminator,
+          '{}'::jsonb                                  AS metadata
+   FROM activity
+            LEFT JOIN activity_user au ON activity.id = au.activity_id
+   WHERE activity.accompanyingperiod_id IS NOT NULL;
+
+As you can see, the view gather multiple SELECT queries and bind them
+with UNION.
+
+Each SELECT query is built dynamically, through a class implementing an
+interface: ``Chill\PersonBundle\Service\EntityInfo\AccompanyingPeriodInfoUnionQueryPartInterface``, `like
+here <https://gitlab.com/Chill-Projet/chill-bundles/-/blob/master/src/Bundle/ChillPersonBundle/Service/EntityInfo/AccompanyingPeriodInfoQueryPart/AccompanyingPeriodWorkEndQueryPartForAccompanyingPeriodInfo.php>`__
+
+To add new `SELECT` query in different `UNION` parts in the sql view, create a
+service and implements this interface: ``Chill\PersonBundle\Service\EntityInfo\AccompanyingPeriodInfoUnionQueryPartInterface``.

docs/source/development/index.rst

@@ -35,6 +35,7 @@ As Chill rely on the `symfony <http://symfony.com>`_ framework, reading the fram
     manual/index.rst
     Assets <assets.rst>
     Cron Jobs <cronjob.rst>
+    Info about entities <entity-info.rst>
 
 Layout and UI
 **************

docs/source/development/timelines.rst

@@ -6,6 +6,8 @@
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".
 
+.. _timelines:
+
 Timelines
 *********
 
@@ -18,24 +20,24 @@ Concept
 From an user point of view
 --------------------------
 
-Chill has two objectives : 
+Chill has two objectives :
 
 * make the administrative tasks more lightweight ;
 * help social workers to have all information they need to work
 
 To reach this second objective, Chill provides a special view: **timeline**. On a timeline view, information is gathered and shown on a single page, from the most recent event to the oldest one.
 
-The information gathered is linked to a *context*. This *context* may be, for instance : 
+The information gathered is linked to a *context*. This *context* may be, for instance :
 
 * a person : events linked to this person are shown on the page ;
 * a center: events linked to a center are shown. They may concern different peoples ;
-* ... 
+* ...
 
 In other word, the *context* is the kind of argument that will be used in the event's query.
 
 Let us recall that only the data the user has allowed to see should be shown.
 
-.. seealso:: 
+.. seealso::
 
    `The issue where the subject was first discussed <https://redmine.champs-libres.coop/issues/224>`_
 
@@ -43,30 +45,30 @@ Let us recall that only the data the user has allowed to see should be shown.
 For developers
 --------------
 
-The `Main` bundle provides interfaces and services to help to build timelines. 
+The `Main` bundle provides interfaces and services to help to build timelines.
 
 If a bundle wants to *push* information in a timeline, it should be create a service which implements `Chill\MainBundle\Timeline\TimelineProviderInterface`, and tag is with `chill.timeline` and arguments defining the supported context (you may use multiple `chill.timeline` tags in order to support multiple context with a single service/class).
 
-If a bundle wants to provide a new context for a timeline, the service `chill.main.timeline_builder` will helps to gather timeline's services supporting the defined context, and run queries across the models. 
+If a bundle wants to provide a new context for a timeline, the service `chill.main.timeline_builder` will helps to gather timeline's services supporting the defined context, and run queries across the models.
 
 .. _understanding-queries :
 
 Understanding queries
 ^^^^^^^^^^^^^^^^^^^^^
 
-Due to the fact that timelines should show only the X last events from Y differents tables, queries for a timeline may consume a lot of resources: at first on the database, and then on the ORM part, which will have to deserialize DB data to PHP classes, which may not be used if they are not part of the "last X events". 
+Due to the fact that timelines should show only the X last events from Y differents tables, queries for a timeline may consume a lot of resources: at first on the database, and then on the ORM part, which will have to deserialize DB data to PHP classes, which may not be used if they are not part of the "last X events".
 
-To avoid such load on database, the objects are queried in two steps : 
+To avoid such load on database, the objects are queried in two steps :
 
 1. An UNION request which gather the last X events, ordered by date. The data retrieved are the ID, the date, and a string key: a type. This type discriminates the data type.
-2. The PHP objects are queried by ID, the type helps the program to link id with the kind of objects. 
+2. The PHP objects are queried by ID, the type helps the program to link id with the kind of objects.
 
 Those methods should ensure that only X PHP objects will be gathered and build by the ORM.
 
 What does the master timeline builder service ?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
- When the service `chill.main.timeline_builder` is instanciated, the service is informed of each service taggued with `chill.timeline` tags. Then, 
+ When the service `chill.main.timeline_builder` is instanciated, the service is informed of each service taggued with `chill.timeline` tags. Then,
 
 1. The service build an UNION query by assembling column and tables names provided by the `fetchQuery` result ;
 2. The UNION query is run, the result contains an id and a type for each row (see :ref:`above <understanding-queries>`)
@@ -84,7 +86,7 @@ To push events on a timeline :
 Implementing the TimelineProviderInterface
 ------------------------------------------
 
-The has the following signature : 
+The has the following signature :
 
 .. code-block:: php
 
@@ -92,19 +94,19 @@ The has the following signature :
 
     interface TimelineProviderInterface
     {
-        
+
-        /** 
+        /**
-         * 
+         *
          * @param string $context
          * @param mixed[] $args the argument to the context.
          * @return TimelineSingleQuery
          * @throw  \LogicException if the context is not supported
          */
         public function fetchQuery($context, array $args);
-        
+
         /**
          * Indicate if the result type may be handled by the service
-         * 
+         *
          * @param string $type the key present in the SELECT query
          * @return boolean
          */
@@ -113,42 +115,42 @@ The has the following signature :
         /**
          * fetch entities from db into an associative array. The keys **MUST BE**
          * the id
-         * 
+         *
-         * All ids returned by all SELECT queries 
+         * All ids returned by all SELECT queries
          * (@see TimeLineProviderInterface::fetchQuery) and with the type
          * supported by the provider (@see TimelineProviderInterface::supportsType)
          * will be passed as argument.
-         * 
+         *
          * @param array $ids an array of id
          * @return mixed[] an associative array of entities, with id as key
          */
         public function getEntities(array $ids);
-        
+
         /**
          * return an associative array with argument to render the entity
          * in an html template, which will be included in the timeline page
-         * 
+         *
          * The result must have the following key :
-         * 
+         *
          * - `template` : the template FQDN
          * - `template_data`: the data required by the template
-         * 
+         *
-         * 
+         *
          * Example:
-         * 
+         *
          * ```
-         * array( 
+         * array(
          *    'template'      => 'ChillMyBundle:timeline:template.html.twig',
          *    'template_data' => array(
-         *             'accompanyingPeriod' => $entity, 
+         *             'accompanyingPeriod' => $entity,
-         *              'person' => $args['person'] 
+         *              'person' => $args['person']
          *         )
          *    );
          * ```
-         * 
+         *
          * `$context` and `$args` are defined by the bundle which will call the timeline
-         * rendering. 
+         * rendering.
-         * 
+         *
          * @param type $entity
          * @param type $context
          * @param array $args
@@ -156,7 +158,7 @@ The has the following signature :
          * @throws \LogicException if the context is not supported
          */
         public function getEntityTemplate($entity, $context, array $args);
-     
+
     }
 
 
@@ -176,7 +178,7 @@ The parameters should be replaced into the query by :code:`?`. They will be repl
 
 `$context` and `$args` are defined by the bundle which will call the timeline rendering. You may use them to build a different query depending on this context.
 
-For instance, if the context is `'person'`, the args will be this array : 
+For instance, if the context is `'person'`, the args will be this array :
 
 .. code-block:: php
 
@@ -197,7 +199,7 @@ You should find in the bundle documentation which contexts are arguments the bun
 
 .. note::
 
-    We encourage to use `ClassMetaData` to define column names arguments. If you change your column names, changes will be reflected automatically during the execution of your code. 
+    We encourage to use `ClassMetaData` to define column names arguments. If you change your column names, changes will be reflected automatically during the execution of your code.
 
 Example of an implementation :
 
@@ -215,13 +217,13 @@ Example of an implementation :
      */
     class TimelineReportProvider implements TimelineProviderInterface
     {
-        
+
         /**
          *
          * @var EntityManager
          */
         protected $em;
-        
+
         public function __construct(EntityManager $em)
         {
             $this->em = $em;
@@ -230,9 +232,9 @@ Example of an implementation :
         public function fetchQuery($context, array $args)
             {
                 $this->checkContext($context);
-                
+
                 $metadata = $this->em->getClassMetadata('ChillReportBundle:Report');
-                
+
                 return TimelineSingleQuery::fromArray([
                    'id' => $metadata->getColumnName('id'),
                    'type' => 'report',
@@ -254,11 +256,11 @@ Example of an implementation :
 The `supportsType` function
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This function indicate to the master `chill.main.timeline_builder` service (which orchestrate the build of UNION queries) that the service supports the type indicated in the result's array of the `fetchQuery` function. 
+This function indicate to the master `chill.main.timeline_builder` service (which orchestrate the build of UNION queries) that the service supports the type indicated in the result's array of the `fetchQuery` function.
 
-The implementation of our previous example will be : 
+The implementation of our previous example will be :
 
-.. code-block:: php 
+.. code-block:: php
 
 
     namespace Chill\ReportBundle\Timeline;
@@ -272,7 +274,7 @@ The implementation of our previous example will be :
         //...
 
         /**
-         * 
+         *
          * {@inheritDoc}
          */
         public function supportsType($type)
@@ -304,12 +306,12 @@ The results **must be** an array where the id given by the UNION query (remember
         {
             $reports = $this->em->getRepository('ChillReportBundle:Report')
                   ->findBy(array('id' => $ids));
-            
+
             $result = array();
             foreach($reports as $report) {
                 $result[$report->getId()] = $report;
             }
-            
+
             return $result;
         }
 
@@ -318,9 +320,9 @@ The results **must be** an array where the id given by the UNION query (remember
 The `getEntityTemplate` function
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This is where the master service will collect information to render the entity. 
+This is where the master service will collect information to render the entity.
 
-The result must be an associative array with : 
+The result must be an associative array with :
 
 - **template** is the FQDN of the template ;
 - **template_data** is an associative array where keys are the variables'names for this template, and values are the values.
@@ -332,8 +334,8 @@ Example :
     array(
         'template' => 'ChillMyBundle:timeline:template.html.twig',
         'template_data' => array(
-            'period' => $entity, 
+            'period' => $entity,
-            'person' => $args['person'] 
+            'person' => $args['person']
             )
         );
 
@@ -349,7 +351,7 @@ Create a timeline with his own context
 
 You have to create a Controller which will execute the service `chill.main.timeline_builder`. Using the `Chill\MainBundle\Timeline\TimelineBuilder::getTimelineHTML` function, you will get an HTML representation of the timeline, which you may include with twig `raw` filter.
 
-Example : 
+Example :
 
 .. code-block:: php