Download the PHP package vkr/controller-delegation-bundle without Composer

About

This small bundle enables usage of the Delegation pattern in Symfony controllers. Its main use-case is when you create a reusable component that requires some controller logic but does not require to define complete controllers and templates. It can be said that the goal of this bundle is to provide a system of bundle inheritance that is more lightweight and hassle-free than default Symfony bundle inheritance.

This bundle consists just of three classes - two abstract and one concrete. It does not do anything by itself, and is designed to be used as a dependency in other reusable bundles.

This bundle has no dependencies other than Symfony itself.

Philosophy

Suppose you have some reusable code that involves a lot of manipulation with the container and invoking other useful controller methods such as . Of course, you can put these into an actual controller, but then you also have to define a view. Both controller actions and views can be overridden by bundle inheritance, but that involves following a naming convention, and that can be inconvenient. For example, customizing is not the easiest thing in the world.

The philosophy behind this bundle states that it will be easier for a client coder to invoke a delegate method inside each controller action that would accept the same arguments as the actual controller but might return something other than HTTP response. The controller then parses the results of delegate's work in whatever way it deems necessary.

Thus, it can be said that the actual controller acts as a decorator for the delegate class.

Usage

Create a delegate class that should extend . This class is container-aware and has access to all controller methods via . It should return the same instance of class that was created in its parent constructor under the name of .

Use it in the following way:

All setter methods of return its instance. You could also write

Then it is expected that the client coder will create a controller that will extend and write the following method in it:

is a shortcut for getting template variables. It is generally recommended that both controller method and delegate method have same signatures.

Dealing with redirects

If there are any redirects that you wish to return, things become more tricky. The concept is that the delegate class creator should not hardcode any route names. These are replaced with special markers, such as 'success' or 'failure'. Then you do something like this in your delegate class:

For these markers to be parsed, they must be first declared as class property:

Note that required routes list can be neither declared nor redefined in action methods.

Then, this should be added to your controller:

If your delegate can return both redirect and non-redirect values, the controller will look as follows:

If the object contains both redirect and non-redirect values, redirect will take precedence.

If your route comes with parameters, you can modify your controller as follows:

Finally, if you want to skip some of required parameters, you can use key:

Sometimes, you will want to use external links for redirect, e.g. an API call. Here is how you do it:

Dealing with additional render calls

Suppose that inside your controller logic you need to render something that is not going to be returned by the controller. The best example here is sending emails. In this case, you just need to pass an extra argument to the delegate action, and then parse it somehow in your delegate:

Inside your delegate you can use

Note that template name and template variables should not be hardcoded inside the delegate class.

Best practices

• Put your delegate classes in a separate folder and append to their class names.
• Use one delegate method per every controller method. The names of delegate method and corresponding controller method should be identical.
• Do not initialize the delegate object inside your controller's constructor or any method called by constructor. While not causing any errors by itself, using the constructor might cause bugs in the future, if you invoke some container methods from the delegate's constructor. In Symfony, the container gets filled with contents AFTER the controller object is created.
• Do not put business logic in your delegate classes and try to keep them skinny.
• Do not unit-test your delegate classes. Delegate classes should only keep controller logic in them, and controller logic is not unit-testable.