1.
The Naked Bundle
Matthias Noback
@matthiasnoback
Symfony Usergroup Belgium
October 13th, 2014

2.
What's it all about?

3.
An actual naked bundle

4.
I could've called it
BundleLitetm
The No Code Bundle
The Clean Bundle

5.
But “naked” was catchy and controversial

6.
Until Pierre came along

7.
The official view on bundles

8.
First-class citizens
Documentation » The Quick Tour » The Architecture

9.
Importance
Your code is more important than
the framework,
which is an implementation detail

10.
Reuse

11.
Nice!

12.
All your code lives in a bundle
Documentation » The Book » Creating Pages in Symfony2

13.
Reuse
“All your code in a bundle”
contradicts the promise of reuse

14.
Everything lives inside a bundle
Documentation » Glossary

15.
Not really true
Many things live inside libraries
(the Symfony components are
libraries too!)

16.
Which is good!

17.
But you probably know that already

18.
“libraries first”

19.
What about...
● Controllers
● Entities
● Templates
● ...

20.
They just need to be in a bundle
Or do they?

21.
Don't get me wrong
I love Symfony!

22.
But a framework is just a framework
● Quickstarter for your projects
● Prevents and solves big security
issues for you
● Has a community you can rely on

23.
A framework is there for you

24.
Your code doesn't need a framework

25.
Noback's Principle
Code shouldn't rely on something
it doesn't truly need

26.
Bundle conventions
Things in a bundle often rely on
conventions to work

27.
Conventions aren't necessary at all

28.
So according to Noback's Principle,
code shouldn't rely on bundle conventions too

29.
Naming conventions
Controllers:
● *Controller classes
● *action methods
Templates:
● in /Resources/views
● name: Controller/Action.html.twig

30.
Structural conventions
Controller:
● Extends framework Controller class
● Is ContainerAware

31.
Behavioral conventions
Controller:
● Is allowed to return an array
● Actions can type-hint to objects which will be
fetched based on route parameters (??)

32.
Configuration conventions
Use lots of annotations!
/**
* @Route("/{id}")
* @Method("GET")
* @ParamConverter("post", class="SensioBlogBundle:Post")
* @Template("SensioBlogBundle:Annot:show.html.twig")
* @Cache(smaxage="15", lastmodified="post.getUpdatedAt()")
* @Security("has_role('ROLE_ADMIN')")
*/
public function showAction(Post $post)
{
}

33.
These conventions are what makes an application
a Symfony2 application

34.
A Year With Symfony

35.
About bundles

36.
A bundle exposes resources

37.
Resources
● Service definitions
● Controllers
● Routes
● Templates
● Entities
● Form types
● Event listeners
● Translations
● ...

38.
No need for them to be inside a bundle

39.
When placed outside the bundle
the resources could be reused separately

40.
The bundle would be really small

41.
And could just as well be a:
Laravel package,
Zend or Drupal module,
CakePHP plugin,
...

42.
So the challenge is to
Make the bundle as clean as possible

43.
Move the “misplaced” things to
● a library
● with dependencies
● but not symfony/framework­bundle
;)

44.
Being realistic
Practical reusability

45.
Reuse within the Symfony family
Think: Silex, Laravel, etc.

46.
Allowed dependency
HttpFoundation
● Request
● Response
● Exceptions
● etc.

47.
What do we rely on
HttpKernel
namespace SymfonyComponentHttpKernel;
use SymfonyComponentHttpFoundationRequest;
use SymfonyComponentHttpFoundationResponse;
interface HttpKernelInterface
{
/**
* Handles a Request to convert it to a Response.
*/
public function handle(Request $request, ...);
}

48.
Why? My secret missions
“Let's rebuild the application, but
this time we use Zend4 instead of
Symfony2”

49.
And of course
Education

50.
You need a strong coupling radar

51.
Explicit dependencies
● Function calls
● Imported classes (“use”)
● Included files
● ...

52.
Implicit dependencies
● File locations
● File, class, method names
● Structure of return values
● ...

53.
There we go!

54.
use SymfonyBundleFrameworkBundleControllerController;
use SensioBundleFrameworkExtraBundleConfigurationRoute;
use SensioBundleFrameworkExtraBundleConfigurationTemplate;
/**
* @Route(“/article”)
*/
class ArticleController extends Controller
{
/**
* @Route(“/edit”)
* @Template()
*/
function editAction(...)
{
...
}
}
Controller

55.
TODO
✔ Don't rely on things that may not
be there in another context:
✔ Parent Controller class
✔ Routing, template, annotations, etc.

56.
class ArticleController
{
function editAction(...)
{
...
}
}
Nice and clean ;)

57.
use SymfonyComponentHttpFoundationRequest;
class ArticleController
{
public function editAction(Request $request)
{
$em = $this­>
get('doctrine')­>
getManager();
...
if (...) {
throw $this­>
createNotFoundException();
}
...
return array(
'form' => $form­>
createView()
);
}
}
Zooming in a bit

58.
TODO
✔ Inject dependencies
✔ Don't use helper methods
✔ Render the template manually
✔ Keep using Request
(not really a TODO)

59.
use DoctrineORMEntityManager;
class ArticleController
{
function __construct(
EntityManager $em,
) {
$this­>
em = $em;
}
...
}
Inject dependencies

60.
Inline helper methods
use SymfonyComponentHttpKernelExceptionNotFoundHttpException
class ArticleController
{
...
public function newAction(...)
{
...
throw new NotFoundHttpException();
...
}
}

61.
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentTemplatingEngineInterface;
class ArticleController
{
function __construct(..., EngineInterface $templating) {
}
public function newAction(...)
{
...
return new Response(
$this­>
templating­>
render(
'@MyBundle:Article:new.html.twig',
array(
'form' => $form­>
createView()
)
)
);
}
}
Render the template manually

62.
Dependencies are explicit now
Also: no mention of a “bundle”
anywhere!
use SymfonyComponentHttpFoundationRequest;
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentTemplatingEngineInterface;
use DoctrineORMEntityManager;

63.
Dependency overflow
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentTemplatingEngineInterface;
class ArticleController
{
function __construct(
EntityManager $entityManager,
EngineInterface $templating,
TranslatorInterface $translator,
ValidatorInterface $validator,
Swift_Mailer $mailer,
RouterInterface $router
) {
...
}
...
}

64.
The cause?
Convention

65.
One controller, many actions
one action!

66.
__invoke()
namespace MyLibraryControllerArticle;
class New
{
function __construct(...)
{
// only what's necessary for this “action”
}
public function __invoke(...)
{
...
}
}

67.
Nice!
└─Controller
└─Article
├─New.php
├─Edit.php
├─Archive.php
└─Delete.php

68.
TODO
✔ Set up routing
✔ Create a service and provide the
right arguments

69.
Bundle stuff: services.xml
<!­­in
MyBundle/Resources/config/services.xml →
<?xml version="1.0" ?>
<container>
<services>
<service id="new_article_controller"
class="MyBundleControllerArticleNew">
<argument type="service"
id="doctrine.orm.default_entity_manager" />
<argument type="service" id="templating" />
</service>
</services>
</container>

70.
Bundle stuff: routing.xml
<!­­in
MyBundle/Resources/config/routing.xml →
<?xml version="1.0" encoding="UTF­8"
?>
<routes>
<route id="new_article"
path="/article/new">
<default key="_controller">
new_article_controller:__invoke
</default>
</route>
</routes>
Pull request by Kevin Bond allows you to leave out the “:__invoke” part!

71.
Controller – Achievements
● Can be anywhere
● No need to follow naming conventions
(“*Controller”, “*action”)
● Dependency injection, no service location
● Reusable in any application using
HttpFoundation

72.
Next up: Entities

73.
namespace MyBundleEntity;
use DoctrineORMMapping as ORM;
class Article
{
...
/**
* @ORMColumn(type=”string”)
*/
private $title;
}
Entity conventions

74.
What's wrong with annotations?
namespace MyBundleEntity;
use DoctrineORMMapping as ORM;
class Article
{
...
/**
* @ORMColumn(type=”string”)
*/
private $title;
}

75.
Annotations are classes

76.
use DoctrineCommonAnnotationsAnnotationReader;
$reader = new AnnotationReader();
$class = new ReflectionClass('Article');
$reader­>
getClassAnnotations($class);
BANG
Class
DoctrineORMMappingColumn
not found

77.
Well, uhm, yes, but...

78.
Are you ever going to use
anything else than Doctrine ORM?

79.
Well...
Think about Doctrine MongoDB ODM,
Doctrine CouchDB ODM, etc.
namespace MyBundleEntity;
use DoctrineORMMapping as ORM;
use DoctrineODMMongoDBMappingAnnotations as MongoDB;
use DoctrineODMCouchDBMappingAnnotations as CoucheDB;
class Article
{
/**
* @ORMColumn
* @MognoDBField
* @CoucheDBField
*/
private $title;
}

80.
TODO
✔ Remove annotations
✔ Find another way to map the data

81.
namespace MyBundleEntity;
class Article
{
private $id;
private $title;
}
Nice and clean
A true POPO, the ideal of the data
mapper pattern

82.
Use XML for mapping metadata
<doctrine­mapping>
<entity name=”MyBundleEntityArticle”>
<id name="id" type="integer" column="id">
<generator strategy="AUTO"/>
</id>
<field name=”title” type=”string”>
</entity>
</doctrine­mapping>

83.
Conventions for XML metadata
● For MyBundleEntityArticle
● Put XML here:
@MyBundle/Resources/config/doctrine/
Article.orm.xml

84.
We don't want it in the bundle!
There's a nice little trick

85.
You need DoctrineBundle >=1.2
{
"require": {
...,
"doctrine/doctrine­bundle":
"~1.2@dev"
}
}

86.
use DoctrineBundleDoctrineBundleDependencyInjectionCompiler
DoctrineOrmMappingsPass;
class MyBundle extends Bundle
{
public function build(ContainerBuilder $container)
{
$container­>
addCompilerPass(
$this­>
buildMappingCompilerPass()
);
}
private function buildMappingCompilerPass()
{
$xmlPath = '%kernel.root_dir%/../src/MyLibrary/Doctrine';
$namespacePrefix = 'MyLibraryModel';
return DoctrineOrmMappingsPass::createXmlMappingDriver(
array($xmlPath => $namespacePrefix)
);
}
}

87.
Now:
● For MyLibraryModelArticle
● Put XML here:
src/MyLibrary/Doctrine/Article.orm.xml

88.
Entities - Achievements
● Entity classes can be anywhere
● Mapping metadata can be
anywhere and in different formats
● Entities are true POPOs

89.
Finally: Templates

90.
Conventions
● In /Resources/views/[Controller]
● Filename: [Action].[format].[engine]

91.
The difficulty with templates
They can have all kinds of implicit
dependencies:
● global variables, e.g. {{ app.request }}
● functions, e.g. {{ path(...) }}
● parent templates, e.g. {% extends
“::base.html.twig” %}

92.
Still, we want them out!
And it's possible

93.
Documentation » The Cookbook » Templating »
How to use and Register namespaced Twig Paths
# in config.yml
twig:
...
paths:
Twig namespaces
"%kernel.root_dir%/../src/MyLibrary/Views": MyLibrary
// in the controller
return $this­>
templating­>
render('@MyLibrary/Template.html.twig');

94.
Get rid of absolute paths
Using Puli, created by Bernhard
Schüssek (Symfony Forms,
Validation)

95.
What Puli does
Find the absolute paths of
resources in a project

96.
use WebmozartPuliRepositoryResourceRepository;
$repo = new ResourceRepository();
$repo­>
add('/my­library/
views', '/absolute/path/to/views/*');
/my-library/views /index.html.twig
/absolute/path/to/views /index.html.twig
echo $repo
­>
get('/my­library/
views/index.html.twig')
­>
getRealPath();
// => /absolute/path/to/views/index.html.twig

97.
Register “prefixes”
Manually, or using the
Puli Composer plugin
// in the composer.json file of a package or project
{
"extra": {
"resources": {
"/my­library/
views": "src/MyLibrary/Views"
}
}
}

98.
Twig templates
// in composer.json
{
"extra": {
"resources": {
"/my­library/
views": "src/MyLibrary/Views"
}
}
}
Puli Twig extension
// in the controller
return $this­>
templating
­>
render('/my­library/
views/index.html.twig');

99.
Many possibilities
● Templates
● Translation files
●Mapping metadata
● Service definitions
● And so on!

100.
The future is bright
● Puli is not stable yet
● But I expect much from it:

101.
Puli will be the ultimate tool

102.
to create NAKED BUNDLES

103.
and to enable reuse of
many kinds of resources

104.
not limited by
project,
framework,
even language
boundaries!

105.
But even without Puli
There's a whole lot you can do to make your code
not rely on the framework

106.
Remember
The framework is for you
Your code doesn't need it

107.
Questions?

108.
Buy it for $ 17,50
http://leanpub.com/a-year-with-symfony/c/symfony-usergroup-belgium

109.
Get a $10,00 introduction discount:
http://leanpub.com/principles-of-php-package-design
/c/symfony-usergroup-belgium

110.
Thank you
Feedback: meetup.com
Talk to me: @matthiasnoback

111.
Images
Sally MacKenzie:
www.amazon.com