Previous Next
PHP/Symfony Data Jukebox Tutorial Bundle

PHP/Symfony Data Jukebox Tutorial Bundle - The Tutorial

Learn to forget all about views and concentrate entirely on the model.

http://www.idiap.ch/scientific-research/resources/symfony-bundle-datajukebox

Table of Contents

The philosophy behind the Data Jukebox Bundle

The Data Jukebox Bundle sticks to Symfony philosophy as much as possible. Shortly put, one defines Entities, which are then manipulated - in the Controller - thanks to a corresponding (standard or customized) Repository. Rendering is achieved via Template while localization is done thanks to translation files.

The Data Jukebox Bundle simply adds Properties to the picture, which corresponds to a PHP class where specific methods - matching the PropertiesInterface definition - allow to retrieve additional meta-data about the corresponding Entity and construct - entirely automatically - the views for the common CRUD (Create-Read-Update-Delete) operations.

The one aspect where the Data Jukebox Bundle differs from Symfony is the way it deals with joined entities. Shortly put: it doesn't! Read operations can not use joined entities the way Symfony does. The idea behind this design decision is that joining entities fields (aka. tables columns) for read purposes is something that is better achieved in SQL views, with all the power of the database engine backing the operation. Thus, while relationships can still be defined and used according to Symfony philosophy when dealing with forms - even within the Data Jukebox Bundle realm - they must be "resolved" at the SQL (view) level when dealing with read actions, with joined columns being returned as scalar values rather than entities (objects). This distinction between the two purposes is implemented using entity inheritance, where an abstract MappedSuperclass acts as parent for one standard, table-backed Entity and another joined, view-backed (View)Entity.

A sample blog application

A sample blog application will be used to illustrate how to use the Data Jukebox Bundle.

Blog Category

To start with, we will define a Blog Category Entity:

  1. <?php
  2. namespace DataJukeboxTutorialBundle\Entity;
  3.  
  4. use Doctrine\ORM\Mapping as ORM;
  5. use DataJukeboxBundle\Annotations\Properties;
  6.  
  7. /** Blog category entity
  8.  * @ORM\Entity
  9.  * @ORM\Table(name="SampleBlogCategory")
  10.  * @Properties(propertiesClass="DataJukeboxTutorialBundle\Properties\SampleBlogCategoryProperties")
  11.  */
  12. class SampleBlogCategoryEntity
  13.   implements \DataJukeboxBundle\DataJukebox\PrimaryKeyInterface
  14. {
  15.  
  16.   /*
  17.    * PROPERTIES
  18.    ********************************************************************************/
  19.  
  20.   /** Primary key
  21.    * @var integer 
  22.    * @ORM\Column(name="pk", type="integer")
  23.    * @ORM\Id
  24.    * @ORM\GeneratedValue
  25.    */
  26.   protected $PK;
  27.  
  28.   /** Name
  29.    * @var string 
  30.    * @ORM\Column(name="Name_vc", type="string", length=100)
  31.    */
  32.   protected $Name;
  33.  
  34.   // ...
  35.  
  36.   /*
  37.    * METHODS
  38.    ********************************************************************************/
  39.  
  40.   // Setters/Getters/...
  41.  
  42.  
  43.   /*
  44.    * METHODS: PrimaryKeyInterface
  45.    ********************************************************************************/
  46.  
  47.   public function getPrimaryKey()
  48.   {
  49.     return array('PK' => $this->PK);
  50.   }
  51.  
  52. }

The only way it differs from a standard Symfony entity:

  • it implements the Data Jukebox PrimaryKeyInterface and the corresponding getPrimaryKey method
  • it declares a corresponding Properties class, using the annotation @Properties(propertiesClass="...")

    • We will cover those changes when dealing with the application core entity (see below).

    Blog Entry

    We will now define the Blog Entry resources.

    Given the many-to-one relationship with the Blog Category entity and Data Jukebox way of dealing with those, we must first define the parent abstract SuperClass:

    1. <?php
    2. namespace DataJukeboxTutorialBundle\Entity;
    3.  
    4. use Doctrine\ORM\Mapping as ORM;
    5.  
    6. /** Blog entry superclass
    7.  * @ORM\MappedSuperclass
    8.  */
    9. class SampleBlogEntrySuperclass
    10.   implements \DataJukeboxBundle\DataJukebox\PrimaryKeyInterface
    11. {
    12.  
    13.   /*
    14.    * PROPERTIES
    15.    ********************************************************************************/
    16.  
    17.   /** Primary key
    18.    * @var integer 
    19.    * @ORM\Column(name="pk", type="integer")
    20.    * @ORM\Id
    21.    * @ORM\GeneratedValue
    22.    */
    23.   protected $PK;
    24.  
    25.   /** Title
    26.    * @var string 
    27.    * @ORM\Column(name="Title_vc", type="string", length=100)
    28.    */
    29.   protected $Title;
    30.  
    31.   /** Date
    32.    * @var \DateTime 
    33.    * @ORM\Column(name="Date_d", type="date")
    34.    */
    35.   protected $Date;
    36.  
    37.   // ...
    38.  
    39.   /*
    40.    * METHODS
    41.    ********************************************************************************/
    42.  
    43.   // Getters/...
    44.  
    45.  
    46.   /*
    47.    * METHODS: PrimaryKeyInterface
    48.    ********************************************************************************/
    49.  
    50.   public function getPrimaryKey()
    51.   {
    52.     return array('PK' => $this->PK);
    53.   }
    54.  
    55. }

    Then we can define the corresponding "standard", table-backed Entity (for create/update purposes):

    1. <?php
    2. namespace DataJukeboxTutorialBundle\Entity;
    3.  
    4. use Doctrine\ORM\Mapping as ORM;
    5. use DataJukeboxBundle\Annotations\Properties;
    6.  
    7. /** Blog entry entity (for create/update purposes)
    8.  * @ORM\Entity
    9.  * @ORM\Table(name="SampleBlogEntry")
    10.  * @Properties(propertiesClass="DataJukeboxTutorialBundle\Properties\SampleBlogEntryProperties")
    11.  */
    12. class SampleBlogEntryEntity
    13.   extends SampleBlogEntrySuperclass
    14. {
    15.  
    16.   /*
    17.    * PROPERTIES
    18.    ********************************************************************************/
    19.  
    20.   /** Category (entity)
    21.    * @var SampleBlogCategoryEntity 
    22.    * @ORM\ManyToOne(targetEntity="SampleBlogCategoryEntity")
    23.    * @ORM\JoinColumn(name="Category_fk", referencedColumnName="pk")
    24.    */
    25.   protected $Category;
    26.  
    27.  
    28.   /*
    29.    * METHODS
    30.    ********************************************************************************/
    31.  
    32.   // Setters/Getters/...
    33.  
    34. }

    And its joined, view-backed Entity (for read purposes), where the Category is no longer an entity/object, but a scalar (string) corresponding to the category name:

    1. <?php
    2. namespace DataJukeboxTutorialBundle\Entity;
    3.  
    4. use Doctrine\ORM\Mapping as ORM;
    5. use DataJukeboxBundle\Annotations\Properties;
    6.  
    7. /** Blog entry (view) entity (for reading purposes)
    8.  * @ORM\Entity
    9.  * @ORM\Table(name="SampleBlogEntry_view")
    10.  * @Properties(propertiesClass="DataJukeboxTutorialBundle\Properties\SampleBlogEntryProperties")
    11.  */
    12. class SampleBlogEntryViewEntity
    13.   extends SampleBlogEntrySuperclass
    14. {
    15.  
    16.   /*
    17.    * PROPERTIES
    18.    ********************************************************************************/
    19.  
    20.   /** Category (foreign key)
    21.    * @var integer 
    22.    * @ORM\Column(name="Category_fk", type="integer")
    23.    */
    24.   protected $CategoryFK;
    25.  
    26.   /** Category (name)
    27.    * @var string 
    28.    * @ORM\Column(name="Category_vc", type="string", length=100)
    29.    */
    30.   protected $Category;
    31.  
    32.  
    33.   /*
    34.    * METHODS
    35.    ********************************************************************************/
    36.  
    37.   // Getters/...
    38.  
    39. }

    Primary Key Interface

    The Primary Key Interface and its sole getPrimaryKey() method are here to simplify the process of retrieving the entity primary key name(s)/value(s) pair(s). If an entity has more than one field acting as identifier - thus corresponding to a composite primary key - one must just make sure to include all identifier fields in the returned array.

    Properties

    The entity associated Properties is where all the magic of the Data Jukebox Bundle takes its root:

    1. <?php
    2. namespace DataJukeboxTutorialBundle\Properties;
    3.  
    4. class SampleBlogEntryProperties
    5.   extends \DataJukeboxBundle\DataJukebox\Properties
    6.   implements \DataJukeboxBundle\DataJukebox\FormatInterface
    7. {
    8.  
    9.   /*
    10.    * CONSTANTS
    11.    ********************************************************************************/
    12.  
    13.   /** Administration authorization level
    14.    * @var integer 
    15.    */
    16.   const AUTH_ADMIN = 9;
    17.  
    18.  
    19.   /*
    20.    * METHODS: Properties(Interface)
    21.    ********************************************************************************/
    22.  
    23.   // Return whether the defined action is authorized
    24.   // at the defined authorization level
    25.   public function isAuthorized()
    26.   {
    27.     switch ($this->getAction()) {
    28.     case 'list':
    29.     case 'detail':
    30.       return true;
    31.     case 'insert':
    32.     case 'update':
    33.     case 'delete':
    34.       return $this->getAuthorization() >= self::AUTH_ADMIN;
    35.     }
    36.     return parent::isAuthorized();
    37.   }
    38.  
    39.   // Return the routes for the various CRUD operations
    40.   public function getRoutes()
    41.   {
    42.     // As per authorization level
    43.     if ($this->getAuthorization() >= self::AUTH_ADMIN) {
    44.       switch ($this->getAction()) {
    45.       case 'list':
    46.         return array(
    47.           'detail' => array('SampleBlogEntry_view'),
    48.           'insert' => array('SampleBlogEntry_edit'),
    49.           'delete' => array('SampleBlogEntry_delete'),
    50.           'select_delete' => array('SampleBlogEntry_delete'),
    51.         );
    52.       case 'detail':
    53.         return array(
    54.           'list' => array('SampleBlogEntry_view'),
    55.           'update' => array('SampleBlogEntry_edit'),
    56.           'delete' => array('SampleBlogEntry_delete'),
    57.         );
    58.       }
    59.     }
    60.  
    61.     // Default
    62.     switch ($this->getAction()) {
    63.     case 'list':
    64.       return array(
    65.         'detail' => array('SampleBlogEntry_view'),
    66.       );
    67.     case 'detail':
    68.       return array(
    69.         'list' => array('SampleBlogEntry_view'),
    70.       );
    71.     }
    72.  
    73.     // Fallback
    74.     return parent::getRoutes();
    75.   }
    76.  
    77.   // Return the (localized) fields labels
    78.   public function getLabels()
    79.   {
    80.     return array_merge(
    81.       parent::getLabels(),
    82.       $this->getMeta('label', 'SampleBlogEntry')
    83.     );
    84.   }
    85.  
    86.   // Return the (localized) fields tooltips
    87.   public function getTooltips()
    88.   {
    89.     return array_merge(
    90.       parent::getTooltips(),
    91.       $this->getMeta('tooltip', 'SampleBlogEntry')
    92.     );
    93.   }
    94.  
    95.   // Return the fields allowed to query/display
    96.   public function getFields()
    97.   {
    98.     switch ($this->getAction()) {
    99.     case 'list':
    100.       return array('Title', 'Date', 'Category', 'Tags');
    101.     }
    102.     return array('Title', 'Date', 'Category', 'Content', 'Tags');
    103.   }
    104.  
    105.   // Return the fields to query/display by default
    106.   public function getFieldsDefault()
    107.   {
    108.     switch ($this->getAction()) {
    109.     case 'list':
    110.       return array('Title', 'Date', 'Category');
    111.     }
    112.     return parent::getFieldsDefault();
    113.   }
    114.  
    115.   // Return the fields that must be kept hidden
    116.   public function getFieldsHidden()
    117.   {
    118.     return array_merge(
    119.       array('PK', 'CategoryFK'),
    120.       parent::getFieldsHidden()
    121.     );
    122.   }
    123.  
    124.   // Return the fields that must be displayed or data-filled
    125.   public function getFieldsRequired()
    126.   {
    127.     switch ($this->getAction()) {
    128.     case 'list':
    129.     case 'detail':
    130.       return array('CategoryFK', 'Title');
    131.     case 'insert':
    132.     case 'update':
    133.       return array('Title', 'Date', 'Category', 'Content');
    134.     }
    135.     return parent::getFieldsRequired();
    136.   }
    137.  
    138.   // Return the fields that may not be modified
    139.   public function getFieldsReadonly()
    140.   {
    141.     switch ($this->getAction()) {
    142.     case 'update':
    143.       return array('Date');
    144.     }
    145.     return parent::getFieldsReadOnly();
    146.   }
    147.  
    148.   // Return the default value for specific fields
    149.   public function getFieldsDefaultValue()
    150.   {
    151.     return array(
    152.       'Date' => new \DateTime(),
    153.     );
    154.   }
    155.  
    156.   // Return the links to associate with each field
    157.   public function getFieldsLink()
    158.   {
    159.     switch ($this->getAction()) {
    160.     case 'list':
    161.       return array_merge(
    162.         array(
    163.           'Title' => array('path', 'SampleBlogEntry_view', array('_pk' => 'PK')),
    164.         ),
    165.         parent::getFieldsLink()
    166.       );
    167.     case 'detail':
    168.       return array_merge(
    169.         array(
    170.           'Category' => array('path', 'SampleBlogCategory_view', array('_pk' => 'CategoryFK')),
    171.         ),
    172.         parent::getFieldsLink()
    173.       );
    174.     }
    175.     return parent::getFieldsLink();
    176.   }
    177.  
    178.   // Return the fields that may be used for sorting list views
    179.   public function getFieldsOrder()
    180.   {
    181.     return array_merge(
    182.       array('Date'),
    183.       parent::getFieldsOrder()
    184.     );
    185.   }
    186.  
    187.   // Return the fields that may be used for filtering list views
    188.   public function getFieldsFilter()
    189.   {
    190.     return array('Title', 'Date', 'Category', 'Tags');
    191.   }
    192.  
    193.   // Return the fields that are used for searching data (in list views)
    194.   public function getFieldsSearch()
    195.   {
    196.     return array('Title', 'Content');
    197.   }
    198.  
    199.   // Return the additional links to create in views
    200.   public function getFooterLinks()
    201.   {
    202.     switch ($this->getAction()) {
    203.     case 'detail':
    204.       return array_merge(
    205.         array(
    206.           '_view_list' => array('path+query', 'SampleBlogEntry_view', null, '⊛'),
    207.         ),
    208.         parent::getFooterLinks()
    209.       );
    210.     }
    211.     return parent::getFooterLinks();
    212.   }
    213.  
    214.   // Return the Twig template for each action
    215.   public function getTemplate()
    216.   {
    217.     switch ($this->getAction()) {
    218.     case 'list':
    219.       return '@DataJukeboxTutorial/list.html.twig';
    220.     case 'detail':
    221.       return '@DataJukeboxTutorial/detail.html.twig';
    222.     case 'insert':
    223.     case 'update':
    224.       return '@DataJukeboxTutorial/form.html.twig';
    225.     }
    226.     throw new \Exception(sprintf('Invalid action (%s)', $this->getAction()));
    227.   }
    228.  
    229.  
    230.   /*
    231.    * METHODS: FormatInterface
    232.    ********************************************************************************/
    233.  
    234.   // Custom formatting for specific fields
    235.   public function formatFields(array &$aRow, $iIndex) {
    236.     if (isset($aRow['Date'])) $aRow['Date_formatted'] = $aRow['Date']->format('r');
    237.   }
    238.  
    239. }

    Ok, this is a lengthy definition... but at the end of the day, it says all there is to know about the entity in order to create all views - for create/read/update/delete purposes - automatically, while respecting the business logic that backs the entity.

    Controller

    We can now create the Controller that will create all those views:

    1. <?php
    2. namespace DataJukeboxTutorialBundle\Controller;
    3.  
    4. use Symfony\Component\HttpFoundation\Request;
    5. use Symfony\Bundle\FrameworkBundle\Controller\Controller;
    6. use Symfony\Component\Security\Core\Exception\AccessDeniedException;
    7.  
    8. use DataJukeboxTutorialBundle\Properties\SampleBlogEntryProperties;
    9.  
    10. class SampleBlogEntryController
    11.   extends Controller
    12. {
    13.  
    14.   public function getAuthorization()
    15.   {
    16.     $oSecurityAuthorizationChecker = $this->get('security.authorization_checker');
    17.     if ($oSecurityAuthorizationChecker->isGranted('ROLE_BLOG_ADMIN')) return SampleBlogEntryProperties::AUTH_ADMIN;
    18.     return SampleBlogEntryProperties::AUTH_PUBLIC;
    19.   }
    20.  
    21.   public function viewAction($_pk, Request $oRequest)
    22.   {
    23.     // Properties
    24.     $oDataJukebox = $this->get('DataJukebox');
    25.     $iAuthorization = $this->getAuthorization();
    26.     $oProperties = $oDataJukebox->getProperties('DataJukeboxTutorialBundle:SampleBlogEntryViewEntity')
    27.                                 ->setAuthorization($iAuthorization)
    28.                                 ->setAction(is_null($_pk) ? 'list' : 'detail')
    29.                                 ->setTranslator($this->get('translator'));
    30.     if (!$oProperties->isAuthorized()) throw new AccessDeniedException();
    31.  
    32.     // Browsing
    33.     $oBrowser = $oProperties->getBrowser($oRequest);
    34.     if (is_null($_pk) and !$oBrowser->getFieldsOrder()) $oBrowser->setFieldsOrder('Date_D');
    35.  
    36.     // Data query
    37.     $oRepository = $oDataJukebox->getRepository($oProperties);
    38.     $oResult = $oRepository->getDataResult($_pk, $oBrowser);
    39.  
    40.     // Response
    41.     return $this->render(
    42.       $oProperties->getTemplate(),
    43.       array('data' => $oResult->getTemplateData())
    44.     );
    45.   }
    46.  
    47.   public function editAction($_pk, Request $oRequest)
    48.   {
    49.     // Properties
    50.     $oDataJukebox = $this->get('DataJukebox');
    51.     $iAuthorization = $this->getAuthorization();
    52.     $oProperties = $oDataJukebox->getProperties('DataJukeboxTutorialBundle:SampleBlogEntryEntity')
    53.                                 ->setAuthorization($iAuthorization)
    54.                                 ->setAction(is_null($_pk) ? 'insert' : 'update')
    55.                                 ->setTranslator($this->get('translator'));
    56.     if (!$oProperties->isAuthorized()) throw new AccessDeniedException();
    57.  
    58.     // Data query
    59.     $oRepository = $oDataJukebox->getRepository($oProperties);
    60.     $oData = is_null($_pk) ? null : $oRepository->getDataEntity($_pk);
    61.  
    62.     // Form resources
    63.     $oFormType = $oDataJukebox->getFormType($oProperties);
    64.     $oForm = $this->createForm($oFormType, $oData);
    65.  
    66.     // Form handling
    67.     $oForm->handleRequest($oRequest);
    68.     if ($oForm->isValid()) {
    69.       $oData = $oForm->getData();
    70.       $oEntityManager = $oProperties->getEntityManager();
    71.       $oEntityManager->persist($oData);
    72.       $oEntityManager->flush();
    73.       return $this->redirectToRoute('SampleBlogEntry_view', $oFormType->getPrimaryKeySlug($oData));
    74.     }
    75.  
    76.     // Response
    77.     return $this->render(
    78.       $oProperties->getTemplate(),
    79.       array(
    80.         'form' => $oForm->createView(),
    81.         'data' => array('properties' => $oProperties->getTemplateData()),
    82.       )
    83.     );
    84.   }
    85.  
    86.   public function deleteAction($_pk, Request $oRequest)
    87.   {
    88.     // Properties
    89.     $oDataJukebox = $this->get('DataJukebox');
    90.     $iAuthorization = $this->getAuthorization();
    91.     $oProperties = $oDataJukebox->getProperties('DataJukeboxTutorialBundle:SampleBlogEntryEntity')
    92.                                 ->setAuthorization($iAuthorization)
    93.                                 ->setAction('delete');
    94.     if (!$oProperties->isAuthorized()) throw new AccessDeniedException();
    95.  
    96.     // Data primary keys (potentially passed by HTTP POST)
    97.     if (is_null($_pk)) {
    98.       $asPK = \DataJukeboxBundle\DataJukebox\Browser::getPrimaryKeys($oRequest);
    99.     } else {
    100.       $asPK = array($_pk);
    101.     }
    102.  
    103.     // Data query
    104.     if (count($asPK)) {
    105.       $oRepository = $oDataJukebox->getRepository($oProperties);
    106.       $oEntityManager = $oProperties->getEntityManager();
    107.       foreach ($asPK as $sPK) {
    108.         $oData = $oRepository->getDataEntity($sPK);
    109.         $oEntityManager->remove($oData);
    110.       }
    111.       $oEntityManager->flush();
    112.     }
    113.  
    114.     // Response
    115.     return $this->redirectToRoute('SampleBlogEntry_view', $oRequest->query->all());
    116.   }
    117.  
    118. }

    ... and this is it!

    Tips and Tricks

    A few things are worth noting when using the Data Jukebox Bundle:

  • Primary Key (Route) Parameter: the primary key parameter in Data Jukebox routes and controllers MUST be _pk, even for entities that have a composite (multiple-fields) primary key.
  • Twig Template: you can customite the views as you deem fit, using (Symfony) form and (Data Jukebox) DataJukebox_list/DataJukebox_detail functions in your Twig templates (Note: PHP templates are NOT supported).
  • Localization: is achieved using Symfony standard translations files, along the handy getMeta method in your Properties; just make sure to specify the correct translation domain.
    • Previous Next
    PHP/Symfony Data Jukebox Tutorial Bundle

    Documentation generated on Wed, 15 Nov 2017 15:15:10 +0100 by phpDocumentor 1.4.4