Inconsistent recommendations about Semantic Configurations

[ChristopherMoll]

The cookbook page on extensions recommends avoiding semantic configuration if it's not needed:

When you create a bundle, you have two choices on how to handle configuration:

Normal Service Configuration (easy):
...

Exposing Semantic Configuration (advanced):
...

The second option - which you'll learn about in this article - is much more flexible, but also requires more time to setup. If you're wondering which method you should use, it's probably a good idea to start with method #1, and then change to #2 later if you need to.

On the other hand, the cookbook page on bundle best practices recommends using semantic configuration even in simpler applications:

To provide more flexibility, a bundle can provide configurable settings by using the Symfony2 built-in mechanisms.
For simple configuration settings, rely on the default parameters entry of the Symfony2 configuration. Symfony2 parameters are simple key/value pairs; a value being any valid PHP value. Each parameter name should start with the bundle alias, though this is just a best-practice suggestion. The rest of the parameter name will use a period (.) to separate different parts (e.g. acme_hello.email.from).
The end user can provide values in any configuration file:

# app/config/config.yml
parameters:
    acme_hello.email.from: [email protected]

Retrieve the configuration parameters in your code from the container:

$container->getParameter('acme_hello.email.from');

Even if this mechanism is simple enough, you are highly encouraged to use the semantic configuration described in the cookbook.

[stof]

For a shared bundle, the good way to go is to use the semantic configuration:

• it allows validating the config
• it allows providing default values
• it can be used for other things than setting parameters (defining some service aliases, loading some config file conditionally...)
• it decouples the config from the place where it is used (making it easier to provide BC in the config)
• it documents the available configuration

[ChristopherMoll]

I agree with you, but don't you think the docs should be consistent about it?

[stof]

I would simply suggest to change the sentence in the first page to

it's probably a good idea to start with method #1, and then change to #2 later if you need to or if you want to share your bundle.

Starting without a semantic configuration is indeed fine for application specific bundles most of the time, and it is indeed easier to implement