Commit 4f6ddac8 by Dirk Benkert

added source documentation to all classes and files

parent 59a98ac3
......@@ -119,3 +119,12 @@ If you want to customize the email templates used for invitation and forgot pass
* [Dirk Benkert](https://gitlab.dirk-benkert.de/u/dbenkert)
* [Nico Plötz](https://gitlab.dirk-benkert.de/u/nitom)
## Documentation
use apigen to generate source documentation
```
cd vendor/bin
./apigen generate -s ../../modules -d ../../docs --todo --deprecated
```
to generate the apigen documentation
\ No newline at end of file
......@@ -18,11 +18,13 @@
"minimum-stability": "dev",
"require": {
"php": ">=5.3.3",
"apigen/apigen": "dev-master",
"zendframework/zendframework": "2.4.*",
"doctrine/orm": "2.4.*",
"doctrine/doctrine-orm-module": "0.8.0",
"hounddog/doctrine-data-fixture-module": "dev-master",
"widmogrod/zf2-mustache-module": "dev-master"
},
"require-dev": {
"apigen/apigen": "dev-master"
}
}
......@@ -28,12 +28,15 @@ use Zend\Session\SessionManager;
use Zend\Session\Container;
use Zend\Console\Request as ConsoleRequest;
/**
* Module initialization
*
* @package Administration
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) 2015 Dirk Benkert
*/
class Module {
public function init(ModuleManager $moduleManager) {
// ModuleManager has events for loading Modules and loading.post of a Module
}
public function onBootstrap($e) {
//$eventManager = $e->getApplication()->getEventManager();
//[0] => route
......
......@@ -28,31 +28,123 @@ use Zend\View\Model\ViewModel;
use Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException;
use Application\Util\Text;
/**
* Controller plugin for CRUD operations
*
* @package Administration_Controller_Plugin
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) 2015 Dirk Benkert
*/
class Crud extends AbstractPlugin {
/**
* option key for the entity object
*/
const ENTITY = 'entity';
/**
* option key for the id column
*/
const ID_COLUMN = 'id';
/**
* option key for the default values
*/
const DEFAULT_VALUES = 'defaultValues';
/**
* option key for the form object
*/
const FORM = 'form';
/**
* option key for routing information
*/
const ROUTE = 'route';
/**
* option key for the edit element
*/
const EDIT_TEMPLATE = 'editTemplate';
/**
* option key for messages
*/
const MESSAGES = 'messages';
/**
* option key for message string replacements
*/
const REPLACEMENTS = 'replacements';
/**
* option key for child entities
*/
const CHILD_ENTITIES = 'childEntities';
/**
* option key for file upload element
*/
const UPLOAD_ELEMENT_NAME = 'upload_element_name';
/**
* option key for element persistor
*/
const PERSISTOR = 'persistor';
/**
* option key for new entry message
*/
const MSG_NEW_ENTRY = 0;
/**
* option key for entry saved message
*/
const MSG_ENTRY_SAVED = 1;
/**
* option key for entry deleted message
*/
const MSG_ENTRY_DELETED = 2;
/**
* Options
*
* @var array
*/
protected $options = array();
/**
* Entity
*
* @var object
*/
protected $entity = null;
/**
* Id
*
* @var int
*/
protected $id = null;
/**
* Setter
*
* @param array $options
*/
public function setOptions($options) {
$this->options = $options;
}
/**
* Does a CRUD delete operation
* $doNotAsk toggels the "do you really want to delete?" question, wich requires a delete.phtml
*
* @param boolean $doNotAsk toggle "do you really want to delete?" question
*
* @return \Zend\View\Model\ViewModel
*/
public function deleteEntity($doNotAsk = false) {
$controller = $this->getController();
......@@ -91,6 +183,12 @@ class Crud extends AbstractPlugin {
return $this->redirect();
}
/**
* Does a CRUD edit operation
* Returns ViewModel for the edit.phtml with form populated with entity data to
*
* @return \Zend\View\Model\ViewModel
*/
public function editEntity() {
$controller = $this->getController();
$this->setId($controller->getRequest()->getQuery($this->options[self::ID_COLUMN], false));
......@@ -112,6 +210,12 @@ class Crud extends AbstractPlugin {
return $viewModel;
}
/**
* Does a CRUD save operation
* Returns ViewModel for the edit.phtml in case of invalid data or redirect
*
* @return \Zend\View\Model\ViewModel
*/
public function saveEntity() {
$controller = $this->getController();
$form = $this->options[self::FORM];
......@@ -163,6 +267,12 @@ class Crud extends AbstractPlugin {
}
}
/**
* send redirect or JSON structure for a redirect via Javascript AjaxForm.js
*
* @param type $sendJson
* @return \Zend\Http\Response
*/
protected function redirect($sendJson = false) {
$controller = $this->getController();
$path = 'index';
......@@ -183,6 +293,11 @@ class Crud extends AbstractPlugin {
$controller->redirectTo($path, $params, $route);
}
/**
* Parses $_POST and $_FILES and creates a structure for the processing in saveEntity
*
* @return array
*/
protected function parseParams() {
$controller = $this->getController();
$data = array();
......@@ -220,6 +335,13 @@ class Crud extends AbstractPlugin {
return $data;
}
/**
* transforms route params for use in ViewModel
*
* @param array $params
*
* @return array
*/
protected function getParams($params) {
if (is_array($this->options[self::ROUTE])) {
foreach ($this->options[self::ROUTE][1] as $name => $value) {
......@@ -230,6 +352,14 @@ class Crud extends AbstractPlugin {
return $params;
}
/**
* replaces replacements in message string if defined with entity data and returns the message string
*
* @param int $messageKey
* @param object $entity
*
* @return string
*/
protected function parseMessage($messageKey, $entity) {
if (isset($this->options[self::REPLACEMENTS]) && is_array($this->options[self::REPLACEMENTS])) {
$replacements = array();
......@@ -243,6 +373,13 @@ class Crud extends AbstractPlugin {
return $this->options[self::MESSAGES][$messageKey];
}
/**
* getter
*
* @param id $id default false
*
* @return object
*/
public function getEntity($id = false) {
if (null == $this->entity) {
$controller = $this->getController();
......@@ -255,18 +392,38 @@ class Crud extends AbstractPlugin {
return $this->entity;
}
/**
* getter
*
* @return Zend\Form\Form
*/
public function getForm() {
return $this->options[self::FORM];
}
/**
* getter
*
* @return int
*/
public function getId() {
return $this->id;
}
/**
* setter
*
* @param int $id
*/
public function setId($id) {
$this->id = $id;
}
/**
* getter
*
* @return \Administration\CrudPersistor\PersistorInterface
*/
public function getPersistor() {
if (!isset($this->options[self::PERSISTOR])) {
$this->options[self::PERSISTOR] = 'Administration\CrudPersistor\Entity';
......@@ -282,5 +439,4 @@ class Crud extends AbstractPlugin {
return $persistor;
}
}
......@@ -27,21 +27,78 @@ use Zend\Mvc\Controller\Plugin\AbstractPlugin;
use Zend\Session\Container;
use Zend\View\Model\ViewModel;
/**
* Controller plugin for Pagination, Filter and Sorting
*
* @package Administration_Controller_Plugin
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) 2015 Dirk Benkert
*/
class PaginationFilterSort extends AbstractPlugin {
/**
* option key sessionNamespace
*/
const SESSION_NAMESPACE = 'sessionNamespace';
/**
* option key for the entity
*/
const ENTITY = 'entity';
/**
* option key for the paginator
*/
const PAGINATOR = 'paginator';
/**
* option key for the filter
*/
const FILTER = 'filter';
/**
* option key for the identity
*/
const IDENTITY = 'identity';
/**
* option key for the query parameter
*/
const PARAMS = 'params';
/**
* Data array
*
* @var array
*/
protected $data = array();
/**
* Options array
*
* @var array
*/
protected $options = array();
/**
* session container
*
* @var Zend\Session\Container
*/
protected $session = null;
protected $repository = null;
/**
* Repostory
*
* @var Application\Repository\PaginationFilterSortAwareInterface
*/
protected $repository = null;
/**
* setter
*
* @param array $options
*/
public function setOptions($options) {
$this->options = $options;
......@@ -69,6 +126,9 @@ class PaginationFilterSort extends AbstractPlugin {
));
}
/**
* parses the query params ($_GET) and fills $this->data with pagination and filter information
*/
protected function parseParams() {
$controller = $this->getController();
......@@ -87,6 +147,12 @@ class PaginationFilterSort extends AbstractPlugin {
}
}
/**
*
* @param array $params
*
* @return Administration\Paginator\Paginator
*/
public function getPaginator($params = array()) {
$repository = $this->getRepository();
$repository->setParams(array_merge($params, $this->data));
......@@ -105,12 +171,22 @@ class PaginationFilterSort extends AbstractPlugin {
return $paginator;
}
/**
* return filter defined in repository class
*
* @return array
*/
public function getFilter() {
$repository = $this->getRepository();
return $repository->getFilter();
}
/**
* getter
*
* @return Application\Repository\PaginationFilterSortAwareInterface
*/
public function getRepository() {
if (null === $this->repository) {
$controller = $this->getController();
......
......@@ -42,8 +42,20 @@ use Application\Entity\User;
use Administration\Form\UserForm;
use Zend\Stdlib\Parameters;
/**
* Controller for user administration
*
* @package Administration_Controller
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) 2015 Dirk Benkert
*/
class UserController extends ControllerAbstract {
/**
* CRUD Messages
*
* @var array
*/
protected $message = array(
//'%s (%s) added.', // success message on $editMode = false
//'%s (%s) saved.', // success message on $editMode = true
......@@ -54,7 +66,7 @@ class UserController extends ControllerAbstract {
);
/**
* lists users for administrative purposes
* list users for administrative purposes
*
* @return \Zend\View\Model\ViewModel
*/
......@@ -67,6 +79,7 @@ class UserController extends ControllerAbstract {
return $plugin->getViewModel();
}
/**
* form action for a new user or to modify an existing one
*
......@@ -106,8 +119,12 @@ class UserController extends ControllerAbstract {
return $plugin->saveEntity();
}
protected function getCrudOptions() {
/**
* defines options for CRUD plugin
*
* @return array
*/
protected function getCrudOptions() {
$id = $this->getRequest()->getQuery('id', false);
// editMode in constructor is required to disable form field username
......
......@@ -22,33 +22,78 @@
*/
namespace Administration\CrudPersistor;
/**
* Abstract persistor class
* Persistor classes are used by the CRUD plugin for persisting objects
*
* @package Administration_CrudPersistor
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) 2015 Dirk Benkert
*/
abstract class AbstractPersistor implements PersistorInterface {
/**
* option key child entities
*/
const CHILD_ENTITIES = 'childEntities';
/**
* class calling the persistor, typically Administration\Controller\Plugin\Crud
*
* @var Administration\Controller\Plugin\Crud
*/
protected $service = null;
/**
* Options
*
* @var array
*/
protected $options = array();
/**
* The constructor
*
* @param array $options default array()
*
* @return void
*/
public function __construct($options = array()) {
$this->setOptions($options);
}
/**
* getter
*
* @return Administration\Controller\Plugin\Crud
*/
public function getService() {
return $this->service;
}
/**
* setter
*
* @param Administration\Controller\Plugin\Crud $service
*/
public function setService($service) {
$this->service = $service;
}
/**
* setter
*
* @param array $options
*/
public function setOptions($options) {
$this->options = $options;
}
/**
* resolves child entities in the data array for many-to-many, one-to-many and one-to-one relations
*
* @param array $$data
*/
protected function resolveChildEntities(&$data) {
if (isset($this->options[self::CHILD_ENTITIES]) && is_array($this->options[self::CHILD_ENTITIES])) {
$controller = $this->getService()->getController();
......
......@@ -21,21 +21,22 @@
* limitations under the License.
*/
namespace Administration\CrudPersistor;
/**
* File description
* Persistor implementation for persisting Doctrine entities
*
* @category CATEGORY
* @package PACKAGE
* @subpackage SUBPACKAGE
* @copyright Copyright (c) 2012 Dirk Benkert
* @author Dirk Benkert <benkert.dirk@gmail.com>
* @license Dirk Benkert standard license terms and conditions 1.0
* @package Administration_CrudPersistor
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) 2015 Dirk Benkert
*/
namespace Administration\CrudPersistor;
class Entity extends AbstractPersistor {
/**
* persist $entity with $data
*
* @param object $entity
* @param array $data
*/
public function persist($entity, $data) {
$controller = $this->getService()->getController();
$entity->setService($controller);
......@@ -47,6 +48,11 @@ class Entity extends AbstractPersistor {
$controller->getEntityManager()->flush();
}
/**
* remove an $entity
*
* @param object $entity
*/
public function remove($entity) {
$controller = $this->getService()->getController();
......
......@@ -22,13 +22,41 @@
*/
namespace Administration\CrudPersistor;
/**
* Abstract persistor class
* Persistor classes are used by the CRUD plugin for persisting objects
*
* @package Administration_CrudPersistor
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) 2015 Dirk Benkert
*/
interface PersistorInterface {
/**
* persist $entity with $data
*
* @param object $entity
* @param array $data
*/
public function persist($entity, $data);
/**
* remove an $entity
*
* @param object $entity
*/
public function remove($entity);
/**
* setter
*
* @param Administration\Controller\Plugin\Crud
*/
public function setService($service);
/**
* getter
*
* @return Administration\Controller\Plugin\Crud
*/
public function getService();
}
......@@ -21,15 +21,6 @@
* limitations under the License.
*/
/**
* Description for UserForm
*
* @package Administration_Form
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) Dirk Benkert
* @version 1.0
*/
namespace Administration\Form;
use Zend\Form\Form;
......@@ -42,6 +33,13 @@ use Zend\ServiceManager\ServiceLocatorInterface;
use Doctrine\ORM\EntityManager;
use Application\Util\Text;
/**
* Abstract form class
*
* @package Administration_Form
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) 2015 Dirk Benkert
*/
abstract class AbstractForm extends Form implements ServiceLocatorAwareInterface {
/**
* ServiceManager
......@@ -64,6 +62,11 @@ abstract class AbstractForm extends Form implements ServiceLocatorAwareInterface
*/
protected $entityManager = null;
/**
* the constructor
*
* @param string $name
*/
public function __construct($name = '') {
parent::__construct('');
}
......
......@@ -40,6 +40,13 @@ use Zend\Validator\Regex;
use Zend\Validator\Identical;
use Zend\Validator\InArray;
/**
* For for creating and editing user entities
*
* @package Administration_Form
* @author Dirk Benkert <mail@dirk-benkert.de>
* @copyright Copyright (c) 2015 Dirk Benkert
*/
class UserForm extends AbstractForm {
/**
......@@ -52,7 +59,6 @@ class UserForm extends AbstractForm {
/**
* the constructor
*
* @param array $storages
* @param boolean $editMode
*/
public function __construct($editMode = false) {
......
......@@ -24,23 +24,61 @@ namespace Administration\Paginator;
use Zend\Paginator\Paginator as ZendPaginator;