Defining Annotations

Annotations extends the phpdoc syntax to provide metadata information to Controllers or ViewModels. In both the ViewModel Binding example and the Annotated ViewModel Binding example we see how annotations are used to extend the functionality of the individual use cases.

Below the ExampleController has been shortened for the purposes of this example.

<?php
    class ExampleController extends FrontController
    {
        /**
         * URL: Example/viewModelBindingAction/
         * Alias: view-model-binding-example/
         *
         * @annotation DependenciesLocations(People)
         * @annotation DependencyInjection(PersonService, PersonViewModel)
         *
         * @return View
         */
        public function viewModelBindingAction()
        {
            $this->createExampleDisplayTemplate("ViewModel Binding Example", "_viewModelBinding");

            $this->view->content = "Hello World from the <b>ExampleController viewModelBindingAction</b> action";

            return $this->viewModel(PeopleService::get());
        }
    } /*end of class ExampleController*/

From the snippet above the * @annotation DependenciesLocations(People) and * @annotation DependencyInjection(PersonService, PersonViewModel) lines tells a mechanism in the background that within the application/Models/People and application/ViewModels/People folders to make available the PersonService.class.php and PersonViewModel.class.php files to the current controller action.

It is possible to create custom annotations, for controller actions, that will respond to custom built functionality but for purposes of this framework's demonstrations, those will be discussed at a later date.

The framework supports the MVVM approach to organizing a project. The default location for view models files is application/ViewModels/ which is similar to "normal" models but offer the flexiblity of not having to be organized into a folder structure that resembles the names of controllers.

Below the PersonViewModel has been shortened for the purposes of this example.

<?php
    class Person
    {
        /**
         * @annotation Id(FirstName)
         * @annotation Display(First Name)
         *
         * @var string
         */
        public $firstName;

        /**
         * @annotation Id(LastName)
         * @annotation Display(Last Name)
         *
         * @var string
         */
        public $lastName;

        /**
         * @annotation Id(EmailAddress)
         * @annotation Display(Email Address)
         * @annotation Type(email)
         *
         * @var string
         */
        public $emailAddress;
    } /*end of class Person*/

The above extract is used to do view model binding in the Annotated ViewModel Binding example. The phpdoc contain @ annotation definitions that are then interpreted by a view template by binding to custom tag helpers or simple php output.

Two Things To Remember

The return $this->viewModel() method creates two special variables, one called $this->view->viewModel; which contain annotation information (if any), and another called $this->view->boundModel; which contains the actual data stored by the view model.