What is a Bundle?

• Bundles are first class citizens
• As a matter of fact the Symfony2 framework is a Bundle too!
• The minimal glue code to integrate a library with Symfony2 and/or a set of Controllers/CLI Commands

What can Bundle do?

• A Bundle can provide Controllers
• A Bundle can provide Commands
• A Bundle can provide entities/documents
• A Bundle can provide services
• A Bundle can provide assets (js, css, images)

Where do I find Bundles?

• Unofficial Bundle index: knpbundles.com
• Automatically indexes code that looks like a Bundle
• Generates a point value based on some simple metrics
  • 1 point for each followers on GitHub.
  • 5 points if your README is more than 300 chars.
  • 5 points if you use Travis CI.
  • 5 more points if your Travis build status is actually ok ;)
  • 5 points if you provide a composer package.
  • 5 points per person recommending the bundle on KnpBundles.
  • Small boost for bundles with commits in the past 30 days.

knpbundles.com

PLEASE PLEASE PLEASE check knpbundles.com before you write a new Bundle!

Directory Structure

cookbook/bundles/best_practices.html

Semantic configuration

• Prefix all services with the Bundle alias, ie. AcmeMyExtension::getAlias()
• Explicitly handle any configurable parameters
• Define a Configuration class for the semantic configuration
• Use compiler passes to interact with other Bundles services

cookbook/bundles/extension.html

DIC extension class

use Symfony\C..\D..I..\ContainerBuilder as CB;
use Symfony\C..\Config\FileLocator;
use Symfony\C..\HttpKernel\D..I..\Extension;
use Symfony\..\D..I..\Loader\XmlFileLoader;

class AcmeMyExtension extends Extension
{
    public function load(array $configs, CB $dic)
    {
        $configuration = new Configuration();
        $config = $this->processConfiguration(
            $configuration, $configs
        );

        $dir = __DIR__ . '/../Resources/config';
        $locator = new FileLocator($dir);
        $loader = new XmlFileLoader($dic, $locator);
        $loader->load('services.xml');

        foreach ($config as $key => $val) {
            $dic->setParameter('acme_my.'.$key, $val);
        }
    }
}

DIC configuration class

use Symfony\C..\Config\Definition as Def;

class Configuration implements Def\ConfigurationInterface
{
    public function getConfigTreeBuilder()
    {
        $treeBuilder = new Def\Builder\TreeBuilder();

        $treeBuilder->root('acme_my')
        ->children()
            ->scalarNode('host')
                ->isRequired()->cannotBeEmpty()->end()
            ->scalarNode('port')
                ->defaultValue(2000)->end()
            ->scalarNode('timeout')
                ->defaultValue(30000)->end()
        ->end()
        ;

        return $treeBuilder;
    }
}

Composer

• Default dependency management as of Symfony 2.1
• Bundles should be registered onPackagist
• Use Satis or Totan Proxy to create your own composer index
• Alternatively use repositories directive to make composer aware of specific (closed source) repositories
• If you use github make sure to enable the "Packagist" commit hook

getcomposer.org

Composer.json example

{
    "name": "acme/my-bundle",
    "type": "symfony-bundle",
    "description": "This Bundle is an example",
    "license": "MIT",
    "authors": [
        {
            "name": "Duffy Duck",
            "email": "diffy@acme.com"
        }
    ],
    "require": {
        "php":                      ">=5.3.3",
        "symfony/framework-bundle": "~2.3",
    },
    "autoload": {
        "psr-4": { "Acme\\MyBundle": "" }
    },
    "extra": {
        "branch-alias": {
            "dev-master": "1.1-dev"
        }
    }
}

Composer

• Default dependency management as of Symfony 2.1
• Bundles should be registered onPackagist
• Use Satis or Totan Proxy to create your own composer index
• Alternatively use repositories directive to make composer aware of specific (closed source) repositories
• If you use github make sure to enable the "Packagist" commit hook

getcomposer.org

Testing

• JMSCommandBundle generates Kernels for functional tests
• Alternatively use the CMF Testing component
• Functional tests are a very quick way to catch BC breaks

• Unit tests are for libs, which should not be part of Bundles
• Matthias has created a libs to unit tests Configuration classes

Functional Testing

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class HomepageTest extends WebTestCase
{
    public function testContents()
    {
        $client = $this->createClient();
        $crawler = $client->request('GET', '/');
        $s = $client->getResponse()->getStatusCode();
        $this->assertEquals(200, $s);

        $crawler->filter('h1:contains(Homepage)');
        $this->assertCount(1, $count);
        $crawler->filter('ul.menu_main li')
        $this->assertCount(13, $count);
    }
}

Travis-CI

• Just create a ".travis.yml" file
• Enable github hook to run tests automatically
• Test against multiple DBs and PHP/library versions
• Enables contributors to easily also run the tests

Travis-CI .travis.yml

language: php

php: [ 5.4, 5.5, 5.6, hhvm]

env: [ SYMFONY_VERSION=2.5.* ]

matrix:
    include:
    - php: 5.5
      env: SYMFONY_VERSION=2.3.*
    - php: 5.5
      env: SYMFONY_VERSION=2.6.*

before_script:
    - composer require symfony/symfony:${SYMFONY_VERSION} --prefer-source

script: phpunit --coverage-text

Overriding templates/controllers

• Use the app Resource dir for template override only:
  app/Resources/FOSUserBundle/views/Security/login.html.twig
• Create a child bundle when also overriding controllers:
  src/Acme/MyBundle/Resources/views/Security/login.html.twig
src/Acme/MyBundle/Controller/SecurityController.php

Child Bundle

use Symfony\Component\HttpKernel\Bundle\Bundle;

class MyBundle extends Bundle
{
public function getParent()
{
return 'FOSUserBundle';
}
}

How to fix a typo

• Setup a Github account
• To fix a typo browse to the file and click edit
• Github will then fork the repository and create a pull request for you all in one single step

How to fix a bug

• Setup a Github account
• Branch, commit, fork, change your remote, push, open PR
• Remember to follow the Symfony2 coding guide

Temporary patch a composer package

• For example patching the 1.2.0 release of SomeSuperBundle
• Fork into your own github account ("mygithub")
• Apply the patch into a new branch ("add-rocknroll")
• Push the branch to your fork
• Open a PR but in the mean time already use the patch

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/mygithub/SomeSuperBundle"
        }
    ],
    "require" : {
        "php": ">=5.3.3",
        "symfony/symfony": "~2.3",
        "some/super-bundle": "dev-add-rocknroll as 1.2.0"
    }
}

composer docs

Evaluation check list

• Search knpbundles.com
• Check the license
• Check the README.md / documentation
• Check the Bundle structure
• Check Tests and travis-ci integration
• Check the code
• Try it out ..

FOSUserBundle

• Provides user management for your project
• Integrates with SecurityBundle
• Controllers for registration, password resetting...
• Supports Doctrine ORM, MongoDB ODM, CouchDB ODM, Propel ... and add your own storage layer

JMSSecurityExtraBundle

• Extra features on top of the Security component
• Annotation-based security checks
• Expression-based permissions

JMSSecurityExtraBundle

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Response;

class MyController extends Controller
{
    /**
     * Get the list of articles
     *
     * @return array data
     *
     * @Secure(roles="ROLE_ADMIN")
     */
    public function getArticlesAction()
    {
        /*
        $security = $this->get('security.context');
        if ($security->isGranted('ROLE_ADMIN')) {
            throw new AccessDeniedException();
        }
        */

        $data = json_encode(array('bim', 'bam', 'bingo'));
        return new Response($data);
    }
}

JMSSerializerBundle

• Expands on the core Serializer
• Implements visitor pattern to give more flexibility
• More flexible handling to return different structures for JSON and XML
• Most effective when (de)serializing from/to Object Graphs
• Additional features like versioning, group based serialization rule sets etc.

JMSSerializerBundle

use JMS\SerializerBundle\Annotation as Serializer;
use JMS\SerializerBundle\Annotation\XmlList;

use Doctrine\Common\Collections\Collection;

/**
 * @Serializer\XmlRoot("response")
 */
class ArticleResponse
{
    /**
     * @var Collection
     * @XmlList(inline = true, entry = "article")
     */
    protected $articles;

    protected $page;

    public function __construct(Collection $a, $page)
    {
        $this->articles = $a;
        $this->page = $page;
    }
}

FOSRestBundle

• Provides a set of services and listeners to help in building REST APIs
• View layer using JMSSerializerBundle to support HTML, XML, JSON from a single Controller action
• Automatic generation of routes from Controller actions
• Accept header negotiation
• Request body decoding
• GET parameter parsing and validation

FOSRestBundle

use Acme\MyBundle\ArticleResponse;

class RestController
{
  /**
     * Get the list of articles
     * route name: liip_hello_rest_get_articles
     * pattern: /liip/hello/rest/articles.{_format}
     * http method requirement: GET
     *
     * @param string $page page number
     * @return array data
     *
     * @View()
     * @QueryParam(name="page",
     *             requirements="\d+",
     *             default="1")
     * @ApiDoc()
     */
    public function getArticlesAction($page)
    {
        $articles = array('bim', 'bam', 'bingo');

        return new ArticleResponse($articles, $page);
    }
}

FOSRestBundle

<html>
    <body>
        <div>
            <div>bim</div>
            <div>bam</div>
            <div>bingo</div>
        </div>
        <div>page: 2</div>
    </body>
</html>

<response>
    <article>bim</article>
    <article>bam</article>
    <article>bingo</article>
    <page>2</page>
</response>

{
  "articles": [
    "bim",
    "bam",
    "bingo"
  ],
  "page": "2"
}

NelmioApiDocBundle

• Generates REST API documentation based on routing data
• Integrated with FOSRestBundle and JMSSerializerBundle
• Provides a sandbox to try out REST API calls inside the UI

StofDoctrineExtensionBundle

• Configures the Gedmo behavioral extensions
• Timestampable, translatable, sluggable, tree...

use Doctrine\ORM\Mapping as ORM;
use Gedmo\Mapping\Annotation as Gedmo;

/** @ORM\Entity() */
class Post
{
    /**
     * @ORM\Column(type="datetime")
     * @Gedmo\Timestampable(on="create")
     */
    protected $createdAt;

    /**
     * @ORM\Column(type="datetime")
     * @Gedmo\Timestampable(on="update")
     */
    protected $updatedAt;
}

KnpMenuBundle

• Build your menus in an object-oriented way
• Menu represented as a tree of objects

• Renders the menu with several renderers:

  • "standard" menu
  • breadcrumb
  • ...

• Pluggable data providers

LiipImagineBundle

• Integration with the imagine image manipulation library
• Define filter groups to dynamically apply to images
• Automatically defines routes for each filter groups
• Optional pluggable caching
• Define custom loaders (filesystem, database etc.)

LiipImagineBundle

{% extends "LiipHelloBundle::layout.html.twig" %}

{% block content %}

<div>
  original:<br>
  <img src="{{ '/bundles/hello/images/test.jpg' }}"/>
</div>

<div>
  LiipImagineBundle in action:<br>
  <img src="{{ '/bundles/hello/images/test.png'
    | imagine_filter('my_thumb') }}"/>
</div>

<div>
  LiipImagineBundle in action:<br>
  <img src="{{ '/bundles/hello/images/test.png'
    | imagine_filter('my_thumb', true) }}"/>
</div>

{% endblock content %}

Github projects

• FOSUserBundle
• JMSSecurityExtraBundle
• JMSSerializerBundle
• FOSRestBundle
• NelmioApiDocBundle
• StofDoctrineExtensionBundle
• KnpMenuBundle
• LiipImagineBundle

Resources

• Standard Edition bundles
• Bundle cookbooks
• #symfony IRC
• http://knpbundles.com
• FOS github organization