Merge branch 'master' of git://github.com/Chill-project/Main

ChillMainBundle.php

@@ -6,6 +6,7 @@ use Symfony\Component\HttpKernel\Bundle\Bundle;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Chill\MainBundle\DependencyInjection\SearchableServicesCompilerPass;
 use Chill\MainBundle\DependencyInjection\ConfigConsistencyCompilerPass;
+use Chill\MainBundle\DependencyInjection\TimelineCompilerClass;
 
 class ChillMainBundle extends Bundle
 {
@@ -14,5 +15,6 @@ class ChillMainBundle extends Bundle
         parent::build($container);
         $container->addCompilerPass(new SearchableServicesCompilerPass());
         $container->addCompilerPass(new ConfigConsistencyCompilerPass());
+        $container->addCompilerPass(new TimelineCompilerClass());
     }
 }

DependencyInjection/SearchableServicesCompilerPass.php

@@ -33,7 +33,7 @@ class SearchableServicesCompilerPass implements CompilerPassInterface
      */
     public function process(ContainerBuilder $container)
     {
-    if (!$container->hasDefinition('chill.main.search_provider')) {
+        if (!$container->hasDefinition('chill.main.search_provider')) {
             throw new \LogicException('service chill.main.search_provider '
                     . 'is not defined.');
         }

DependencyInjection/TimelineCompilerClass.php

@@ -0,0 +1,66 @@
+<?php
+
+/*
+ * Copyright (C) 2015 Julien Fastré <julien.fastre@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\DependencyInjection;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Reference;
+
+/**
+ * Add services taggued with  `name: chill.timeline` to 
+ * timeline_builder service definition
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ */
+class TimelineCompilerClass implements CompilerPassInterface
+{
+    public function process(ContainerBuilder $container)
+    {
+        if (!$container->hasDefinition('chill.main.timeline_builder')) {
+            throw new \LogicException('service chill.main.timeline_builder '
+                    . 'is not defined.');
+        }
+        
+        $definition = $container->getDefinition(
+            'chill.main.timeline_builder'
+        );
+
+        $taggedServices = $container->findTaggedServiceIds(
+            'chill.timeline'
+        );
+        
+        foreach ($taggedServices as $id => $tagAttributes) {
+            
+            foreach ($tagAttributes as $attributes) {
+                
+                if (!isset($attributes["context"])) {
+                    throw new \LogicException("the 'context' attribute is missing in your ".
+                        "service '$id' definition");
+                }
+
+                $definition->addMethodCall(
+                    'addProvider',
+                    array($attributes["context"], $id)
+                );
+            }
+        }
+    }
+
+}

Resources/config/services.yml

@@ -79,3 +79,10 @@ services:
 
     chill.main.search_provider:
         class: Chill\MainBundle\Search\SearchProvider
+        
+    chill.main.timeline_builder:
+        class: Chill\MainBundle\Timeline\TimelineBuilder
+        arguments:
+            - "@doctrine.orm.entity_manager"
+        calls:
+            - [ setContainer, ["@service_container"]]

Resources/views/Timeline/index.html.twig

@@ -0,0 +1,8 @@
+<div class="timeline">
+{% for result in results %}
+    <div>
+        {% include result.template with result.template_data %}
+    </div>
+
+{% endfor %}
+</div>

Timeline/TimelineBuilder.php

@@ -0,0 +1,262 @@
+<?php
+
+/*
+ * Copyright (C) 2015 Julien Fastré <julien.fastre@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\Timeline;
+
+use Doctrine\ORM\Query\ResultSetMapping;
+use Doctrine\ORM\EntityManagerInterface;
+use Symfony\Component\DependencyInjection\ContainerAwareInterface;
+
+/**
+ * Build timeline
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ */
+class TimelineBuilder implements ContainerAwareInterface
+{
+    
+    use \Symfony\Component\DependencyInjection\ContainerAwareTrait;
+    
+    /**
+     *
+     * @var \Doctrine\ORM\EntityManagerInterface
+     */
+    private $em;
+    
+    public function __construct(EntityManagerInterface $em)
+    {
+        $this->em = $em;
+    }
+    
+    /**
+     *
+     * @var string references to providers services
+     */
+    private $providers = array();
+    
+    /**
+     * return an HTML string with timeline
+     * 
+     * This function must be called from controller
+     * 
+     * @example https://redmine.champs-libres.coop/projects/chillperson/repository/revisions/bd2e1b1808f73e39532e9538413025df5487cad0/entry/Controller/TimelinePersonController.php#L47 the implementation in person bundle
+     * 
+     * @param string $context
+     * @param array $args arguments defined by the bundle which create the context
+     * @param int $page first page = 0
+     * @param int $number number of items by page
+     * @return string an HTML representation, must be included using `|raw` filter
+     */
+    public function getTimelineHTML($context, array $args, $page = 0, $number = 20)
+    {
+        $query = $this->buildUnionQuery($context, $args, $page, $number);
+        $fetched = $this->runQuery($query);
+        $entitiesByKey = $this->getEntities($fetched, $context);
+        
+        return $this->render($fetched, $entitiesByKey, $context, $args);
+    }
+    
+    /**
+     * add a provider id
+     * 
+     * @internal This function is called by the TimelineCompilerClass
+     * 
+     * @param string $context the context of the service
+     * @param string $id the 
+     */
+    public function addProvider($context, $id)
+    {
+        $this->providers[$context][] = $id;
+    }
+    
+    /**
+     * Get providers by context
+     * 
+     * @param string $context
+     * @return TimelineProviderInterface[]
+     */
+    public function getProvidersByContext($context)
+    {
+        $providers = array();
+        
+        foreach($this->providers[$context] as $providerId) {
+            $providers[] = $this->container->get($providerId);
+        }
+        
+        return $providers;
+    }
+    
+    /**
+     * build the UNION query with all providers
+     * 
+     * @uses self::buildSelectQuery to build individual SELECT queries
+     * 
+     * @param string $context
+     * @param mixed $args
+     * @param int $page
+     * @param int $number
+     * @return string
+     * @throws \LogicException if no builder have been defined for this context
+     */
+    private function buildUnionQuery($context, array $args, $page, $number)
+    {
+        //throw an exception if no provider have been defined for this context
+        if (!array_key_exists($context, $this->providers)) {
+            throw new \LogicException(sprintf('No builders have been defined for "%s"'
+                    . ' context', $context));
+        }
+        
+        //append SELECT queries with UNION keyword between them
+        $union = '';
+        foreach($this->getProvidersByContext($context) as $provider) {  
+            $select = $this->buildSelectQuery($provider, $context, $args); 
+            $append = ($union === '') ?  $select : ' UNION '.$select;
+            $union .= $append;
+        }
+        //add ORDER BY clause and LIMIT
+        $union .= sprintf(' ORDER BY date LIMIT %d OFFSET %d',
+                $number, $page * $number);
+        
+        return $union;
+    }
+    
+    /**
+     * return the SQL SELECT query as a string,
+     * 
+     * @uses TimelineProfiderInterface::fetchQuery use the fetchQuery function
+     * @param \Chill\MainBundle\Timeline\TimelineProviderInterface $provider
+     * @param string $context
+     * @param mixed[] $args
+     * @return string
+     */
+    private function buildSelectQuery(TimelineProviderInterface $provider, $context, array $args)
+    {
+        $data = $provider->fetchQuery($context, $args);
+        
+        return sprintf(
+                'SELECT "%s" AS id, '
+                . '"%s" AS "date", '
+                . "'%s' AS type "
+                . 'FROM %s '
+                . 'WHERE %s',
+                $data['id'],
+                $data['date'],
+                $data['type'],
+                $data['FROM'],
+                $data['WHERE']);
+    }
+    
+    /**
+     * run the UNION query and return result as an array
+     * 
+     * @param string $query
+     * @return array
+     */
+    private function runQuery($query)
+    {
+        $resultSetMapping = (new ResultSetMapping())
+                ->addScalarResult('id', 'id')
+                ->addScalarResult('type', 'type')
+                ->addScalarResult('date', 'date');
+        
+        return $this->em->createNativeQuery($query, $resultSetMapping)
+                ->getArrayResult();
+    }
+    
+    /**
+     * 
+     * @param array $queriedIds
+     * @param string $context
+     * @return array with the form array($type => [$entity, $entity, $entity])
+     */
+    private function getEntities(array $queriedIds, $context)
+    {
+        //gather entities by type to pass all id with same type to the TimelineProvider. 
+        $idsByType = array();
+        
+        foreach($queriedIds as $result) {
+            $idsByType[$result['type']][] = $result['id'];
+        }
+        
+        //fetch entities from providers
+        $entitiesByType = array();
+        foreach ($idsByType as $type => $ids) {
+            //iterate providers for current context
+            foreach($this->getProvidersByContext($context) as $provider) {
+                if ($provider->supportsType($type)) {
+                    $entitiesByType[$type] = $provider->getEntities($ids);
+                    break; //we assume that providers have unique keys => we break the loop
+                }
+            }
+        }
+        
+        return $entitiesByType;
+    }
+    
+    /**
+     * render the timeline as HTML
+     * 
+     * @param array $fetched
+     * @param array $entitiesByType
+     * @param string $context
+     * @param mixed[] $args
+     * @return string the HTML representation of the timeline
+     */
+    private function render(array $fetched, array $entitiesByType, $context, array $args)
+    {
+        //add results to a pretty array
+        $timelineEntries = array();
+        foreach ($fetched as $result) {
+            $data = $this->getTemplateData(
+                    $result['type'], 
+                    $entitiesByType[$result['type']][$result['id']], //the entity
+                    $context,
+                    $args);
+            $timelineEntry['date'] = new \DateTime($result['date']);
+            $timelineEntry['template'] = $data['template'];
+            $timelineEntry['template_data'] = $data['template_data'];
+            
+            $timelineEntries[] = $timelineEntry;
+        }
+        
+        return $this->container->get('templating')
+                ->render('ChillMainBundle:Timeline:index.html.twig', array(
+                    'results' => $timelineEntries
+                ));
+        
+    }
+    
+    /**
+     * get the template data from the provider for the given entity, by type.
+     * 
+     * @param string $type
+     * @param mixed $entity
+     * @param string $context
+     * @param mixed[] $args
+     * @return array the template data fetched from the provider
+     */
+    private function getTemplateData($type, $entity, $context, array $args)
+    {
+        foreach($this->getProvidersByContext($context) as $provider) {
+            if ($provider->supportsType($type)) {
+                return $provider->getEntityTemplate($entity, $context, $args);
+            }
+        }
+    }
+}

Timeline/TimelineProviderInterface.php

@@ -0,0 +1,130 @@
+<?php
+
+/*
+ * Copyright (C) 2015 Julien Fastré <julien.fastre@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+namespace Chill\MainBundle\Timeline;
+
+/**
+ * Interface for service providing info to timeline
+ * 
+ * Services implementing those interface must be tagged like this :
+ * 
+ * ```
+ * services:
+ *    my_timeline:
+ *       class: My\Class
+ *       tags:
+ *          #a first 'person' context :
+ *          - { name: timeline, context: person }
+ *          # a second 'center' context :
+ *          - { name: timeline, context: center }
+ * ```
+ * 
+ * The bundle which will call the timeline will document available context and
+ * the arguments provided by the context.
+ * 
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ */
+interface TimelineProviderInterface
+{
+    
+    /**
+     * provide data to build a SQL SELECT query to fetch entities
+     * 
+     * The TimeLineBuilder will create a full SELECT query and append
+     * the query into an UNION of SELECT queries. This permit to fetch
+     * all entities from different table in a single query.
+     * 
+     * The associative array MUST have the following key :
+     * - `id` : the name of the id column
+     * - `type`: a string to indicate the type
+     * - `date`: the name of the datetime column, used to order entities by date
+     * - `FROM` (in capital) : the FROM clause. May contains JOIN instructions
+     * 
+     * Those key are optional:
+     * - `WHERE` (in capital) : the WHERE clause. 
+     * 
+     * Where relevant, the data must be quoted to avoid SQL injection.
+     * 
+     * `$context` and `$args` are defined by the bundle which will call the timeline
+     * rendering. 
+     * 
+     * @param string $context
+     * @param mixed[] $args the argument to the context.
+     * @return string[]
+     * @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
+     */
+    public function supportsType($type);
+
+    /**
+     * fetch entities from db into an associative array. The keys **MUST BE**
+     * the id
+     * 
+     * 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( 
+     *    'template'      => 'ChillMyBundle:timeline:template.html.twig',
+     *    'template_data' => array(
+     *             'accompanyingPeriod' => $entity, 
+     *              'person' => $args['person'] 
+     *         )
+     *    );
+     * ```
+     * 
+     * `$context` and `$args` are defined by the bundle which will call the timeline
+     * rendering. 
+     * 
+     * @param type $entity
+     * @param type $context
+     * @param array $args
+     * @return mixed[]
+     * @throws \LogicException if the context is not supported
+     */
+    public function getEntityTemplate($entity, $context, array $args);
+ 
+}