diff --git a/ChillMainBundle.php b/ChillMainBundle.php index bb4c675a7..59bf33e50 100644 --- a/ChillMainBundle.php +++ b/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()); } } diff --git a/DependencyInjection/SearchableServicesCompilerPass.php b/DependencyInjection/SearchableServicesCompilerPass.php index ed2903cc5..12f27933e 100644 --- a/DependencyInjection/SearchableServicesCompilerPass.php +++ b/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.'); } diff --git a/DependencyInjection/TimelineCompilerClass.php b/DependencyInjection/TimelineCompilerClass.php new file mode 100644 index 000000000..4fad76538 --- /dev/null +++ b/DependencyInjection/TimelineCompilerClass.php @@ -0,0 +1,66 @@ + + * + * 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 . + */ + +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é + */ +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) + ); + } + } + } + +} diff --git a/Resources/config/services.yml b/Resources/config/services.yml index 793c1f3da..e0dcbf936 100644 --- a/Resources/config/services.yml +++ b/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"]] diff --git a/Resources/views/Timeline/index.html.twig b/Resources/views/Timeline/index.html.twig new file mode 100644 index 000000000..062e62c74 --- /dev/null +++ b/Resources/views/Timeline/index.html.twig @@ -0,0 +1,8 @@ +
+{% for result in results %} +
+ {% include result.template with result.template_data %} +
+ +{% endfor %} +
\ No newline at end of file diff --git a/Timeline/TimelineBuilder.php b/Timeline/TimelineBuilder.php new file mode 100644 index 000000000..6899d224b --- /dev/null +++ b/Timeline/TimelineBuilder.php @@ -0,0 +1,262 @@ + + * + * 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 . + */ + +namespace Chill\MainBundle\Timeline; + +use Doctrine\ORM\Query\ResultSetMapping; +use Doctrine\ORM\EntityManagerInterface; +use Symfony\Component\DependencyInjection\ContainerAwareInterface; + +/** + * Build timeline + * + * @author Julien Fastré + */ +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); + } + } + } +} diff --git a/Timeline/TimelineProviderInterface.php b/Timeline/TimelineProviderInterface.php new file mode 100644 index 000000000..3406186fc --- /dev/null +++ b/Timeline/TimelineProviderInterface.php @@ -0,0 +1,130 @@ + + * + * 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 . + */ + +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é + */ +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); + +}