What is Best Practice Bundle?

This is a simple bundle to show different best practices for Symfony Bundles development. This bundle could as well be named starter-bundle, empty-bundle or boilerplate-bundle. The master-branch follows the future Symfony 2.1 release (upgrade notes).

Use the bundle as a reference (or cheatsheet) for your own bundles. Also look at the documentation and comments in the source if you forgot how to do something.

Of course you can use this bundle as a "Boilerplate" or empty/starter bundle if you plan to build your own bundle. Fork or clone this bundle if you wish. Please search knpBundles.com before you build a new bundle. See if something simimlar is already out there.

This bundle contains

the directory tree structure advised by Symfony
follows the coding standards
has documentation examples based on reStructuredText
uses Twig for templating
comes with unittests (including Functional tests)
uses Composer for dependancy management
uses Travis CI as a build bot for continuous integration
is hosted on Github (with Service Hooks)
a customized .gitignore file

Bugs and Roadmap

Before providing bug-reports please the current issues and forum first. The roadmap for the future of this bundle is described below.

Future features and documentation

Help appreciated, see enhancements under issues). Please +1 the enhancements you are interested in.

use the PHP-CS-Fixer
make /best-practice/ available for the functional test
clone the bundle via command as an alternative to generate:bundle
multiple languages / locale / i18n examples
provide tutorials / blog-posts (yaml, caching with Varnish, Vagrant etc.)
more info on cache management
more logging (via monolog)
more information on routing/paths, assetic and forms
custom exceptions
add edge side include (esi), session, validator and redirect tests
add mime-type tests like xml and json tests
Object-relational mapping (ORM): Propel/Doctrine entity integration?
html5 boilerplate?

Requirements

Symfony2.1 (PHP 5.3.3 and up including Composer)
Twig

Installation

Add the following line to your composer.json file.

//composer.json
{
    //...

    "require": {
        //...
        "LilaConcepts/LilaConceptsBestPracticeBundle" : "dev-master"
    }

    //...
}

If you haven't allready done so, get Composer (make sure it's up-to-date).

curl -s http://getcomposer.org/installer | php

And install the new bundle

php composer.phar update LilaConcepts/LilaConceptsBestPracticeBundle

Configure

The final step is to add the bundle to your AppKernel.php.

<?php

    // in AppKernel::registerBundles()
    $bundles = array(
        // Dependencies
        new Symfony\Bundle\FrameworkBundle\FrameworkBundle(),
        new Symfony\Bundle\TwigBundle\TwigBundle(),
    );
    
    // Optionally place it in the dev and test-environments only
    if (in_array($this->getEnvironment(), array('dev', 'test'))) {
        // ...
        $bundles[] = new LilaConcepts\Bundle\LilaConceptsBestPracticeBundle\LilaConceptsBestPracticeBundle()
    }

Unittest the bundle

You can now unittest the module, just type:

phpunit

Point your browser to http://localhost/app_dev.php/best-practice/ (under development, does not work yet!)

Standalone Installation

If you want to download and unittest the code, you don't need a working Symfony project. Just run the following.

git clone https://github.com/LilaConcepts/LilaConceptsBestPracticeBundle.git
cd LilaConceptsBestPracticeBundle
curl -s http://getcomposer.org/installer | php
php composer.phar install
phpunit

Fork/clone the Bundle for your own use

Click the Fork button on https://github.com/LilaConcepts/LilaConceptsBestPracticeBundle. Then click on Admin and rename the bundle. Please stick with the naming conventions and use something like 'myfeature-bundle' or 'myadmin-bundle'. You are ready with the github part, it's time to clone the respository into a temporary folder and make some changes. Set your own Github URL and Bundle/Company name.

mkdir temp/ && cd temp/
BUNDLE=MainBundle
COMPANY=Acme
GITHUBURL=https://github.com/[your account name]/[your bundle name]-bundle.git

Now run the following code:

SHORTBUNDLE=`echo ${BUNDLE} | sed 's/Bundle//'`
COMPLETENAME=${COMPANY}${SHORTBUNDLE}
LOGICALNAME=`echo ${COMPANY}_${SHORTBUNDLE} | tr '[A-Z]' '[a-z]'`
DIRNAME=`echo ${SHORTBUNDLE} | tr '[A-Z]' '[a-z]'`-bundle

git clone ${GITHUBURL} ${BUNDLE}
cd ${BUNDLE}

FILES=`find . -regex '.*/*.[php|yml]' -type f`
sed -i '' -e 's/LilaConcepts\\Bundle\\LilaConceptsBestPracticeBundle/'${COMPANY}'\\Bundle\\'${COMPANY}${BUNDLE}'/g' ${FILES}
sed -i '' -e 's/lilaconcepts_bestpractice/'${LOGICALNAME}'/g' ${FILES}
sed -i '' -e 's/LilaConceptsBestPracticeExtension/'${COMPLETENAME}Extension'/g' ${FILES}
sed -i '' -e 's/LilaConceptsBestPracticeBundle/'${COMPLETENAME}Bundle'/g' ${FILES} composer.json
sed -i '' -e 's/LilaConcepts/'${COMPANY}'/g' composer.json

mv ./DependencyInjection/LilaConceptsBestPracticeExtension.php ./DependencyInjection/${COMPLETENAME}Extension.php
mv ./LilaConceptsBestPracticeBundle.php ./${COMPLETENAME}Bundle.php

echo -e "\n\nDone, please inspect the changes and push it back to github:\n\n    git push\n\nYou will need this later for your AppKernel.php:\n\n    new ${COMPANY}\Bundle\\${BUNDLE}\\${COMPANY}${BUNDLE}()\n"

Optionally:

curl -s http://getcomposer.org/installer | php
php composer.phar install
phpunit

Be sure to update the following files before pushing it back to Github:

composer.json
README.md
LICENCE
CONTRIBUTORS.md
CHANGELOG's
Resource/doc/*

Push it back to Github:

git add .
git commit -a -m "Initial checkin"
git push

Head over to Packagist and submit your Bundle. Optional: setup a Github Service Hook so packagist will be informed automatically.

Now install your bundle following these instructions with your own packagist name of course. You can remove the temp/ directory we created and work inside the vendor/.../Bundle/YourBundle directory.

Documentation

For more information see Resources/doc/index.rst. Feel free to fix typo's.

Contributing

First of all, many thanks to all the contributors and people who inspired us. If you like to help making Best Practice Bundle better, or if you see anything that's wrong, send me a personal message or provide a bug report under issues. Even better if you could send a pull-request. If you have any further questions please head over to the forum.

Licence

This bundle is released under the MIT Licence by Lila Concepts B.V., see the LICENCE-file for more information. Lila Concepts B.V. is a dutch organisation and the creator of Aandelen Kopen and Beleggen voor Beginners amongst other sites.

keesschepers / LilaConceptsBestPracticeBundle