Skip to content

Commit

Permalink
minor #47 Added some PhpDoc for IDE-using developers (Pierstoval)
Browse files Browse the repository at this point in the history 
This PR was merged into the master branch.

Discussion
----------

Added some PhpDoc for IDE-using developers

I'm using PHPStorm and when I want to modify the AdminController, I have many many "warning" alerts, and there is not much auto-completion, so I decided to update all PHPDocs and typings to have a more fluid dev environment with this great IDE 😄

Commits
-------

91fab23 Added some PhpDoc for IDEs users
  • Loading branch information
@javiereguiluz
javiereguiluz committed Jan 19, 2015
2 parents d55d1cd + 91fab23 commit 269c1d2
Showing 1 changed file with 148 additions and 5 deletions.
153 changes: 148 additions & 5 deletions Controller/AdminController.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,10 @@

namespace JavierEguiluz\Bundle\EasyAdminBundle\Controller;

use Doctrine\Common\Persistence\ObjectManager;
use Doctrine\ORM\EntityManager;
use Doctrine\ORM\Mapping\ClassMetadata;
use Symfony\Component\Form\Form;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
Expand All @@ -26,20 +29,36 @@
use Pagerfanta\Pagerfanta;
use Pagerfanta\Adapter\DoctrineORMAdapter;

/**
* Class AdminController
* @package JavierEguiluz\Bundle\EasyAdminBundle\Controller
*/
class AdminController extends Controller
{
/**
* @var array
*/
protected $allowedActions = array('list', 'edit', 'new', 'show', 'search', 'delete');
/**
* @var
*/
protected $config;
/**
* @var array
*/
protected $entity = array();

/** @var Request */
protected $request;

/** @var ObjectManager */
/** @var EntityManager */
protected $em;

/**
* @Route("/", name="admin")
* @param Request $request
*
* @return RedirectResponse|Response
*/
public function indexAction(Request $request)
{
Expand All @@ -61,6 +80,11 @@ public function indexAction(Request $request)
return $this->{$action.'Action'}();
}

/**
* @param Request $request
*
* @return Response|null
*/
protected function initialize(Request $request)
{
$this->config = $this->container->getParameter('easy_admin.config');
Expand Down Expand Up @@ -94,8 +118,13 @@ protected function initialize(Request $request)
}

$this->request = $request;

return null;
}

/**
* @return Response
*/
public function listAction()
{
$fields = $this->getFieldsForList($this->entity['fieldMappings']);
Expand All @@ -109,6 +138,9 @@ public function listAction()
));
}

/**
* @return RedirectResponse|Response
*/
public function editAction()
{
if (!$item = $this->em->getRepository($this->entity['class'])->find($this->request->query->get('id'))) {
Expand All @@ -121,7 +153,7 @@ public function editAction()

$editForm->handleRequest($this->request);
if ($editForm->isValid()) {
$item = $this->prepareEditEntityForPersist($item);
$this->prepareEditEntityForPersist($item);
$this->em->flush();

return $this->redirect($this->generateUrl('admin', array('action' => 'list', 'entity' => $this->entity['name'])));
Expand All @@ -136,6 +168,9 @@ public function editAction()
));
}

/**
* @return Response
*/
public function showAction()
{
if (!$item = $this->em->getRepository($this->entity['class'])->find($this->request->query->get('id'))) {
Expand All @@ -154,6 +189,9 @@ public function showAction()
));
}

/**
* @return RedirectResponse|Response
*/
public function newAction()
{
$entityFullyQualifiedClassName = $this->entity['class'];
Expand All @@ -179,9 +217,12 @@ public function newAction()
));
}

/**
* @return RedirectResponse
*/
public function deleteAction()
{
if ('DELETE' !== $this->request->query->getMethod()) {
if ('DELETE' !== $this->request->getMethod()) {
return $this->redirect($this->generateUrl('admin', array('action' => 'list', 'entity' => $this->entity['name'])));
}

Expand All @@ -200,6 +241,9 @@ public function deleteAction()
return $this->redirect($this->generateUrl('admin', array('action' => 'list', 'entity' => $this->entity['name'])));
}

/**
* @return Response
*/
public function searchAction()
{
$searchableFields = $this->getSearchableFields($this->entity['fieldMappings']);
Expand All @@ -216,6 +260,10 @@ public function searchAction()

/**
* Takes the FQCN of the Doctrine entity and returns all its configured metadata.
*
* @param string $entityName Entity FQCN
*
* @return array
*/
protected function getEntityMetadata($entityName)
{
Expand All @@ -224,11 +272,12 @@ protected function getEntityMetadata($entityName)
$entityMetadata['name'] = $entityName;
$entityMetadata['class'] = $this->config['entities'][$entityName]['class'];

/** @var ClassMetadata $doctrineMetadata */
$doctrineMetadata = $this->em->getMetadataFactory()->getMetadataFor($entityMetadata['class']);

// TODO: Check if the entity performs any kind of inheritance: $doctrineMetadata->isInheritanceTypeNone()

if ('id' !== $doctrineMetadata->identifier[0]) {
if ('id' !== $doctrineMetadata->getSingleIdentifierFieldName()) {
throw new \RuntimeException(sprintf("The '%s' entity isn't valid because it doesn't define a primary key called 'id'.", $entityMetadata['class']));
}

Expand Down Expand Up @@ -260,6 +309,9 @@ protected function getEntityMetadata($entityName)
/**
* Allows applications to modify the entity associated with the item being
* edited before persisting it.
*
* @param object $entity
* @return object
*/
protected function prepareEditEntityForPersist($entity)
{
Expand All @@ -269,6 +321,9 @@ protected function prepareEditEntityForPersist($entity)
/**
* Allows applications to modify the entity associated with the item being
* created before persisting it.
*
* @param object $entity
* @return object
*/
protected function prepareNewEntityForPersist($entity)
{
Expand All @@ -277,6 +332,10 @@ protected function prepareNewEntityForPersist($entity)

/**
* These are the entity fields on which the query is performed.
*
* @param array $entityFields
*
* @return array
*/
protected function getSearchableFields(array $entityFields)
{
Expand All @@ -288,6 +347,10 @@ protected function getSearchableFields(array $entityFields)

/**
* These are the entity fields displayed in the listings.
*
* @param array $entityFields
*
* @return array
*/
protected function getFieldsForList(array $entityFields)
{
Expand All @@ -300,6 +363,12 @@ protected function getFieldsForList(array $entityFields)
}
}

/**
* @param array $fields
* @param array $whiteList
*
* @return array
*/
protected function filterEntityFieldsBasedOnWhitelist(array $fields, array $whiteList)
{
$filteredFields = array();
Expand All @@ -323,6 +392,13 @@ protected function filterEntityFieldsBasedOnWhitelist(array $fields, array $whit
return $filteredFields;
}

/**
* @param array $fields
* @param array $fieldNameBlackList
* @param array $fieldTypeBlackList
*
* @return array
*/
protected function filterEntityFieldsBasedOnNameAndTypeBlackList(array $fields, array $fieldNameBlackList, array $fieldTypeBlackList)
{
$filteredFields = array();
Expand All @@ -336,6 +412,11 @@ protected function filterEntityFieldsBasedOnNameAndTypeBlackList(array $fields,
return $filteredFields;
}

/**
* @param array $fields
*
* @return array
*/
protected function filterListFieldsBasedOnSmartGuesses(array $fields)
{
// empirical guess: listings with more than 8 fields look ugly
Expand Down Expand Up @@ -367,6 +448,10 @@ protected function filterListFieldsBasedOnSmartGuesses(array $fields)

/**
* These are the entity fields displayed in the 'show' action.
*
* @param array $entityFields
*
* @return array
*/
protected function getFieldsForShow(array $entityFields)
{
Expand All @@ -375,12 +460,25 @@ protected function getFieldsForShow(array $entityFields)

/**
* These are the fields displayed in the search results listings
*
* @param array $entityFields
*
* @return array
*/
protected function getFieldsForSearch(array $entityFields)
{
return $this->getFieldsForList($entityFields);
}

/**
* @param string $entityClass
* @param int $page
* @param int $maxPerPage
* @param string $sortField
* @param string $sortDirection
*
* @return Pagerfanta
*/
protected function findAll($entityClass, $page = 1, $maxPerPage = 15, $sortField = null, $sortDirection = null)
{
$query = $this->em->createQueryBuilder()
Expand All @@ -403,6 +501,15 @@ protected function findAll($entityClass, $page = 1, $maxPerPage = 15, $sortField
return $paginator;
}

/**
* @param string $entityClass
* @param string $searchQuery
* @param array $searchableFields
* @param int $page
* @param int $maxPerPage
*
* @return Pagerfanta
*/
protected function findBy($entityClass, $searchQuery, array $searchableFields, $page = 1, $maxPerPage = 15)
{
$query = $this->em->createQueryBuilder()
Expand All @@ -421,6 +528,12 @@ protected function findBy($entityClass, $searchQuery, array $searchableFields, $
return $paginator;
}

/**
* @param object $entity
* @param array $entityFieldsMapping
*
* @return Form
*/
protected function createEditForm($entity, array $entityFieldsMapping)
{
$formTypeMap = array(
Expand Down Expand Up @@ -451,6 +564,10 @@ protected function createEditForm($entity, array $entityFieldsMapping)

/**
* These are the entity fields included in the form displayed for the 'edit' action.
*
* @param array $entityFields
*
* @return array
*/
protected function getFieldsForEdit(array $entityFields)
{
Expand All @@ -466,6 +583,11 @@ protected function getFieldsForEdit(array $entityFields)
return $this->filterEntityFieldsBasedOnNameAndTypeBlackList($entityFields, $excludedFieldNames, $excludedFieldTypes);
}

/**
* @param array $entityFields
*
* @return array
*/
protected function getFieldsForNew(array $entityFields)
{
$entityConfiguration = $this->config['entities'][$this->entity['name']];
Expand All @@ -480,18 +602,33 @@ protected function getFieldsForNew(array $entityFields)
return $this->filterEntityFieldsBasedOnNameAndTypeBlackList($entityFields, $excludedFieldNames, $excludedFieldTypes);
}

/**
* @param object $entity
* @param array $entityFieldsMapping
*
* @return Form
*/
protected function createNewForm($entity, array $entityFieldsMapping)
{
return $this->createEditForm($entity, $entityFieldsMapping);
}

/**
* @return mixed
*/
protected function getNameOfTheFirstConfiguredEntity()
{
$entityNames = array_keys($this->config['entities']);

return $entityNames[0];
}

/**
* @param string $entityName
* @param integer $entityId
*
* @return Form
*/
protected function createDeleteForm($entityName, $entityId)
{
return $this->createFormBuilder()
Expand All @@ -502,6 +639,12 @@ protected function createDeleteForm($entityName, $entityId)
;
}

/**
* @param string $view
* @param array $parameters
*
* @return Response
*/
protected function render404error($view, array $parameters = array())
{
return $this->render($view, $parameters, new Response('', 404));
Expand Down

0 comments on commit 269c1d2

Please sign in to comment.