Rewrote Extension & Configuration docs #3894
Conversation
| @@ -445,6 +447,8 @@ a second argument:: | |||
| ->fixXmlConfig('child', 'children') | |||
| ->children() | |||
| ->arrayNode('children') | |||
| // ... | |||
| ->end() | |||
| ->end() | |||
| ; | |||
There was a problem hiding this comment.
What do you think about moving the semicolon to the line above?
There was a problem hiding this comment.
i think the place is right imo. It helps the reader's brain to start where it left. Things like this make sense imo more than what the standard says, but oh well.
|
good job @wouterj I will now stop and cook you again when i get a chance. These simplifications and tips are a great addition! |
| single: Configuration; Semantic | ||
| single: Bundle; Extension configuration | ||
|
|
||
| How to Expose Semantic Configuration for a Bundle |
There was a problem hiding this comment.
Should be "How to Expose a Semantic Configuration" or "How to Expose Semantic Configurations".
There was a problem hiding this comment.
What about...
How to Create Friendly (Semantic) Configuration for your Bundle
There was a problem hiding this comment.
👍 let's remove those non-basic english words from the docs :)
| single: Configuration; Semantic | ||
| single: Bundle; Extension configuration | ||
|
|
||
| How to Create Friendly Configuration for a Bundle |
There was a problem hiding this comment.
You can say "very friendly", so friendly is not a closed-class word
There was a problem hiding this comment.
Are you sure? To me, very friendly are two words and is not a modification of friendly.
There was a problem hiding this comment.
"very" is an adverb that says something about the "friendly" abverb. So the "friendly" word is extended using "very". If a word can be extended, it isn't closed-class.
I may be wrong, let's see what @weaverryan thinks
There was a problem hiding this comment.
Yeah, I'm curious what @weaverryan thinks about this.
There was a problem hiding this comment.
Haha, you guys are great. This is so technical, that I'm no more qualified than you guys are here - I'm also just reading on the web :). @wouterj's description makes sense to me.
| -------------- | ||
|
|
||
| Symfony allows people to provide the configuration in three different formats: | ||
| Yaml, XML and PHP. Yaml and PHP both use the same syntax and are supported by |
|
i just got seriously bitten by this information being out of date. Anything small i can do to get this merged? |
|
@jrobeson exactly what you did now: Making me aware that I need to do some things. Oh, and creating a time machine for @weaverryan so he has some time to review this. |
|
thanks @wouterj! specifically i got bit by the part about using getConfigurationExtension() vs the old way $container->registerExtension() |
| make use of :ref:`parameters <book-service-container-parameters>`, then | ||
| you still have the flexibility to customize your bundle from your application | ||
| configuration. See ":ref:`service-container-imports-directive`" for more | ||
| details. |
There was a problem hiding this comment.
I like what we're saying here, but I'm not sure its as clear as I want. I basically want to say (not word-for-word, just an idea):
Unless you're building a bundle you plan to release open source of share between projects, don't follow this guide. Just create services in
services.ymland be done.
If we talk parameters, I want to keep it short, so that we don't cloud this message:
If you do want to be able to configure something from within
config.yml, you can always create a parameter there and then use it somewhere else.
There was a problem hiding this comment.
I get what I mean, I reduced it quite a lot now.
|
just had to explain this issue to another person. Is there anything i can do to help with this? |
|
Thanks for the great work Wouter and sorry for my slow merge! |
This PR was merged into the 2.3 branch. Discussion ---------- Rewrote Extension & Configuration docs The "How to expose semantic configuration for a bundle" article always was a bit of a mess. It tried to explain how to use Extension classes to load service definitions and how to provide configuration options for a bundle. At the same time it showed 2 ways to achieve this goal: a simple way and the official way. This resulted in an article that wasn't easy to follow and did not really learn anything about Extensions and Configurations. So I decided to rewrite the complete article into 2 seperate articles: One about the Extension and one about the Configuration. While I was doing that, I discovered it was time that we rewrote this thing. Most of the article was written in Feb 2011 and was outdated now. I've also added a section about XML configuration. This is a first sketch, I haven't checked my english/grammar/typos, but it's ready to catch the first comments! | Q | A | --- | --- | Doc fix? | yes | New docs? | yes | Applies to | 2.3+ | Fixed tickets | - Side-note: I have discussed with myself to move the article to the components docs, because most of it doesn't rely on the Symfony framework. However, since the conventions do, I decided to keep it in the cookbook to make it easier to follow. Commits ------- c9fe05b Rewrote Extension & Configuration docs
The "How to expose semantic configuration for a bundle" article always was a bit of a mess. It tried to explain how to use Extension classes to load service definitions and how to provide configuration options for a bundle. At the same time it showed 2 ways to achieve this goal: a simple way and the official way. This resulted in an article that wasn't easy to follow and did not really learn anything about Extensions and Configurations.
So I decided to rewrite the complete article into 2 seperate articles: One about the Extension and one about the Configuration.
While I was doing that, I discovered it was time that we rewrote this thing. Most of the article was written in Feb 2011 and was outdated now.
I've also added a section about XML configuration.
This is a first sketch, I haven't checked my english/grammar/typos, but it's ready to catch the first comments!
Side-note: I have discussed with myself to move the article to the components docs, because most of it doesn't rely on the Symfony framework. However, since the conventions do, I decided to keep it in the cookbook to make it easier to follow.