Immediate remove cookie data in zend-mvc application

In zend-mvc application, we can utilize Zend\Http\Header\SetCookie header to set cookie to be added to response header. For example, we have a setAction() to set it, we can do:

use Zend\Http\Header\SetCookie;
// ...
    public function setAction()
    {
        $request  = $this->getRequest();
        $response = $this->getResponse();

        $response->getHeaders()->addHeader(new SetCookie(
            // name
            'test',

            // value
            'abc',
            
            // expires
            \time() + (60 * 60 * 24 * 365),
            
            // path
            '/',
            
            // domain
            null,
            
            // secure
            $request->getUri()->getScheme() === 'https',
            
            // httponly
            true
        ));

        return $response;
    }
// ...

Above, we set cookie with name “test” with value “abc”, with expires 1 year. To remove it completely before 1 year hit, we can pass 8th parameter as maxAge to be 0, so, for example, we have a removeAction to remove it, we can do:

use Zend\Http\Header\SetCookie;
// ...
    public function removeAction()
    {
        $request  = $this->getRequest();
        $response = $this->getResponse();

        $cookie   = $request->getCookie();
        if (! isset($cookie['test'])) {
            // already removed, return response early
            return $response;
        }

        $response->getHeaders()->addHeader(new SetCookie(
            'test',
            null, // no need to set value
            null, // no need to set expires
            '/',
            null,
            $request->getUri()->getScheme() === 'https',
            true,
            0    // set maxAge to 0 make "test" cookie gone
        ));

        return $response;
    }
// ...

That’s it!

ErrorHeroModule : a Hero for Your Zend Mvc and Expressive Application

After > 1 year work with 52 releases, I think it is time to show off. Even you have 100% test coverage, error may can still happen, that’s why ErrorHeroModule was born. ErrorHeroModule is a Hero for your Zend Mvc, and zend-expressive application to trap php errors and exception with configureable options.

The logging storage is mainly a database, then can continue “log” to your email when you want it.

Features

1. Save to DB with Db Writer Adapter

We can choose using Zend\Db or Doctrine via DoctrineORMModule. The error log is recorded like below:

2. Log Exception (dispatch.error and render.error) and PHP Errors in all events process

This handle all Exceptions and Errors with support PHP 7 Error during MVC process or middleware flow.

3. Support excludes PHP E_* Error (eg: exclude E_USER_DEPRECATED) in config settings

This can be used when you have a functionality which has collection of E_* errors, and you need to keep the functionality to run.

4. Support excludes PHP Exception (eg: Exception class or classes that extends it) in config settings

This can be used when you have exceptions that you want to have special treatment.

5. Handle only once log error for same error per configured time range

This can be used when on some environment, eg: in production, we don’t want to get same error repeatly reported in some periodic time while we are fixing it.

6. Set default page (web access) or default message (console access) for error if configured ‘display_errors’ = 0

This can be used to set a “nice” page on web environment:

or content on console access:

7. Set default content when request is XMLHttpRequest via ‘ajax’ configuration

This can be used to set a default content when request is an XMLHttpRequest.

8. Provide request information ( http method, raw data, query data, files data, and cookie data )

This can be used to help reproduce the error.

9. Send Mail

This has options:
– many receivers to listed configured email
– with include $_FILES into attachments on upload error.

This can be used to help reproduce the error, with include uploaded data when error happen when we just submitted a form with upload process.

Support

This module support zend-mvc:^2.5 and zend-expressive:^1.1|^2.0 with php version ^5.6|^7.0. My plan is to drop php ^5.6 in version 2.

Limitations

There are some limitations right now and I want it to be implemented in next releases:

General functionality:

• Allow custom formatter when log to email, currently, it send Json format to email.

Current Json Formatter is really stable with the following format sample data:

{
    "timestamp": "2017-12-20T15:23:00+07:00",
    "priority": 3,
    "priorityName": "ERR",
    "message": "a sample error preview",
    "extra": {
        "url": "http://app.dev/error-preview",
        "file": "/var/www/app/vendor/samsonasik/error-hero-module/src/Controller/ErrorPreviewController.php",
        "line": 11,
        "error_type": "Exception",
        "trace": "#0 /var/www/app/vendor/zendframework/zend-mvc/src/Controller/AbstractActionController.php(78): ErrorHeroModule\\Controller\\ErrorPreviewController->exceptionAction()
#1 /var/www/app/vendor/zendframework/zend-eventmanager/src/EventManager.php(322): Zend\\Mvc\\Controller\\AbstractActionController->onDispatch(Object(Zend\\Mvc\\MvcEvent))
#2 /var/www/app/vendor/zendframework/zend-eventmanager/src/EventManager.php(179): Zend\\EventManager\\EventManager->triggerListeners(Object(Zend\\Mvc\\MvcEvent), Object(Closure))
#3 /var/www/app/vendor/zendframework/zend-mvc/src/Controller/AbstractController.php(106): Zend\\EventManager\\EventManager->triggerEventUntil(Object(Closure), Object(Zend\\Mvc\\MvcEvent))
#4 /var/www/app/vendor/zendframework/zend-mvc/src/DispatchListener.php(138): Zend\\Mvc\\Controller\\AbstractController->dispatch(Object(Zend\\Http\\PhpEnvironment\\Request), Object(Zend\\Http\\PhpEnvironment\\Response))
#5 /var/www/app/vendor/zendframework/zend-eventmanager/src/EventManager.php(322): Zend\\Mvc\\DispatchListener->onDispatch(Object(Zend\\Mvc\\MvcEvent))
#6 /var/www/app/vendor/zendframework/zend-eventmanager/src/EventManager.php(179): Zend\\EventManager\\EventManager->triggerListeners(Object(Zend\\Mvc\\MvcEvent), Object(Closure))
#7 /var/www/app/vendor/zendframework/zend-mvc/src/Application.php(332): Zend\\EventManager\\EventManager->triggerEventUntil(Object(Closure), Object(Zend\\Mvc\\MvcEvent))
#8 /var/www/app/public/index.php(53): Zend\\Mvc\\Application->run()
#9 {main}",
        "request_data": {
            "query": [],
            "request_method": "GET",
            "body_data": [],
            "raw_data": "",
            "files_data": [],
            "cookie_data": {
                "ZS6SESSID": "pbihc9ts004oq4b5alg4tg91b6",
                "PHPSESSID": "bkd7jaj22z936vstc9l0xuc9sr2dqp4g",
            }
        }
    }
}

The drawback with allow custom formatter is you maintain/keep an eye yourself for the formatter you provide!

Zend Mvc application:

• Trap exception and error when they happen at Module::init().

Zend Expressive application:

• Make support for non zend-servicemanager for container. (support zend-servicemanager, symfony, aura, auryn, and pimple for zend-expressive application at version 2.9.0)
• Make support for non zend-view for custom page template engine when error happen. (supported at version 2.1.0)

That’s it for now. If you see something can be improved, please contribute! Thank you for all users that using it.

Apigility: Using zf-oauth2’s refresh_token_lifetime to create client’s remember me functionality

If you’re building client based application which require oauth authentication to apigility application which uses time based expire access token, you may want to create a remember me functionality in client.

PHP Configuration

The very first required is set the client and the server side has same timezone, eg:

# your php.ini
date.timezone = "Asia/Jakarta"

This is ensure that you have actually same time for both client and api server.

DB data requirements

If you already setup the Oauth2 DB, you need to insert/update the client to support “password” and “refresh_token”, that use both means use space-separated value eg:

INSERT INTO `oauth_clients` (`client_id`, `client_secret`, `redirect_uri`, `grant_types`, `scope`, `user_id`) VALUES
(
    'test',
    '$2y$10$vbuy12RNSTJ.LHDdivegwu9dqkxh8h6OS4VoIX64HQGngAqUfcSJe',
    '/oauth/receivecode',
    'password refresh_token',
    NULL,
    NULL
);

Above sql insert data to oauth_clients table with client_id valued “test” with bcrypted client_secret “test”.

You can also insert a users data, for example:

INSERT INTO `oauth_users` (`username`, `password`) VALUES
(
    'test',
    '$2y$10$vbuy12RNSTJ.LHDdivegwu9dqkxh8h6OS4VoIX64HQGngAqUfcSJe'
),

Above sql insert data to oauth_users table with username valued “test” with bcrypted password “test”.

ZF-Oauth2 configuration

In apigility side, we can configure the “zf-oauth2” config, for example, as follows:

// config/autoload/global.php
return [
    // ...
    'zf-oauth2' => [
        'access_lifetime' => 1800,
        'options' => [
            'refresh_token_lifetime' => 604800,
            'always_issue_new_refresh_token' => true,
        ],
    ],
];

The configuration above means we can have an access token lifetime in 1800 seconds, and we can re-issue the new token lifetime with existing “refresh_token” as far as the time range is not > 604800 seconds ( 1 week ). For example, we authenticate with data:

{
    "grant_type": "password",
    "username": "test",
    "password": "test",
    "client_id": "test",
    "client_secret" : "test"
}

have authenticated tokens data like the following:

{
  "access_token": "8e4b0e5ddc874a6f1500514ef530dbea3976ae77",
  "expires_in": 1800,
  "token_type": "Bearer",
  "scope": null,
  "refresh_token": "d19b79cd376924409c14ee46e5230617482fb169"
}

The “refresh_token” is the key here.

The client application

I assume you’re using Zend Framework 2/3 application for client side, which we can use Zend\Authentication\AuthenticationService service. We can build custom Auth storage for it, eg:

namespace Application\Storage;

use Zend\Authentication\Storage;

class AuthStorage extends Storage\Session
{
    public function __construct()
    {
        parent::__construct('app_client');

        $sessionConfigOptions = [
            'use_cookies'     => true,
            'cookie_httponly' => true,
            'gc_maxlifetime'  => 1800,
            'cookie_lifetime' => 1800,
        ];
        $this->getSessionManager()->getConfig()
                                  ->setOptions($sessionConfigOptions);
    }

    public function rememberMe($time)
    {
        $this->getSessionManager()->rememberMe($time);
    }

    public function clear()
    {
        $this->getSessionManager()->forgetMe();
        parent::clear();
    }

    public function getSessionManager()
    {
        return $this->session->getManager();
    }
}

You can now create factory to build the AuthenticationService service with the authstorage like I blog posted at Create ZF Client Authentication for Apigility Oauth with ApigilityConsumer post.

On authentication part, eg: AuthenticationController, you can do:

$result = $this->authenticationService->authenticate();

if ($result->isValid()) {
    $storage = $this->authenticationService->getStorage();

    // save next "expires" time to session
    $storage->write(
        $storage->read() +
        [
            // it is better to use
            // api service to get the `oauth_access_tokens` real expires
            'expires' => date('Y-m-d H:i:s', time() + $read['expires_in'])
        ]
    );

    // for example, you have "rememberme" checkbox
    if (($rememberme = $request->getPost('rememberme')) == 1 ) {

        $storage->rememberMe(604800);

        $read = $storage->read();
        $storage->write(
            compact('rememberme') +
            $read +
            [
                // it is better to use
                // api service to get the `oauth_refresh_tokens` real expires
                'refreshExpires' => date('Y-m-d H:i:s', time() + 604800)
            ]
        );
    }
    // ...
}

We are going to use “expires” as immediate check session lifetime hit the expires, and “refreshExpires” to check when it stil be able to re-issue new token.

In bootstrap, for example, in Application\Module::onBootstrap() you can verify it to re-issue the token when access lifetime has hit.

namespace Application;

use Zend\Authentication\AuthenticationService;
use Zend\Mvc\MvcEvent;

class Module
{
    // ...
    public function onBootstrap(MvcEvent $e)
    {
        $services = $e->getApplication()->getServiceManager();
        $storage  = $services->get(AuthenticationService::class)->getStorage();
        $read     = $storage->read();

        if (isset($read['access_token'])) {

            $timeFirst   = strtotime($read['expires']);
            $currentTime = date('Y-m-d H:i:s');
            $timeSecond  = strtotime($currentTime);
            $counter     = $timeFirst - $timeSecond;

            if (! empty($rememberme = $read['rememberme'])) {

                $storage->getSessionManager()
                        ->getConfig()
                        ->setStorageOption('gc_maxlifetime', 604800)
                        ->setStorageOption('cookie_lifetime', 604800);
                
                if ($counter < 0 && $currentTime < $read['refreshExpires']) {

                    // API CALL to apigility oauth uri
                    // with grant_types = "refresh_token" and uses
                    // refresh_token as the key to re-issue new token
                    //
                    //    {
                    //        "grant_type"    : "refresh_token",
                    //        "refresh_token" : $read['refresh_token']
                    //        "client_id"     : "test",
                    //        "client_secret" : "test"
                    //    }
                    //
                    $storage->write(
                        [
                            // it is better to use
                            // api service to get the `oauth_access_tokens` real expires
                            'expires' => date('Y-m-d H:i:s', time() + $read['expires_in']),

                            // api service to get the `oauth_refresh_tokens` real expires
                            'refreshExpires' => date('Y-m-d H:i:s', time() + 604800),
                        ] +
                        compact('rememberme') +
                        [
                            "access_token": "<new access token based on oauth call>",
                            "expires_in": <new expire_in based on oauth call>,
                            "token_type": "<new token_type based on oauth call>",
                            "refresh_token": "<new refresh_token token based on oauth call>"
                        ] +
                        $read
                    );

                    $read = $storage->read();
                }
            }

            if ($currentTime > $read['expires'])) {
                // force clean up session
                $storage->clear();
            }

        }

    }
    // ...
}

Note

As commented in the codes sample above, in your real life application, it is beter to use real token expires instead of adding current time with expire_in time or manual fill refresh token lifetime. Do more automation yourself!

If you use Zend Framework 2/3 or Zend Expressive, you can try ApigilityConsumer for client module to consume api services. Enjoy 😉

Auto add _links property of HAL Resources into all api service in Apigility

If you want to have the _links property value to HAL Resource in apigility api service, for example:

{
    "id": 1,
    "name": "Abdul Malik Ikhsan",
    
    "_links": {
        "self": {
            "href": "http://api.dev/user/1"
        }
    }
}

you can do manually in every api service:

use ZF\ContentNegotiation\ViewModel;
use ZF\Hal\Entity as HalEntity;
use ZF\Hal\Link\Link;

// ...

    public function userAction()
    {
        $halEntity = new HalEntity([
             'id' => 1,
             'name' => 'Abdul Malik Ikhsan',   
        ]);

        $link = $halEntity->getLinks();
        $link->add(Link::factory(
              [
                  'rel' => 'self',
                  'url' => $this->getRequest()->getUriString(),
              ]
        ));

        return new ViewModel([
            'payload' => $halEntity,
        ]);
    }

// ...

You can eliminate that by apply via EventManager’s Shared Manager which attach to Zend\Mvc\Controller\AbstractActionController on dispatch event, like below:

namespace Application;

use Zend\Mvc\Controller\AbstractActionController;
use Zend\Mvc\MvcEvent;
use ZF\Hal\Link\Link;
use ZF\Hal\Plugin\Hal;

class Module
{
    public function onBootstrap(MvcEvent $e)
    {
        $app       = $e->getApplication();
        $sharedEvm = $app->getEventManager()->getSharedManager();

        $sharedEvm->attach(AbstractActionController::class, 'dispatch',
            function($event) use ($sharedEvm) {

                $uri = $event->getRequest()->getUriString();

                $sharedEvm->attach(Hal::class, 'renderEntity', function($event) use ($uri) {
                    $event->getParam('entity')
                          ->getLinks()
                          ->add(Link::factory(
                                [
                                    'rel' => 'self',
                                    'url' => $uri,
                                ]
                            ));
                });

            },
            100
        );

    }

    public function getConfig() { /* */ }
}

On above code, we attach ZF\Hal\Plugin\Hal on renderEntity event which get the ZF\Hal\Entity object from ZF\ContentNegotiation\ViewModel payload property, and apply Link into it via ZF\Hal\Link\Link::factory().

Now, you can eliminate unneeded repetitive codes in all every api services.

Done 😉

Using Direct ArrayObject instance as ObjectPrototype in Zend\Db

When creating a table model for ZF2 or ZF3 application with Zend\DB, direct ArrayObject instance can be usefull as ResultSet object prototype. We can no longer need to create an individual class that has getArrayCopy() or exchangeArray() for data transformation.

For example, we have the following table model:

<?php
namespace Application\Model;

use Zend\Db\TableGateway\AbstractTableGateway;

class CountryTable
{
    public static $table = 'country';
    private $tableGateway;

    public function __construct(AbstractTableGateway $tableGateway)
    {
        $this->tableGateway = $tableGateway;
    }

    public function getCountriesInAsia()
    {
        $select  = $this->tableGateway->getSql()->select();
        $select->where([
            'continent' => 'ASIA'
        ]);

        return $this->tableGateway->selectWith($select);
    }
}

The ArrayObject usage we can use is:

new ArrayObject([], ArrayObject::ARRAY_AS_PROPS);

So, we can build the factory for above table model as follows:

<?php
namespace Application\Model;

use ArrayObject;
use Interop\Container\ContainerInterface;
use Zend\ServiceManager\Factory\FactoryInterface;
use Zend\Db\ResultSet\HydratingResultSet;
use Zend\Db\TableGateway\TableGateway;

class CountryTableFactory implements FactoryInterface
{
    public function __invoke(ContainerInterface $container, $requestedName, array $options = null)
    {
        $resultSetPrototype = new HydratingResultSet();
        $resultSetPrototype->setObjectPrototype(
             new ArrayObject([], ArrayObject::ARRAY_AS_PROPS)
        );
        
        $tableGateway =  new TableGateway(
            CountryTable::$table,
            $container->get('Zend\Db\Adapter\Adapter'),
            null,
            $resultSetPrototype
        );

        return new CountryTable($tableGateway);
    }
}

and register it into service_manager under factories:

<?php
namespace Application;

return [
    // ...
    'service_manager' => [
        'factories' => [
            Model\CountryTable::class => Model\CountryTableFactory:class,
        ],
    ],
];

When retrieving the data, you can do the followings:

use Application\Model\CountryTable;

$countryTable    = $container->get(CountryTable::class);
$countriesInAsia = $countryTable->getCountriesInAsia();

foreach ($countriesInAsia as $key => $row) {

    // dump a copy of the ArrayObject
    var_dump($arrayCopy = $row->getArrayCopy());

    // echoed column as property
    echo $row->name; // with value "INA"
    echo $row->iso;  // with value "ID"
    echo $row->continent; // with value "ASIA"

    // echoed as array with provided key
    echo $row['name']; // with value "INA"
    echo $row['iso'];  // with value "ID"
    echo $row['continent']; // with value "ASIA"

    // modify data via exhangeArray
    $row->exchangeArray(array_merge(
		$arrayCopy,
		[
			'name' => 'INDONESIA',
		]
	));

    // or modify its data by its property
    $row->name = 'INDONESIA';
    // or modify its data by its index array
    $row['name'] = 'INDONESIA';

    echo $row->name; // now has value "INDONESIA"
    echo $row['name']; // now has value "INDONESIA"
}

Bonus:

To avoid repetitive creating factory class for each table model, we can create an abstract factory for it:

<?php

namespace Application\Model;

use ArrayObject;
use Interop\Container\ContainerInterface;
use Zend\Db\ResultSet\HydratingResultSet;
use Zend\Db\TableGateway\TableGateway;
use Zend\ServiceManager\Factory\AbstractFactoryInterface;

class CommonModelTableFactory implements AbstractFactoryInterface
{
    public function canCreate(ContainerInterface $container, $requestedName)
    {
        return ((substr($requestedName, -5) === 'Table') && class_exists($requestedName));
    }

    public function __invoke(ContainerInterface $container, $requestedName, array $options = null)
    {
        $tableModel = '\\' . $requestedName;

        $resultSetPrototype = new HydratingResultSet();
        $resultSetPrototype->setObjectPrototype(
            new ArrayObject([], ArrayObject::ARRAY_AS_PROPS)
        );

        $tableGateway =  new TableGateway(
            $tableModel::$table,
            $container->get('Zend\Db\Adapter\Adapter'),
            null,
            $resultSetPrototype
        );

        return new $tableModel($tableGateway);
    }
}

So, now, we can have 1 abstract factory for all table model services:

<?php
namespace Application;

return [
    // ...
    'service_manager' => [
        'abstract_factories' => [
            Model\CommonModelTableFactory:class,
        ],
    ],
];

That’s it 😉

Create ZF Client Authentication for Apigility Oauth with ApigilityConsumer

If you have Apigility as API builder in API side, and client app that consume it using Zend Framework 2/3 or ZF Expressive, you can create an authentication from the client application that call oauth in apigility side.

Zend\Authentication has AbstractAdapter that you can extends to create custom adapter for its need. Let’s assume the applications are like the following diagram:

[CLIENT - A ZF Application]              [API - An Apigility Application]
         |                                          |
   AuthController                     ZF\MvcAuth\Authentication\OAuth2Adapter          
         |                                          |
         |       authenticateAction()               |
         |   ------------------------------------>  |
         |         identity json                    |
         |   <------------------------------------  |

On oauth result call, you may get the following result:

{
  "access_token": "8e4b0e5ddc874a6f1500514ef530dbea3976ae77",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": null,
  "refresh_token": "d19b79cd376924409c14ee46e5230617482fb169"
}

The ApigilityConsumer

ApigilityConsumer is a ZF2/ZF3 Apigility Client module (can also be used in ZF Expressive) to consume Apigility API Services.

You can install by run composer command:

composer require samsonasik/apigility-consumer

For full configurations and features, you can read at its README, for this post’s need, you can do something like this:

<?php
// config/autoload/apigility-consumer.local.php
return [
    'apigility-consumer' => [
        // your apigility host url
        'api-host-url' => 'https://your.apigilty.api.host',

        // your apigility oauth setting
        'oauth' => [

            'grant_type'    => 'password',
            'client_id'     => 'your client id',
            'client_secret' => 'your client secret',

        ],

    ],
];

and register the module into config/application.config.php or config/modules.config.php:

<?php
// config/application.config.php or config/modules.config.php
return [
    'ApigilityConsumer', // <-- register here
    'Application',
],

Create Adapter

You need to extends Zend\Authentication\Adapter\AbstractAdapter and implements Zend\Authentication\Adapter\AdapterInterface. So, You can have the class:

<?php

namespace Application\Adapter;

use ApigilityConsumer\Service\ClientAuthService;
use Zend\Authentication\Adapter\AbstractAdapter;
use Zend\Authentication\Adapter\AdapterInterface;
use Zend\Authentication\Result;

class ApigilityAuthenticationAdapter
    extends AbstractAdapter
    implements AdapterInterface
{
    /**
     * @var ClientAuthService
     */
    private $clientAuthService;

    /**
     * @param  ClientAuthService $clientAuthService
     */
    public function __construct(ClientAuthService $clientAuthService)
    {
        $this->clientAuthService = $clientAuthService;
    }

    /**
     * @return Result
     */
    public function authenticate()
    {
        $clientResult = $this->clientAuthService->callAPI(
            [
                // your oauth registered route segment in apigility. 
                'api-route-segment' => '/oauth', 

                'form-data' => [
                    'username' => $this->getIdentity(),
                    'password' => $this->getCredential(),
                ],

                'form-request-method' => 'POST',
            ]
        );

        if (! $clientResult->success) {
            return new Result(Result::FAILURE, null, $clientResult::$messages);
        }

        return new Result(RESULT::SUCCESS, $clientResult->data);
    }
}

Your can now build a factory from it:

<?php
namespace Application\Adapter;

use ApigilityConsumer\Service\ClientAuthService;

class ApigilityAuthenticationAdapterFactory
{
    public function __invoke($container)
    {
        return new ApigilityAuthenticationAdapter(
            $container->get(ClientAuthService::class)
        );
    }
}

You can then register at service_manager:

<?php
// module/Application/config/module.config.php
namespace Application;

'service_manager' => [
    'factories' => [
        // ...
        Adapter\ApigilityAuthenticationAdapter::class => Adapter\ApigilityAuthenticationAdapterFactory::class,
    ],
],

For ZF Expressive, you can register under ‘dependencies’ key.

Set Adapter into AuthenticationService

You need to set authentication service’s adapter with defined adapter above with factory:

<?php
namespace Application\Factory;

use Application\Adapter\ApigilityAuthenticationAdapter;
use Zend\Authentication\AuthenticationService;
use Zend\Authentication\Storage\Session;

class AuthenticationServiceFactory
{
    public function __invoke($container)
    {
        $adapter = $container->get(ApigilityAuthenticationAdapter::class);

        return new AuthenticationService(
            new Session(), // or your own storage implementing  Zend\Authentication\Storage\StorageInterface
            $adapter
        );
    }
}

You can then register also at service_manager:

<?php
// module/Application/config/module.config.php
namespace Application;

use Zend\Authentication\AuthenticationService;

'service_manager' => [
    'factories' => [
        // ...
        AuthenticationService::class => Factory\AuthenticationServiceFactory::class,
    ],
],

For ZF Expressive, you can register under ‘dependencies’ key.

The AuthController::authenticate()

I assume that you already inject controler with login form, use “username” and “password” as field names, and fill the data, so, your AuthController::authenticate() can be like the following:

<?php
namespace Application\Controller;

use Application\Form\LoginForm;
use Zend\Authentication\AuthenticationService;

class AuthController
{
    public function __construct(
        AuthenticationService $authenticationService,
        LoginForm $loginForm,
    ) { /* ...*/ }

    public function authenticateAction()
    {
        /*
         *    check request and form validity here
         */
        $formData = $this->loginForm->getData();
        $this->authenticationService->getAdapter()
                                    ->setIdentity($formData['username'])
                                    ->setCredential($formData['password']);

        $result = $this->authenticationService->authenticate();
        if (!$result->isValid()) {
            /**
             * For security reason, you should not show user the reason of failure,
             * However, if it actually needed for specific purpose, you can pull by call:
             *
             *     $result->getMessages();
             *
             */
            return $this->redirect()->toRoute('/auth');
        }

        return $this->redirect()->toRoute('/account');
    }
}

For ZF Expressive, you can create routed Authentication middleware.

That’s it, you’re now have successfully created a client authentication for your ZF2/ZF3 or ZF Expressive application that consume Apigility oauth.

Unit and Functional testing Zend Framework 3 Controller with Kahlan 3.0

This post will cover unit and functional testing ZF3 Controller with Kahlan 3.0. For example, you have a ZF3 Skeleton application with an IndexController like the following:

namespace Application\Controller;

use Zend\Mvc\Controller\AbstractActionController;
use Zend\View\Model\ViewModel;

class IndexController extends AbstractActionController
{
    public function indexAction()
    {
        return new ViewModel();
    }
}

As usual, we need to require kahlan/kahlan:^3.0 via composer command:

composer require --dev kahlan/kahlan:^3.0 --sort-packages

You can then write the spec. Let’s write our spec inside module/Application/spec like the following structure:

module/Application/
├── config
├── spec
│   ├── Controller
│   │   ├── IndexControllerDispatchSpec.php
│   │   └── IndexControllerSpec.php
├── src
│   ├── Controller
│   │   ├── IndexController.php

if we are only have the 1 module, named Application module, we can define the spec and src path via kahlan-config.php like the following:

// ./kahlan.config.php
$commandLine = $this->commandLine();
$commandLine->option('spec', 'default', 'module/Application/spec');
$commandLine->option('src', 'default', 'module/Application/src');

Or for multi-modules, we can run parallel command that specify --spec and --src in command like the following:

vendor/bin/kahlan --spec=module/Application/spec --src=module/Application/src

in each iteration. If you’re using ant, you can write a build.xml for tasks definition:

<?xml version="1.0" encoding="UTF-8"?>
<project name="My Website" default="build">
    
    <!-- executable files directory definition -->
    <property name="toolsdir" value="${basedir}/vendor/bin/"/>
    <!-- module directory definition --> 
    <property name="moduledir" value="${basedir}/module/"/>

    <target name="build"
            depends="kahlan"
            description=""/>

    <target name="kahlan"
            description="Run kahlan">
        
        <parallel>    
        
            <!-- Application -->    
            <exec executable="${toolsdir}kahlan" failonerror="true" taskname="kahlan">
                <arg 
                    line="-spec=${moduledir}Application/spec/ 
                    --src=${moduledir}Application/src"/>
            </exec>
            <!-- Application -->
            
            <!-- other modules run test definition go here --> 
        </parallel>
        
    </target>

</project>

Unit testing

Let’s write the unit testing inside spec/Controller/IndexControllerSpec.php:

namespace ApplicationSpec\Controller;

use Application\Controller\IndexController;
use Zend\View\Model\ViewModel;

describe('IndexController', function () {
    
    given('controller', function () {
        
        return new IndexController();
    
    });
    
    describe('->indexAction()', function() {
        
        it('instance of ViewModel', function() {
            
            $actual = $this->controller->indexAction();
            expect($actual)->toBeAnInstanceOf(ViewModel::class);
            
        });
        
    });
    
});

That’s enough for IndexController::indexAction() unit test, nothing complex logic we need to accomodate as it only return the ViewModel instance, so we just need to check if return values is instance of ViewModel.

Functional Testing

Now, we need to make sure if the dispatch response of IndexController::indexAction() by open ‘/’ url that shown by user is the expected result, that show a welcome page, let’s do with spec/Controller/IndexControllerDispatchSpec.php:

namespace ApplicationSpec\Controller;

use Zend\Console\Console;
use Zend\Mvc\Application;

describe('IndexController Dispatch', function () {
    
    // setup the Application
    beforeAll(function () {
        
        Console::overrideIsConsole(false);
        $appConfig = include __DIR__ . '/../../../../config/application.config.php';
        $this->application = Application::init($appConfig);

        $events = $this->application->getEventManager();
        $this->application->getServiceManager()
                          ->get('SendResponseListener')
                          ->detach($events);

    });
    
    // dispatch '/' page tests
    describe('/', function() {
        
        it('contains welcome page', function() {
            
            $request     = $this->application->getRequest();
            
            $request->setMethod('GET');
            $request->setUri('/'); 
            
            // run app with '/' url
            $app =  $this->application->run();
            
            // expect actual response is contain
            // a welcome page
            expect(
                $app->getResponse()->toString()
            )->toContain('<h1>Welcome to <span class="zf-green">Zend Framework</span></h1>');
            
        });
        
    });
    
});

That’s it 😉

Zend Framework 2 : Using Component as Module

If you use latest zendframework by requiring “zendframework/zendframework”: “^2.5”, You will now get various zendframework components tagged as ~2.7 or ~2.8 as per-component has own life based on each evolution. Interestingly, many components that has services, now act as module. You can check the components on zendframework blog post. In the components mentioned in the post, they will have Module class that uses ConfigProvider class when registering services. If you don’t get the Module class yet inside the components mentioned, you need to run:

composer update

Usage
We can consume the components as modules, for example, in config/application.config.php, you can define:

return [
    'modules' => [
        'Application',
        'Zend\Cache'
    ],
    //  other configs here 
];

If you check the services registered in Zend\Cache, you will get Zend\Cache\Service\StorageCacheAbstractServiceFactory::class that registered in abstract_factories, that allow us to configure cache services via array with ‘caches’ config as limbo when no services that has name inside the ‘caches’ array registered yet. So, for example, we have configured ‘caches’ config:

// config/autoload/global.php
return [
    // ...
    'caches' => [
        'cache_file' => [
            'adapter' => 'filesystem',
            'options' => [
                'ttl' => 7200,
                'cache_dir' => './data/cache',
            ],
        ],
    ],
];

We have cache_file as service name that utilize filesystem cache adapter as config above. We then can just consume the cache_file via service manager:

// assumption: $services is a Zend\ServiceManager\ServiceManager 
// that pulled during Mvc workflow
$services->get('cache_file')->setItem('foo', 'fooValue');
echo $services->get('cache_file')->getItem('foo');

Done 😉

Start Using Middleware Approach with new zend-mvc

zend-mvc 2.7.0 is coming, beside of the forward compatibility with V3 components, there is new middleware listener that allow us to do Dispatching PSR-7 middleware. The middleware can be an invokable class with __invoke() method like the following:

function __invoke($request, $response)
{
    $response->getBody()->write('Hello World!');

    return $response;
}

Ok, let’s start try it, create new project:

$ composer create-project zendframework/skeleton-application:dev-master newzf

After composer create-project done, as usual, you will get new project. zend-mvc 2.7.0 released today, so, You should get zend-mvc 2.7.0 already by run:

$ composer update

Now, We can create a middleware, for example, a HomeAction middleware:

namespace Application\Middleware;

class HomeAction
{
    public function __invoke($request, $response)
    {
        $response->getBody()->write('Hello World!');
        return $response;
    }
}
// module/Application/src/Application/Middleware/HomeAction.php

We then can replace the ‘home’ route:

namespace Application;

// ...
    'home' => [
        'type' => 'Literal',
        'options' => [
            'route' => '/',
            'defaults' => [
                'middleware' => Middleware\HomeAction::class,
            ],
        ],
    ],
// ...
// module/Application/config/module.config.php

As the Application\Middleware\HomeAction is a service, then it need to be registered in service_manager:

namespace Application;

use Zend\ServiceManager\Factory\InvokableFactory;

// ...
    'service_manager' => [
        'factories' => [
            Middleware\HomeAction::class => InvokableFactory::class,
        ],
    ]
// ...
// module/Application/config/module.config.php

Everything seems configured correctly, now, let’s start the server:

$ php -S localhost:8080 -t public

And open up in the browser: http://localhost:8080 ! So, the “Hello World!” will be shown!

Work with ViewModel

So, you now want to work with ViewModel with its layout, You can! Let’s do it. You can inject the Middleware with the Renderer and ViewManager.

use Zend\View\Renderer\PhpRenderer;
use Zend\Mvc\View\Http\ViewManager;

class HomeAction
{
    // ...
    public function __construct(
        PhpRenderer $renderer,
        ViewManager $view
    ) {
        $this->renderer = $renderer;
        $this->view = $view;
    }
    // ...
}
// module/Application/src/Application/Middleware/HomeAction.php

To make it work, we can create factory for it:

namespace Application\Middleware;

class HomeActionFactory
{
    public function __invoke($container)
    {
        $viewRenderer = $container->get('ViewRenderer');
        $viewManager  = $container->get('ViewManager');

        return new HomeAction($viewRenderer, $viewManager);
    }
}
// module/Application/src/Application/Middleware/HomeActionFactory.php

Based on the factory above, we then need to update the registered Application\Middleware\HomeAction service:

namespace Application;

// ...
    'service_manager' => [
        'factories' => [
            Middleware\HomeAction::class => Middleware\HomeActionFactory::class,
        ],
    ]
// ...
// module/Application/config/module.config.php

So, now, you can update the Middleware as follows:

use Zend\View\Renderer\PhpRenderer;
use Zend\Mvc\View\Http\ViewManager;
use Zend\View\Model\ViewModel;
use Zend\Diactoros\Response\HtmlResponse;

class HomeAction
{
    // ...
    public function __invoke($request, $response)
    {
        $viewModel = new ViewModel();
        $viewModel->setTemplate('application/index/index');
        
        $layout = $this->view->getViewModel();
        $layout->setVariable(
            'content',
            $this->renderer->render($viewModel)
        );

        return new HtmlResponse($this->renderer->render($layout));
    }
    // ...
}
// module/Application/src/Application/Middleware/HomeAction.php

Done! 😉

References:
– https://gist.github.com/weierophinney/b9dbff92e4446f49e248
– https://github.com/weierophinney/2015-10-22-ZF3

Testing Zend Framework 2 application using phpspec

If you’re going to start working with new ZF2 application, it is be a good chance to use phpspec for testing tool. We can describe specification and generate code that we already describe. Ok, let’s start with clone ZF2 skeleton application:

$ composer create-project zendframework/skeleton-application:dev-master zfnew

We will start application with “test first”, so, we can remove current module/Application’s classes:

$ cd zfnew
$ rm -rf module/Application/Module.php
$ rm -rf module/Application/src/Application/Controller/IndexController.php

The next step is setup requiring phpspec dependency and its needed extensions:

$ composer config bin-dir bin
$ composer require phpspec/phpspec:~2.3.0 \
                   henrikbjorn/phpspec-code-coverage:~1.0.1 \
                   ciaranmcnulty/phpspec-typehintedmethods:~1.1 --dev

We will use henrikbjorn/phpspec-code-coverage for code coverage generation, and ciaranmcnulty/phpspec-typehintedmethods for typehint generation when running phpspec.

By default, our Application module follow PSR-0 autoloader, so we need to define it in composer.json:

// ...
   "autoload": {
        "psr-0": {
            "Application\\": "module/Application/src/"
        }
    },
// ...

To make it registered in composer’s autoload, we need to run dump-autoload:

$ composer dump-autoload

To point spec to describe Application namespace inside module/Application/src, we need to setup phpspec config under phpspec.yml, we can place it in root zfnew project:

# zfnew/phpspec.yml
suites:
  application_suite:
    namespace: Application
    src_path: module/Application/src/
    spec_path: module/Application

extensions:
  - PhpSpec\Extension\CodeCoverageExtension
  - Cjm\PhpSpec\Extension\TypeHintedMethodsExtension

code_coverage:
  format:
    - html
    - clover
  whitelist:
    - module/Application/src
  output:
    html: coverage
    clover: build/logs/clover.xml

Ok, let’s generate our first spec:

$ bin/phpspec desc Application/Module

We will get output like the following:

We will get generated first spec like the following:

// module/Application/spec/Application/ModuleSpec.php
namespace spec\Application;

use PhpSpec\ObjectBehavior;
use Prophecy\Argument;

class ModuleSpec extends ObjectBehavior
{
    function it_is_initializable()
    {
        $this->shouldHaveType('Application\Module');
    }
}

And when we run:

$ bin/phpspec run

We will get generated class like this if we choose ‘Y’ answering “Do you want me to create Application\Module for you?” question:

And we will get a Module class inside module/Application/src/Application directory:

namespace Application;

class Module
{
}

We need to have more examples to achieve standard Module class, that has getConfig() method, and especially for Application module, we need onBootstrap(MvcEvent $e) method, so we can write examples like the following:

// module/Application/spec/Application/ModuleSpec.php
namespace spec\Application;

use Application\Module;
use PhpSpec\ObjectBehavior;
use Zend\EventManager\EventManager;
use Zend\Mvc\Application;
use Zend\Mvc\MvcEvent;

class ModuleSpec extends ObjectBehavior
{
    function it_is_initializable()
    {
        $this->shouldHaveType(Module::class);
    }

    function it_return_config()
    {
        $getConfig = $this->getConfig();

        $getConfig->shouldBeArray();
        $getConfig->shouldReturn(
            include __DIR__ . '/../../config/module.config.php'
        );
    }

    function its_bootstrap(MvcEvent $e, $application, $eventManager)
    {
        $application->beADoubleOf(Application::class);
        $eventManager->beADoubleOf(EventManager::class);

        $application->getEventManager()->willReturn($eventManager)->shouldBeCalled();
        $e->getApplication()->willReturn($application)->shouldBeCalled();

        $this->onBootstrap($e);
    }
}

And when run, we will get the following errors:

                                                                                
  Do you want me to create `Application\Module::getConfig()` for you? [Y/n] 
  Y
  Method Application\Module::getConfig() has been created.
                                                                                
  Do you want me to create `Application\Module::onBootstrap()` for you? [Y/n] 
  Y
  
  Method Application\Module::onBootstrap() has been created.
Application/Module                                                                
  18  - it return config
      is_array(null) expected to return true, but it did not.

Application/Module                                                                
  28  - its bootstrap
      some predictions failed:
        Double\Zend\Mvc\MvcEvent\P2:
          No calls have been made that match:
            Double\Zend\Mvc\MvcEvent\P2->getApplication()
          but expected at least one.  Double\Zend\Mvc\Application\P1:
          No calls have been made that match:
            Double\Zend\Mvc\Application\P1->getEventManager()
          but expected at least one.

            33%                                     66%                          3
1 specs
3 examples (1 passed, 2 failed)
708ms

Don’t worry about it, it is normal, we just need to fulfill what already described in code as we have generated code template:

namespace Application;

class Module
{

    public function getConfig()
    {
        // TODO: write logic here
    }

    public function onBootstrap(\Zend\Mvc\MvcEvent $mvcEvent)
    {
        // TODO: write logic here
    }
}

let’s fill it so it looks like:

namespace Application;

use Zend\Mvc\ModuleRouteListener;

class Module
{
    public function getConfig()
    {
        return include __DIR__ . '/../../config/module.config.php';
    }

    public function onBootstrap(\Zend\Mvc\MvcEvent $mvcEvent)
    {
        $eventManager        = $mvcEvent->getApplication()->getEventManager();
        $moduleRouteListener = new ModuleRouteListener();
        $moduleRouteListener->attach($eventManager);
    }
}

To prove, you can re-run bin/phpspec run and everything will be green ;).

Now, let’s create spec for Application\Controller\IndexController:

$ bin/phpspec desc Application/Controller/IndexController

And we can define the IndexControllerSpec:

// module/Application/spec/Application/Controller/IndexControllerSpec.php
namespace spec\Application\Controller;

use Application\Controller\IndexController;
use PhpSpec\ObjectBehavior;
use Zend\Mvc\Controller\AbstractActionController;
use Zend\View\Model\ViewModel;

class IndexControllerSpec extends ObjectBehavior
{
    function let(ViewModel $viewModel)
    {
        $this->beConstructedWith($viewModel);
    }

    function it_is_initializable()
    {
        $this->shouldHaveType(IndexController::class);
    }

    function it_is_extends_abstract_action_controller()
    {
        $this->shouldBeAnInstanceOf(AbstractActionController::class);
    }

    function its_index_action_return_view_model(ViewModel $viewModel)
    {
        $this->indexAction()->shouldReturn($viewModel);
    }
}

We use beConstructedWith(), so, we need to inject ViewModel into controller’s construction. We can run bin/phpspec run and we will get the following code:

// module/Application/src/Application/Controller/IndexController.php
namespace Application\Controller;

class IndexController
{

    public function __construct(\Zend\View\Model\ViewModel $viewModel)
    {
        // TODO: write logic here
    }

    public function indexAction()
    {
        // TODO: write logic here
    }
}

Let’s fulfill the examples as described in spec:

// module/Application/src/Application/Controller/IndexController.php
namespace Application\Controller;

use Zend\Mvc\Controller\AbstractActionController;

class IndexController extends AbstractActionController
{
    private $viewModel;

    public function __construct(\Zend\View\Model\ViewModel $viewModel)
    {
        $this->viewModel = $viewModel;
    }

    public function indexAction()
    {
        return $this->viewModel;
    }
}

We need to build the Controller with Factory, so we can describe the factory:

$ bin/phpspec desc Application/Factory/Controller/IndexControllerFactory

We can write spec examples:

// module/Application/spec/Application/Factory/Controller/IndexControllerFactorySpec.php
namespace spec\Application\Factory\Controller;

use Application\Controller\IndexController;
use Application\Factory\Controller\IndexControllerFactory;
use PhpSpec\ObjectBehavior;
use Zend\ServiceManager\FactoryInterface;
use Zend\ServiceManager\ServiceLocatorInterface;

class IndexControllerFactorySpec extends ObjectBehavior
{
    function it_is_initializable()
    {
        $this->shouldHaveType(IndexControllerFactory::class);
    }

    function it_is_implements_factory_interface()
    {
        $this->shouldImplement(FactoryInterface::class);
    }

    function it_is_create_indexcontroller(ServiceLocatorInterface $serviceLocator)
    {
        $this->createService($serviceLocator)
             ->shouldReturnAnInstanceOf(IndexController::class);
    }
}

When run bin/phpspec run, we will get generated code:

// module/Application/src/Application/Factory/Controller/IndexControllerFactory.php
namespace Application\Factory\Controller;

class IndexControllerFactory
{

    public function createService(\Zend\ServiceManager\ServiceLocatorInterface $serviceLocatorInterface)
    {
        // TODO: write logic here
    }
}

Let’s modify to fulfill the spec examples:

// module/Application/src/Application/Factory/Controller/IndexControllerFactory.php
namespace Application\Factory\Controller;

use Application\Controller\IndexController;
use Zend\ServiceManager\FactoryInterface;
use Zend\View\Model\ViewModel;

class IndexControllerFactory implements FactoryInterface
{
    public function createService(\Zend\ServiceManager\ServiceLocatorInterface $serviceLocatorInterface)
    {
        $viewModel = new ViewModel();
        return new IndexController($viewModel);
    }
}

So, everything looks good, we can run bin/phpspec run again, and we can get green result again:

We can see the coverage result in coverage/index.html:

Now, to make our ZF2 application still works when call ‘/’ in browser, we can update our module/Application/config/module.config.php:

// ...
    'controllers' => array(
        'factories' => array(
            'Application\Controller\Index' => 'Application\Factory\Controller\IndexControllerFactory'
        ),
    ),
// ...

That’s it 😉

Testing Zend Framework 2 factory using Prophecy

Simulate every detail what classes methods doing with phpunit sometime make you little crazy and make you do too many effort ? There is a library to reduce that! It named Prophecy, a “Highly opinionated mocking framework for PHP 5.3+”.

In this post, I want to show you in Zend Framework 2 application case, which if we are using ZF2 ~2.4.0, we already have zendframework/zend-test which require phpunit/phpunit:~4.0. The Prophecy is included in phpunit start from 4.5, so the requirement already met. If we use old ZF2 version, we can add "phpspec/prophecy-phpunit": "~1.5" under require-dev in our composer requirement.

For example, we have a factory class for controller creation like the following:

namespace MyModule\Factory\Controller;

use MyModule\Controller\MyController;
use Zend\ServiceManager\ServiceLocatorInterface;
use Zend\ServiceManager\FactoryInterface;

class MyControllerFactory implements FactoryInterface
{
    /**
     * @{inheritDoc}
     */
    public function createService(ServiceLocatorInterface $sl)
    {
        $services           = $sl->getServiceLocator();
        $formElementManager = $services->get('FormElementManager');
        $myForm             = $formElementManager->get('MyModule\Form\MyForm');
        
        $controller = new MyController($myForm);

        return $controller;
    }
}

Without Prophecy, we need write the tests like the following:

namespace MyModule\Factory\Controller;

use PHPUnit_Framework_TestCase;
use MyModule\Factory\Controller\MyControllerFactory;

/**
 * @author Abdul Malik Ikhsan <samsonasik@gmail.com>
 */
class MyControllerFactoryTest extends PHPUnit_Framework_TestCase
{
    /** @var MyControllerFactory */
    protected $factory;

    /** @var ServiceLocatorInterface */
    protected $serviceLocator;

    /** @var \Zend\Mvc\Controller\ControllerManager */
    protected $controllerManager;

    public function setUp()
    {
        $this->controllerManager = $this->getMockBuilder('Zend\Mvc\Controller\ControllerManager') 
                                        ->disableOriginalConstructor()
                                        ->getMock();
        $this->serviceLocator    = $this->getMock('Zend\ServiceManager\ServiceLocatorInterface');

        $factory = new MyControllerFactory();
        $this->factory = $factory;
    }

    public function testCreateService()
    {
        $formElementManager = $this->getMockBuilder('Zend\Form\FormElementManager')
                                   ->disableOriginalConstructor()
                                   ->getMock();
        $myForm  = $this->getMockBuilder('MyModule\Form\MyForm')
                                   ->disableOriginalConstructor()
                                   ->getMock();
        $formElementManager->expects($this->once())
                           ->method('get')
                           ->willReturn($myForm);
        $this->serviceLocator->expects($this->once())
                             ->method('get')
                             ->with('FormElementManager')
                             ->willReturn($FormElementManager);
        
        $this->controllerManager->expects($this->once())
                                ->method('getServiceLocator')
                                ->willReturn($this->serviceLocator);

        $result = $this->factory->createService($this->controllerManager);
        $this->assertInstanceOf('MyModule\Controller\MyControllerFactory', $result);
    }
}

This is the example for 1 dependency, we can to call expects($this->once()), what if we have many dependencies which use many services?, we can end up doing something like this:

$myService1 = $this->getMockBuilder('MyModule\Service\MyService1')
                   ->disableOriginalConstructor()
                   ->getMock();
$this->serviceLocator->expects($this->at(0))
                     ->method('get')
                     ->with('MyService1')
                     ->willReturn($myService1);
$myService2 = $this->getMockBuilder('MyModule\Service\MyService2')
                   ->disableOriginalConstructor()
                   ->getMock();
$this->serviceLocator->expects($this->at(1))
                  ->method('get')
                  ->with('MyService2')
                  ->willReturn($myService2);

And if we added a service dependency in the middle, we need to reset the increment.

With Prophecy, it now simplified, we can eliminate them, and use the mock just like the object do, like the following:

$formElementManager = $this->prophesize('Zend\Form\FormElementManager');
$myForm             = $this->prophesize('MyModule\Form\MyForm');
$formElementManager->get('MyModule\Form\MyForm')->willReturn($myForm);

Let’s see the full code for testing factory above if we are using Prophecy:

namespace MyModule\Factory\Controller;

use PHPUnit_Framework_TestCase;
use MyModule\Factory\Controller\MyControllerFactory;

/**
 * @author Abdul Malik Ikhsan <samsonasik@gmail.com>
 */
class MyControllerFactoryTest extends PHPUnit_Framework_TestCase
{
    /** @var MyControllerFactory */
    protected $factory;

    /** @var ServiceLocatorInterface */
    protected $serviceLocator;

    /** @var \Zend\Mvc\Controller\ControllerManager */
    protected $controllerManager;

    public function setUp()
    {
        $this->controllerManager = $this->prophesize('Zend\Mvc\Controller\ControllerManager');
        $this->serviceLocator    = $this->prophesize('Zend\ServiceManager\ServiceLocatorInterface');

        $factory = new MyControllerFactory();
        $this->factory = $factory;
    }

    public function testCreateService()
    {
        $formElementManager = $this->prophesize('Zend\Form\FormElementManager');
        $myForm             = $this->prophesize('MyModule\Form\MyForm');
        $formElementManager->get('MyModule\Form\MyForm')->willReturn($myForm);
        $this->serviceLocator->get('FormElementManager')->willReturn($formElementManager);
        $this->controllerManager->getServiceLocator()->willReturn($this->serviceLocator);

        $result = $this->factory->createService($this->controllerManager->reveal());
        $this->assertInstanceOf('MyModule\Controller\MyController', $result);
    }
}

That’s it ;). It now simplified.

Zend Framework 2 : Using __invoke(PluginManager $manager) in Service’s Factory

I assume you already knew about registering service with factories type via closure or factory class that implements Zend\ServiceManager\FactoryInterface which is quite complex to do, and if we use pluginManager, for example, on Controller creation, we pushed to use :

namespace Application\Factory\Controller;

use Application\Controller\IndexController;
use Zend\ServiceManager\FactoryInterface;
use Zend\ServiceManger\ServiceLocatorInterface;

class IndexControllerFactory implements FactoryInterface
{
    public function createService(ServiceLocatorInterface $serviceLocator)
    {
        $services  = $serviceLocator->getServiceLocator();    
        $myService = $services->get('MyService');
        
        return new IndexController($myService);
    }
}

Although above way will work, if you check above code with scrutinizer, you will get error :

This is because the getServiceLocator() only exists in the concrete implementation(the ControllerManager class), not in the ServiceLocatorInterface interface.

__invoke(PluginManager $manager) for the rescue

If you read the documentation, you can get quote :

The factories should be either classes implementing Zend\ServiceManager\FactoryInterface 
or invokable classes.

That mean, you can use class that has __invoke() method, so you can pass the PluginManager instead of ServiceLocatorInterface.

namespace Application\Factory\Controller;

use Application\Controller\IndexController;
use Zend\Mvc\Controller\ControllerManager;

class IndexControllerFactory
{
    public function __invoke(ControllerManager $controllerManager)
    {
        $services  = $controllerManager->getServiceLocator();
        $myService = $services->get('MyService');
        
        return new IndexController($myService);
    }
}

Now, your scrutinizer check will be happy ;).

Note :
As Lucas Suggestion, if you still want to use createService(), you can check it with whenever $serviceLocator instanceof Zend\ServiceManager\ServiceLocatorAwareInterface, then we call getServiceLocator() :

// ...
function createService(ServiceLocatorInterface $serviceLocator)
{
   if ($serviceLocator instanceof ServiceLocatorAwareInterface) {
       $serviceLocator = $serviceLocator->getServiceLocator();
   }
   // ...
}
// ...

References :
1. http://blog.alejandrocelaya.com/2014/10/09/advanced-usage-of-service-manager-in-zend-framework-2/#comment-1627763990
2. https://samsonasik.wordpress.com/2013/01/02/zend-framework-2-cheat-sheet-service-manager/
3. http://framework.zend.com/manual/current/en/modules/zend.service-manager.quick-start.html#using-configuration

Conditional Redirect on ZfcUser when login success

I have been digging with ZfcUser in this week, and I realize, I need to do conditional redirection when authentication successful. With current version ( 1.2.2 ), the ‘login_redirect_route’ only support ‘string’ value,  which is very strict. We currently can’t pass callable to it like the following code ( hopefully, in next version or  2.* we can do ) :

'login_redirect_route' => function(\ZfcUser\Entity\UserInterface $user) {
    if ($user->getRole()->getName() === 'admin') {
        return 'zfcadmin';
    }
    return 'zfcuser';
}

We need another approach right now!

Clues

1. ZfcUser\Options\ModuleOptions

The ZfcUser configuration is consumed by ZfcUser\Options\ModuleOptions, registered as ‘zfcuser_module_options’ service, so, we can use it to re-set the ‘loginRedirectRoute’ property value, and re-register as service.

2. ‘authenticate.success’ event

‘authenticate.success’ is an event that will be triggered when we catch that user has Identity on Authentication process, in ZfcUser\Authentication\Adapter\AdapterChain::prepareForAuthentication.

Execution

With 2 clues above, What we can do now is, using listener that re-set ‘zfcuser_module_options’ service which bring new ‘loginRedirectRoute’, that react to ‘authenticate.success’. We can do in our Module class like the following :

use Application\Entity\User;
class Module
{
    // ...
    public function onBootstrap($e)
    {
        $servicemaManager = $e->getTarget()->getServiceManager();
        $objectManager    = $serviceManager->get('objectManager');

        $zfcAuthEvents    =  $serviceManager->get('ZfcUser\Authentication\Adapter\AdapterChain')->getEventManager();
        $zfcAuthEvents->attach('authenticate.success', function($authEvent) use ($serviceManager, $objectManager) {
            $userId = $authEvent->getIdentity();
            $user   = $objectManager->find(User::class, $userId);

            if ($user->getRole()->getName() === 'admin') {
                // we are going to re-set service,
                // we need to set allow_override of serviceManager= true
                $serviceManager->setAllowOverride(true);

                $zfcuserModuleOptions = $serviceManager->get('zfcuser_module_options');
                $zfcuserModuleOptions->setLoginRedirectRoute('zfcadmin');
                $serviceManager->setService('zfcuser_module_options', $zfcuserModuleOptions);

                // set 'allow_override' back to false
                $serviceManager->setAllowOverride(false);
            }
        });
    }
}

Now, whenever we got role name = ‘admin’ during authentication process, we will be redirected to ‘zfcadmin’ route.

References :
1. http://stackoverflow.com/questions/16053479/zfcuser-redirect-roles-to-different-pages-after-login
2. Conversation with Mr. Daniel Strøm
3. http://circlical.com/blog/2013/7/5/capturing-auth-events-with-zfcuser

Using Ember.js in Zend Framework 2 Application

Ember.js is one of the javascript frameworks that adopt Single-Page Application principles. When working with Zend Framework 2 application, we can terminate 2 step view process to just render the view (not the layout) when the request that comes is XmlHttpRequest. We can do it in our Module.php like the following code :

use Zend\View\Model\ViewModel;

class Module
{
    public function onBootstrap($e)
    {
        $eventManager = $e->getApplication()->getEventManager();
        $sharedEvents = $eventManager->getSharedManager();
        $sharedEvents->attach('Zend\Mvc\Controller\AbstractActionController',
            'dispatch', function($e)
        {
            $result = $e->getResult();
            if ($result instanceof ViewModel) {
                $result->setTerminal($e->getRequest()->isXmlHttpRequest());
            }
        });

        // ...
    }
    
    // ...
}

At this post, I will try to make a 3 static page : ‘Home’, ‘About’, and ‘Contact’ in Application module. Let’s first create the navigation :

// config/autoload/navigation.global.php
return [
    'navigation' => [
        'default' => [
            [
                'label' => 'Home',
                'route' => 'home'
            ],
            [
                'label'  => 'About',
                'route'  => 'about',
            ],
            [
                'label' => 'Contact',
                'route' => 'contact',
            ],
        ],
    ],
];

We can then register the navigation service :

// module/Application/config/module.config.php
// ...
   'service_manager' => [
      'factories' => [
            'Navigation' => 'Zend\Navigation\Service\DefaultNavigationFactory',
       ],
    ]
// ...

From the navigation registered above, we can create 3 controller like this :
1. IndexController

// module/Application/src/Application/Controller/IndexController.php
namespace Application\Controller;

use Zend\Mvc\Controller\AbstractActionController;
use Zend\View\Model\ViewModel;

class IndexController extends AbstractActionController
{
    public function indexAction()
    {
        return new ViewModel();
    }
}

2. AboutController

// module/Application/src/Application/Controller/AboutController.php
namespace Application\Controller;

use Zend\Mvc\Controller\AbstractActionController;
use Zend\View\Model\ViewModel;

class AboutController extends AbstractActionController
{
    public function indexAction()
    {
        return new ViewModel();
    }
}

3. ContactController

// module/Application/src/Application/Controller/ContactController.php
namespace Application\Controller;

use Zend\Mvc\Controller\AbstractActionController;
use Zend\View\Model\ViewModel;

class ContactController extends AbstractActionController
{
    public function indexAction()
    {
        return new ViewModel();
    }
}

Controllers created, we can register it into module.config.php under ‘router’ and ‘controllers’ :

// module/Application/config/module.config.php
// ...
   'router' => [
        'routes' => [
            'about' => [
                'type'    => 'Literal',
                'options' => [
                    'route'    => '/about',
                    'defaults' => [
                        'controller' => 'Application\Controller\About',
                        'action'        => 'index',
                    ],
                ],
            ],

            'contact' => [
                'type'    => 'Literal',
                'options' => [
                    'route'    => '/contact',
                    'defaults' => [
                        'controller' => 'Application\Controller\Contact',
                        'action'        => 'index',
                    ],
                ],
            ],
         ],
    ],

    'controllers' => [
        'invokables' => [
            'Application\Controller\Index' => 'Application\Controller\IndexController',
            'Application\Controller\Contact' => 'Application\Controller\ContactController',
            'Application\Controller\About' => 'Application\Controller\AboutController',
        ],
    ],
// ...

I assume you have using default ZendSkeletonApplication so the IndexController route already defined. Ok, now we need to fill the view.
1 index view ( same as the skeleton app view/application/index/index.phtml )
2 about view

// module/Application/view/application/about/index.phtml
<h1>About Me</h1>
<p>
    I'm a web developer.
</p>

3 contact view

// module/Application/view/application/contact/index.phtml
<h1>Contact Me</h1>
<p>
    You can contact me via <a href="mailto: foo@bar.baz.com">foo@bar.baz.com</a>
</p>

Yup, Let’s go to javascript side.

First, require Ember.js in bower.json and install it :

// bower.json
{
    "name":"ZF2 App with Ember Demo",
    "dependencies": {
        "ember": "1.*"
    }
}

Configure it to be installed in public/js folder in .bowerrc.

// .bowerrc
{
    "directory": "public/js",
    "json": "bower.json"
}

Run bower install :

bower install

For Ember 1.10, As we will need template compilation, We need to require ember-template-compiler like shown in here. To make it included, we need to require it in layout.phtml in headScript() view helper :

echo $this->headScript()
            ->prependFile($this->basePath() . '/js/bootstrap.min.js')
            ->prependFile($this->basePath() . '/js/jquery.min.js')
            ->prependFile($this->basePath() . '/js/respond.min.js', 'text/javascript', array('conditional' => 'lt IE 9',))
            ->prependFile($this->basePath() . '/js/html5shiv.js',   'text/javascript', array('conditional' => 'lt IE 9',))

            // ember js dependencies
            ->appendFile($this->basePath() . '/js/ember/ember-template-compiler.js')
            ->appendFile($this->basePath() . '/js/ember/ember.min.js');
        ; 

Now, we need to create a new javascript file for its application specific requirement, I name it app.js :

// public/js/app.js
App = Ember.Application.create();

App.Router.map(function() {
    this.resource('home', {
        path: '/'
    });
    this.resource('about');
    this.resource('contact');
});

Layout

We need to replace :

<?php echo $this->content; ?>

with

{{outlet}}

And wrap it in <script type="text/x-handlebars"> :

// module/Application/view/layout/layout.phtml
// ...
<script type="text/x-handlebars">
        <nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">
            <div class="container">
                <div class="navbar-header">
                    <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
                        <span class="icon-bar"></span>
                        <span class="icon-bar"></span>
                        <span class="icon-bar"></span>
                    </button>
                    <a class="navbar-brand" href="<?php echo $this->url('home') ?>"><img src="<?php echo $this->basePath('img/zf2-logo.png') ?>" alt="Zend Framework 2"/> <?php echo $this->translate('Skeleton Application') ?></a>
                </div>
                
                    <div class="collapse navbar-collapse">
                        <ul class="nav navbar-nav">
                            <?php $navigationContainer = $this->navigation('navigation')->getContainer();
                                  foreach($navigationContainer as $page) {
                            ?>
                                <li>
                                    {{#link-to '<?php echo $page->get('route'); ?>'}}
                                        <?php echo $page->get('label'); ?>
                                    {{/link-to}}
                                </li>  
                            <?php   }   ?>
                        </ul>
                        
                    </div><!--/.nav-collapse -->
            </div>
        </nav>
        
        <div class="container">
            {{outlet}}
        </div>
</script>

We need to require our public/js/app.js in footer :

<?php
$script =  $this->inlineScript();
$script->appendFile($this->basePath() . '/js/app.js');

echo $script;
?>
</body> // means in the footer!

Yup, time to make ajax works, modify public/js/app.js by adding the following codes :

// public/js/app.js
// ...
App.HomeRoute = Ember.Route.extend({
   beforeModel: function() {
     return $.ajax({
        url: '/'
     })
     .then(function(response) {
        Ember.TEMPLATES.home = Ember.Handlebars.compile(response);
    });
   }
});

App.AboutRoute = Ember.Route.extend({
   beforeModel: function() {
     return $.ajax({
        url: '/about'
     })
     .then(function(response) {
        Ember.TEMPLATES.about = Ember.Handlebars.compile(response);
    });
   }
});

App.ContactRoute = Ember.Route.extend({
   beforeModel: function() {
     return $.ajax({
        url: '/contact'
     })
     .then(function(response) {
        Ember.TEMPLATES.contact = Ember.Handlebars.compile(response);
    });
   }
});

// to remove # ( hash ) in url
if (window.history && window.history.pushState) {
    App.Router.reopen({
      location: 'history'
    });
}

Great! If everything ok, then your ZF2 app with Ember.js should work like a magic! The requested page loaded without refreshing the page!.

Bonus

You can make ‘li’ under ‘ul’ for navigation class setted to active when it in the page, with create new ‘li’ component, we can add it in public/js/app.js

// public/js/app.js
// ...
App.LinkLiComponent = Ember.Component.extend({
  tagName: 'li',
  classNameBindings: ['active'],
  active: function() {
    return this.get('childViews').anyBy('active');
  }.property('childViews.@each.active')
});

Ember.Handlebars.helper('link-li', App.LinkLiComponent);

And then, we can modify the looks like :

// module/Application/view/layout/layout.phtml
// ...
<?php $navigationContainer = $this->navigation('navigation')->getContainer();
      foreach($navigationContainer as $page) { ?>

     {{#link-li}}
        {{#link-to '<?php echo $page->get('route'); ?>'}}
           <?php echo $page->get('label'); ?>
        {{/link-to}}
     {{/link-li}}  

<?php   }   ?>

Ok, I hope it useful for you ;). Want to grab the sourcecode ? Clone from my repository https://github.com/samsonasik/zfember 😉

Images :
1. http://www.gravatar.com/avatar/0cf15665a9146ba852bf042b0652780a?s=200
References :
1. http://emberjs.com/
2. http://code.tutsplus.com/tutorials/getting-into-ember-js-part-2–net-31132
3. http://code.tutsplus.com/tutorials/getting-into-emberjs-part-3–net-31394
4. http://stackoverflow.com/questions/17792280/ember-live-uploading-templates
5. http://stackoverflow.com/questions/19871265/ember-js-with-external-handlebars-template
6. http://stackoverflow.com/questions/14328295/how-do-i-bind-to-the-active-class-of-a-link-using-the-new-ember-router
7. http://en.wikipedia.org/wiki/Single-page_application
8. http://emberjs.com/blog/2015/02/07/ember-1-10-0-released.html

Zend Framework 2 : Check request URI matched against registered Router

When you develop web application using Zend Framework 2, there is sometime you get the situation that you need to check requested URI matched against registered ‘Router’, for example : you have uri : http://zf2app/register?redirect=/user  which the application will redirect to passed ‘redirect’ parameter. What if user make bypassed and inject unexpected redirect param ? For example, you have code like this in your controller action :

$redirect = $this->params()->fromQuery('redirect','');
return $this->redirect()->toUrl($redirect);

We can inject unwanted redirect into browser, and BOOM, the site will be redirected to unwanted uri. So, we need to handle it! we need to check whenever the ‘redirect’ value can be matched with registered Router.
First, check if the request URI can be matched against registered Router.

$redirect = $this->params()->fromQuery('redirect','');

$request  = $this->getRequest();
$request->setUri($redirect);

// assignment, not Comparison, that's why use single '='
if ($routeToBeMatched = $this->getServiceLocator()->get('Router')->match($request)) {
    // ... process redirection based on 'redirect' param...
}

When request URI matched against registered Router, then we assign it to $routeToBeMatched variable, we can procees it. What if the “redirect route equals current route” ? We can check it under if.

if ($routeToBeMatched = $this->getServiceLocator()->get('Router')->match($request)) {
   // handle if redirect route = current route
   $currentRouteMatchName = $this->getEvent()->getRouteMatch()->getMatchedRouteName();
   if ($routeToBeMatched->getMatchedRouteName() != $currentRouteMatchName) {
       return $this->redirect()->toUrl($redirect);
   }
}

Great! now, handle default redirection when doesnt’ match :

if ($routeToBeMatched = $this->getServiceLocator()->get('Router')->match($request)) {
    // handle if redirect route = current route
    $currentRouteMatchName = $this->getEvent()->getRouteMatch()->getMatchedRouteName();
    if ($routeToBeMatched->getMatchedRouteName() != $currentRouteMatchName) {
        return $this->redirect()->toUrl($redirect);
    }
}
return $this->redirect()->toUrl('/user');

Ok, this is the complete code sample:

$redirect = $this->params()->fromQuery('redirect','');

$request  = $this->getRequest();
$request->setUri($redirect);

if ($routeToBeMatched = $this->getServiceLocator()->get('Router')->match($request)) {
    // handle if redirect route = current route
    $currentRouteMatchName = $this->getEvent()->getRouteMatch()->getMatchedRouteName();
    if ($routeToBeMatched->getMatchedRouteName() != $currentRouteMatchName) {
        return $this->redirect()->toRoute($redirect);
    }
}
return $this->redirect()->toUrl('/user');

Update: There is a module for that that I created, go grab it here: https://github.com/samsonasik/RedirectHandlerModule 😉