saeven/zf3-circlical-autowire

Annotation based routing, and magic Controller creation for ZF3.

Route Auto-Wiring for Laminas-MVC

, _(*1)

A laminas-mvc module that favors rapid development, it does two things:, _(*2)

• compiles routes to standard PHP arrays for production (and merges them automatically for you too). Does not compete with standard route declarations (both can be used in tandem).
• automatically applies DI into your controllers, do you don't need to write a ton of simple factories

Older versions support zend-mvc, check releases., _(*3)

Use annotations right above your actions to automatically plug routes into the ZF3 Router. No more gear-switching to route files, or digging through route config arrays when you are refactoring., _(*4)

This module also provides a reflection-based abstract factory to automatically wire your controllers using their constructors. Just define your constructors (as you should) and let the lazy factory do the rest!, _(*5)

Installation

Install with:, _(*6)

composer require zf3-circlical-autowire

Then, add it near the top of your application.config.php, _(*7)

'CirclicalAutoWire',

Automatic Controller DI

Don't need to do anything. Excellently lazy, it's automatic. You can code Controllers, add dependencies to your constructor, and this module will inject classes from your service container right into your controller., _(*8)

Automatic Routes

In any controller that should use this module, simply add this use statement:, _(*9)

use CirclicalAutoWire\Annotations\Route;

Method Annotations

On any action in a controller with the use statement, use these types of annotations:, _(*10)

<?php
/**
 * Your usual stuff here
 * @returns bool
 * @Route("/freedom")
 */
 public function anyOldNameAction(){
    // this beats editing a route file each time!
 }

/**
 * This route has a parameter
 * @Route("/freedom/:param")
 */
 public function anyOldNameAction(){
    $this->params()->fromRoute('param');
 }

/**
 * This route has a parameter and a constraint
 * @Route("/freedom/:param", constraints={"param":"[a-zA-Z]"})
 */
 public function anyOldNameAction(){
    // ...
 }

/**
 * Route with parameter, constraint, and defaults
 * @Route("/freedom/:param", constraints={"param":"[a-zA-Z]"}, defaults={"param":"index"})
 */
 public function anyOldNameAction(){
    // ...
 }

/**
 * Route with parameter, name, constraint, and defaults
 * @Route("/freedom/:param", name="easy-as-pie", constraints={"param":"[a-zA-Z]"}, defaults={"param":"index"})
 */
 public function anyOldNameAction(){
    // ...
 }

Child Routes

Child routes are simple to define. Define the parent by giving it a name, and whether or not it may terminate. Separately, tell the child routes that their parent is that first route (by way of name). Here's a complete example:, _(*11)

<?php
/**
 * Class ChildRouteController
 * @package Spec\CirclicalAutoWire\Controller
 */
class ChildRouteController extends AbstractActionController
{

    /**
     * @Route("/icecream", name="icecream", terminate=true)
     */
    public function indexAction(){}

    /**
     * This is a sample docblock
     *
     * @Route("/eat", parent="icecream", name="eat")
     */
    public function eatAction(){}


    /**
     * @Route("/select/:flavor", constraints={"flavor":"\d"}, name="select", parent="icecream")
     */
    public function selectFlavorAction(){}

}

This will produce:, _(*12)

<?php
'router' => [
    'routes' => [
        'icecream' => [
            'type' => Literal::class,
            'options' => [
                'route' => '/icecream',
                'defaults' => [
                    'controller' => ChildRouteController::class,
                    'action' => 'index',
                ],
            ],
            'may_terminate' => true,
            'child_routes' => [
                'eat' => [
                    'type' => Literal::class,
                    'options' => [
                        'route' => "/eat",
                        'defaults' => [
                            'controller' => ChildRouteController::class,
                            'action' => 'eat',
                        ],
                    ],
                ],
                'select' => [
                    'type' => Segment::class,
                    'options' => [
                        'route' => "/select/:flavor",
                        'defaults' => [
                            'controller' => ChildRouteController::class,
                            'action' => 'selectFlavor',
                        ],
                        'constraints' => [
                            'flavor' => '\d',
                        ],
                    ],
                ],
            ],
        ],
    ],
],

Controller Annotations

Provided as a convenience, these help you reach a higher level of lazy. If you know all your Controller routes will start with /index/system, simply annotate your controller as such:, _(*13)

<?php
/**
 * Controller Index
 * @Route("/index/system")
 */
 class IndexController extends AbstractActionController
 {

     /**
      * @Route("/update")
      */
     public function updateAction(){

     }

     /**
      * @Route("/get/:id")
      */
     public function getAction(){

     }
 }

In the example above, the following routes will be compiled:, _(*14)

• /index/system/update
• /index/system/get/:id

Two Modes

Mode is set, via config., _(*15)

Development

In this mode, annotations are scanned and read. There's an incredibly small overhead to scanning Controller code. Each time you refresh, you will see the compiled routes file recreated in the location you have specified (see this Module's config file)., _(*16)

Production

In this mode, annotations are not scanned. Instead, the config file you created in dev mode is automatically merged with your Zend Framework's routes/route config to create a 'traditional' scenario where routes are hardcoded. Zero module overhead., _(*17)

Important Note: When actuated via the console, it will behave as though it were in production mode, _(*18)

I hope you like this module, you can reach out on freenode's #zftalk or @Saeven on Twitter! All PRs considered!, _(*19)