So if any of you experience a similar issue, check if the extension is present and loaded. On openSUSE systems it’s enough to install the php5-posix package. Looks like the package maintainers start to leave out stuff that hardly anyone uses anymore, which is basically a good thing. It just caught me on the wrong foot

I filed a ticket to include this in the symfony installation documentation because i couldn’t find it mentioned anywhere.

What was not so good

Altogether I liked most talks, even the infamous Microsoft one, because each single talk provided knowledge I didn’t have before. There are some general issues I want to address though:

• Some speakers had a really bad French accent. I’m glad my English was good enough so I was able to follow all of them nevertheless, but for some listeners it must have been really hard.
• Please please please provide portable headset microphones at future conferences. Speakers having to hold a microphone in their hands just look awkward, and it limits their freedom of movement and gestures. I mean, it’s not like headset mikes were ultra-future technology… This would also fix the “speaker A is much louder than speaker B because he holds the microphone too close” issue.
• The Wi-Fi connection was really bad on the first day, but it was acceptable on the second. Looks like someone didn’t realize on time that there’d be hundreds of nerds with laptops present.
• Please provide some way to get cola at future conferences, caffeine addicts will thank you for this, especially through the afternoon sessions
• The only speaker I really disliked was the second guy from the Microsoft team. If I want to be shouted at like that, I’ll visit a boot camp and insult some drill instructor, not attend a software conference!

As said above the content of the talks was fine, although there were ups and downs of course. What was much more annoying was that some speakers seemingly didn’t know much about presenting stuff. This is of course acceptable for hacking nerds in general, but only until they have to speak at conferences. Please, guys, read some books about presentation techniques in advance before giving your next speech!

What was great

Let’s stop talking about failures and continue with things that require mentioning because they were great.

• The overall organization was cool and professional. If there were any troubles behind the scenes they were kept hidden from the audience, which is fine.
• The food was good.
• The twitter visualization on the big screen was a really cool thing to do.
• The selection of talks was OK. It addressed both symfony newcomers and experienced listeners.
• The truly outstanding speakers worth mentioning were in my opinion (in order of schedule):
  • John Cleveley: this talk set the bar for the first day. Clearly audible, great presentation, interesting content!
  • Jonathan Wage: obviously an experienced speaker too, with lots of detailed knowledge
  • Stefan Koopmanschap: although the session didn’t provide much new information for me it was nice to listen to. He knows how to handle crowds.
  • Lukas Kahwe Smith: unlike his companion (don’t remember the name) he was cool, professional and easy to understand.
  • Scott Chacon: that’s what a presentation has to be like. Just like that. The reference for the second day, which was altogether definitely better than the first one.
  • Fabien Potencier: Fabien knows how to savor his fame in situations like this and he has every right to do so! What he does and how he convinces people to follow his lead is just outstanding. Standing ovations for one of the most inspiring web developers nowadays!

Symfony Live 2010 was a huge gain for myself. I met lots of interesting people and collected tons of first-hand information. Since it was the first (but definitely not the last) symfony or PHP conference I attended, future events will show how it compares.

Symfony 2 and the future

Symfony 2 will be awesome. I also checked out the brand-new Symfony 2 web page, which I recommend to everyone who is interested in PHP applications or frameworks.

It looks like phpBB 4 will be built upon Symfony 2, which I personally really appreciate because phpBB was my stepladder into PHP development and the open source community around 2001. After switching to PHP5 and OOP style programming I started to disapprove of the phpBB development style. Hopefully there will be a turn around towards more best practices in the future!

Before I forget it… the user stories

On the first day Stefan Koopmanschap announced that symfony needs more people writing success stories helping others arguing in favor of symfony. Every publishable story provided until the end of the second day would win a set of symfony books. I couldn’t resist this offer and sat through the late evening in my hotel room hurting my fingers by typing on my netbook keyboard for 4 full hours. Since I had filed similar content as my speaker’s submission (which was unfortunately rejected) I knew there was enough interesting stuff to write about. It was worth the effort: I got 3 symfony books. Thanks to the symfony team!

I don’t know when my story will be published, but I’ll link it as soon as it is. The title is “Running a TV station with symfony”.

Last but not least

Toni, I really would have liked meeting you, but it seems we just weren’t able to find each other. Let’s hope it will work next time

<off-topic> why is my Wordpress editor so damn slow recently? </off-topic>

Update 2010-03-17: Running a TV station with symfony was published on the symfony blog today.

I’ve nominated symfony in 3 categories:

• Best Tool or Utility for Developers
• Best Project
• Best Commercial Open Source Project

Click the picture to nominate symfony too! Of course don’t forget to read and follow the nomination rules to allow for a fair voting process!

Have fun!

If you happen to be in Vienna at the time we’re looking forward to your visit!

Have fun!

• Field grouping
• Field formatters
• Required marks
• Separators
• Submit buttons
• Help texts
• I18n for everything

In my current symfony project at work I’m using at least 9 different forms, tendency rising. There are lots of things that would help making most of them easier to use.

Field grouping

The W3C HTML specification provides a clean solution to grouping form fields: fieldset and legend elements. Symfony doesn’t support them by now, but I think they are crucial, since lots of people use them and they are quite easy to define.
Looking at Bernhard’s code sample let’s suppose we want to group the username and email fields and then the password fields:

  public function configure()
  {
    $this->addGroup('user_stuff', 'Personal information');
 
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));
 
    $this->addField('email')
         ->setValidator(new sfValidatorEmail());
 
    $this->addGroup('password_stuff', 'Password information');
 
    $this->addField('password', new PasswordField());
 
    $this->addField('password_again')
         ->setWidget(new sfWidgetPassword())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)');
  }

In my imagination this should render like this:

<fieldset id="user_stuff">
  <legend>Personal information</legend>
  <!-- The name and email form fields go here -->
</fieldset>
 
<fieldset id="password_stuff">
  <legend>Password information</legend>
  <!-- The password form fields go here -->
</fieldset>

The magic would be that “addGroup($name, $legendText)” would automatically close a previous group and add all further fields to the current group fieldset. To close a group manually and add the following fields to the global scope a closeGroup() method would be enough.
The grouping HTML code would be defined in the form’s formatter, which can be enhanced easily:

class sfWidgetFormSchemaFormatterList extends sfWidgetFormSchemaFormatter
{
  protected
    // other stuff
    $groupFormat = "<fieldset>\n  <legend>%legend%</legend>\n  %content%</fieldset>";
}

And what if we add a form field later on that belongs to a previous group? Nothing easier than that!

    $this->addFieldToGroup('surname', 'user_stuff');

At the end of the article you’ll see why I think it would be useful to have this in the form definition.

Field formatters

Besides the grouping my forms share one more thing: not all the fields are rendered the same way. Some of them require parameters to the label tag or just completely different row stylings. The solution to this at the moment: I have to generate the row myself. The drawback: I’m usually too lazy to include stuff like error rendering and if I change the formatter one day I have to manually alter all the custom form field rows. There’s only one summary for this: it sucks!
Why not enable custom formatters per row? There’s not even a need to define something new, we can re-use the existing formatter code!

  public function configure()
  {
//  This is how formatters are defined now:
//  $this->widgetSchema->setFormFormatterName('List');
 
//  Make it more intuitive in the first place:
    $this->setFormatterName('List');
 
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));
 
    $this->addField('email')
         ->setValidator(new sfValidatorEmail());
 
    $this->addField('password', new PasswordField())
         // here it comes!
         ->setFormatterName('customPasswordFormat');
 
    $this->addField('password_again')
         ->setWidget(new sfWidgetPassword())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)')
         // and here!
         ->setFormatterName('customPasswordFormat');
  }

The only thing that changes here is that the 2 password fields would be formatted using another formatter. Everything else would stay the same. So simple and yet so powerful…

Required marks

There have been lots of discussions on the mailing lists how required fields should be displayed. My favourite solution would be to put this where all the other formatting stuff goes: to the formatter.

class sfWidgetFormSchemaFormatterList extends sfWidgetFormSchemaFormatter
{
  protected
    $rowFormat       = "<li>\n  %error%%label%%required%\n  %field%%help%\n%hidden_fields%</li>\n",
    // other stuff
    $requiredFormat = "<span>*</span>";
}

Combined with the ability to define custom styles per field this would be a powerful solution.
Ah, there’s something else I would like to notice: defining the required property in the validator is fine from a techie-architect-point-of-view (as are so many other form related issues). But let’s once more see it from the user’s perspective:

  public function configure()
  {
    // old way
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15, 'required' => true));
 
    // what about this?
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15))
         ->setRequired(true);

See the difference? I’d personally like to have both options, but the second one would be much more intuitive from the user’s point of view.

Separators

Update 2009-04-16: I’m not sure anymore that separators like I described them here are a good idea. I’ll keep the content unchanged for anyone to understand the discussion that followed. Keep in mind that all this is a kind of brain storming which naturally results in more storm than brain .

Separators are quite useful in templates when 2 form rows shouldn’t be too close to each other or separated visually using a horizontal line or whatever. In the template this is usually done like this:

  <?php echo $form['name']->renderRow() ?>
  <div class="separator"></div>
  <?php echo $form['email']->renderRow() ?>

Let’s extend the formatter first (you know what I’m getting at, don’t you?):

class sfWidgetFormSchemaFormatterList extends sfWidgetFormSchemaFormatter
{
  protected
    // other stuff
    $separatorFormat = '<div class="separator"></div>';
}

Now we can use it in the form code. And we can use different separators in the same form!

  public function configure()
  {
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));
 
    $this->addSeparator();
 
    $this->addField('email')
         ->setValidator(new sfValidatorEmail());
 
    $this->addSeparator()
         ->setFormatterName('anotherSeparatorFormat');
 
    $this->addField('password', new PasswordField());

Submit buttons

Submit buttons belong to the form. They are even input widgets from a technical point of view. So why not add them to the form definition?

  public function configure()
  {
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));
 
    // all the other fields 
 
    // solution 1
    $this->addField('submit')
         ->setWidget(new sfWidgetSubmit('Submit the form'))
         ->setValidator(new sfValidatorPass());
 
    // solution 2
    $this->addSubmitButton('submit', 'Submit the form');

Together with the ability to use a specific formatter for the submit widget this would make every kind of submit button possible.

Help texts

So far the only possible way to add help texts to your form is passing them to the renderRow() method like this:

  echo $form['name']->renderRow(array(), 'Label text', 'Help text');

Why is this separated from the form definition? Especially if the label is defined inside the form? Are there scenarios where the label stays the same but the help text changes? I don’t think so!
Let’s try an alternative approach:

  public function configure()
  {
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15))
         ->setLabel('Label text')
         ->setHelp('Help text');

You see that this is mixing content with structure. But since most of the forms stuff is mixing content with structure (otherwise the labels should never have been in the form definition in the first place) why not allow to do it properly? And this leads to my last point:

I18n for everything

Symfony is great. Symfony has many powerful features. Symfony supports internationalization (short i18n) for everything. Everything? Not so! The form classes strictly defy being i18ned (sic!), making you wrap labels and help texts in __() functions in the template and hoping that the users don’t mind english error messages. Is there a reason for this? Of course: removing the form’s dependency to use an i18n instance. Is this necessary? I don’t think so:

  public function configure()
  {
    $this->enableI18n(sfContext::getInstance()->getI18n());

Inject the i18n instance into the form. After that, everything could be translated: labels, help texts, messages, errors, even formatters! If you don’t want to use it, don’t. If you need it, make sure you get the damn i18n instance into the form somehow (there are solutions…). I know this is not easy because it changes how most of the widgets are rendered. But I think it would be worth the price.

Why do I want all this stuff?

That’s lots of feature requests. That’s lots of extensions and changes to the forms framework. But why? I can tell you! Because if all of the above features were available, 80% of my form templates could look like this:

  <?php echo $form->render() ?>

Wouldn’t that be worth it? Wouldn’t that help the core powers of symfony: KISS and DRY? I know that some projects have different people for generating form code and markup, but I think most work is done by the same developers. At least this would provide an option to do it differently.

Comments are welcome!

Download the package

For trying the sfMenuBuilder conveniently I have prepared a zip package containing all the classes and some examples (yes, that’s the download link). Feel free to use it any way you like to!

The package contains the following files:

config/
  example_app.yml
lib/
  menu_builder/
    sfMenuBuilder.class.php
    sfMenuItem.class.php
  resolver/
    sfObjectResolver.class.php
    sfObjectResolverInterface.class.php
examples.php
LICENSE

config/example_app.yml contains the markup and comprehensive documentation of a menu item in YAML – of course the parameters have to be the same wherever your menu structure is generated. In examples.php I placed some code showing how to create an sfMenuBuilder instance and how to render the menu either in tab levels or as a tree.

New options in sfMenuBuilder

sfMenuBuilder now works as a multi-instance holder for sfMenuBuilder objects. It’s like a singleton with multiple named singletons, allowing you to create several menu definitions in parallel and at the same time holding them in a static container – this is especially important for helper functions where you would have to manually store the menus somewhere else.

13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

class sfMenuBuilder {
  protected static 
    $instances    = array();
 
  protected
    $menuItems    = array(),
    $route        = null,
    $routeName    = null,
    $routeObject  = null,
    $i18n         = null;
 
  /**
   * Initialize an instance of sfMenuBuilder with the given data and name.
   * If there is an existing instance with the same name it will be overwritten.
   * 
   * Since sfMenuBuilder needs the current sfContext to access the routing and 
   * request objects the context has to be provided as parameter. 
   * 
   * @param array $itemsData    Array of data to create sfMenuItem objects
   * @param sfRoute $route      The current sfRoute
   * @param string $routeName   The name of the current sfRoute
   * @param string $name        The name of the instance, optional, defaults to "default"
   * @param sfI18n $i18n        An instance of sfI18n to perform translations using __()
   * 
   * @return sfMenuBuilder      The newly created instance
   */
  public static function initInstance(array $itemsData, sfRoute $route, $routeName, $name = 'default', sfI18n $i18n = null) {
    self::$instances[$name] = new sfMenuBuilder($itemsData, $route, $routeName, $i18n);
    return self::$instances[$name];
  }
 
  /**
   * Get the instance for the given name parameter.
   * 
   * Warning: this does not create instances automatically! If you 
   * try to get an instance that doesn't exist, null will be returned!
   * 
   * @param string $name    The name of the instance to fetch
   * 
   * @return sfMenuBuilder  An sfMenuBuilder instance for the given name.
   */
  public static function getInstance($name = 'default') {
    if (isset(self::$instances[$name])) {
      return self::$instances[$name];
    }
    return null;
  }
 
  /**
   * Set to protected to prevent access from outside the singleton instance holder.
   * 
   * @param array $itemsData    Array of data to create sfMenuItem objects
   * @param sfRoute $route      The current sfRoute
   * @param string $routeName   The name of the current sfRoute
   * @param sfI18n $i18n        An instance of sfI18n to perform translations using __()
   */
  protected function __construct(array &$itemsData, sfRoute $route, $routeName, sfI18n $i18n = null) {
    $this->routeName = $routeName;
    $this->route = $route;
    $this->i18n = $i18n;
 
    if ($this->route instanceof sfObjectRoute) {
      $options = $this->route->getOptions();
      if ($options['type'] == 'object') {
        $this->routeObject = $this->route->getObject();
      }
    }
 
    foreach ($itemsData as $routeName => $itemData) {
      $this->menuItems[$routeName] = new sfMenuItem($routeName, $itemData);
      $this->menuItems[$routeName]->initialize($this->routeName, $this->route, $this->routeObject, $this->i18n);
    }
  }
 
  /**
   * Render all items of a given level of the menu.
   * 
   * By default, only items inside the current route branch will be rendered.
   * To render all items regardless of their branch set the $forceAll 
   * parameter to true.
   * 
   * @param int $level          Level to render. 0 = top level, 1 = second level and so on
   * @param boolean $forceAll   Set to true to render all items even if their part of the tree is inactive
   * 
   * @return array              Array of items' XHTML code grouped by position
   */
  public function renderLevel($level = 0, $forceAll = false) {
    $rendered = array();
    foreach ($this->menuItems as $item) {
      $item->renderLevel($level, $rendered, $forceAll);
    }
    return $rendered;
  }
 
  /**
   * Render all menu items into a tree structure.
   * 
   * @param string $container   The XHTML container tag to use. Defaults to 'ul'.
   * 
   * @return string             Rendered items and child items, wrapped in container tag
   */
  public function renderTree($container = 'ul') {
    $rendered = '';
    foreach ($this->menuItems as $item) {
      $rendered .= $item->renderTree($container);
    }
    return content_tag($container, $rendered);
  }
}

As you can see now the sfRoute, its name and the sfI18n instance have to be injected into the initInstance() method. The constructor cannot be called from outside the class, so you have to use initInstance() and getInstance() in combination with $name (which defaults to “default”) to access your builder instances.

sfMenuItem revisited

The constructor then creates all the sfMenuItem objects and injects the routing and i18n information. Let’s take a look at the full sfMenuItem class next:

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343

class sfMenuItem {
  protected
    $myRouteName        = null,
    $children           = array(),
    $allRouteNames      = array(),
    $title              = '',
    $position           = 'default',
    $container          = 'li',
    $requireObjectClass = null,
    $customFunction     = null,
    $customUrl          = null,
    $route              = null,
    $routeName          = null,
    $routeObject        = null,
    $i18n               = null;
 
  /**
   * Generate a new sfMenuItem object using its own route name and the node
   * data from the structural schema.
   * 
   * @param string $myRouteName   This item's sfRoute name (as in routing.yml)
   * @param array $itemData       The data definition for this item
   */
  public function __construct($myRouteName, array $itemData) {
    $this->myRouteName = $myRouteName;
    $this->allRouteNames[] = $myRouteName;
 
    if (isset($itemData['title'])) {
      $this->title = $itemData['title'];
    }
    if (isset($itemData['position'])) {
      $this->position = $itemData['position'];
    }
    if (isset($itemData['container'])) {
      $this->container = $itemData['container'];
    }
    if (isset($itemData['alias_routes'])) {
      $this->allRouteNames = array_merge($this->allRouteNames, (array) $itemData['alias_routes']);
    }
    if (isset($itemData['require_object_class'])) {
      $this->requireObjectClass = $itemData['require_object_class'];
    }
    if (isset($itemData['custom_function'])) {
      $this->customFunction = new sfCallable($itemData['custom_function']);
    }
    if (isset($itemData['custom_url'])) {
      $this->customUrl = $itemData['custom_url'];
    }
 
    if (isset($itemData['children']) && is_array($itemData['children'])) {
      foreach ($itemData['children'] as $subRouteName => $subItemData) {
        $this->children[$subRouteName] = new sfMenuItem($subRouteName, $subItemData);
        $this->allRouteNames = array_merge($this->allRouteNames, $this->children[$subRouteName]->getAllRouteNames());
      }
    }
  }
 
  /**
   * Initialize the menu item and all child menu items using the current routing 
   * status of the application.
   * By passing the routing information you can either use routes from outside
   * the context (e.g. testing data) or just improve performance because this
   * would have to be repeated for all the child menu items. 
   * 
   * @param string $routeName   Name of the currently active route
   * @param sfRoute $route      Currently active route object
   * @param mixed $routeObject  Object that is transported through the route if it is an sfObjectRoute
   * @param sfI18n $i18n        An instance of sfI18n to perform translations using __()
   */
  public function initialize($routeName, sfRoute $route, $routeObject, sfI18n $i18n = null) {
    $this->routeName = $routeName;
    $this->route = $route;
    $this->routeObject = $routeObject;
    $this->i18n = $i18n;
 
    foreach ($this->children as $child) {
      $child->initialize($this->routeName, $this->route, $this->routeObject, $this->i18n);
    }
  }
 
  /**
   * Get this menu item's route name.
   * 
   * @return string   Route name of this single menu item
   */
  public function getMyRouteName() {
    return $this->myRouteName;
  }
 
  /**
   * Get all child sfMenuItem objects.
   * 
   * @return array    Array of sfMenuItem objects, using the route names as keys.
   */
  public function getChildren() {
    return $this->children;
  }
 
  /**
   * Get an array of all route names and alias route names this menu item
   * might use. Also includes all sub items' routes recursively.
   * 
   * @return array    Array of route names
   */
  public function getAllRouteNames() {
    return $this->allRouteNames;
  }
 
  /**
   * Get the title that will be used to render this item.
   * 
   * @return string   Title text
   */
  public function getTitle() {
    return $this->title;
  }
 
  /**
   * Get the position this item will be rendered at.
   * 
   * @return string   Position. Defaults to "default"
   */
  public function getPosition() {
    return $this->position;
  }
 
  /**
   * Get this menu item's wrapper container.
   * 
   * @return string   HTML wrapper Container name
   */
  public function getContainer() {
    return $this->container;
  }
 
  /**
   * Get the object class that is required for this item to 
   * be rendered as "enabled".
   * 
   * @return string   Object class name 
   */
  public function getRequireObjectClass() {
    return $this->requireObjectClass;
  }
 
  /**
   * Get this menu item's custom URL.
   * 
   * @return string   Custom URL
   */
  public function getCustomUrl() {
    return $this->customUrl;
  }
 
  /**
   * If an i18n instance was provided, this will do the translation.
   * @see sfI18n::__()
   * 
   * @param string $string  The string to translate
   * 
   * @return string         Translated string
   */
  public function __($string) {
    if (is_null($this->i18n)) {
      return $string;
    }
    return $this->i18n->__($string);
  }
 
  /**
   * Render the current menu item's content text.
   * 
   * The content always contains an 'a' tag containing either a href
   * link (if the item is enabled) or the item title only.
   * 
   * All titles are translated using i18n.
   * 
   * @return string   Rendered menu item content HTML code
   */
  public function renderContent() {
    if ($this->customFunction instanceof sfCallable) {
      return $this->customFunction->call($this);
    }
 
    if (!$this->isEnabled()) {
      return content_tag('a', $this->__($this->title));
    } else {
      if (!is_null($this->customUrl)) {
        return link_to($this->__($this->title), $this->customUrl);
      } elseif (is_null($this->requireObjectClass)) {
        return link_to($this->__($this->title), '@'.$this->myRouteName);
      } else {
        return link_to($this->__($this->title), $this->myRouteName, sfObjectResolver::resolve($this->routeObject, $this->requireObjectClass));
      }
    }
  }
 
  /**
   * Check if the item is enabled or not.
   * An item will be disabled if it requires an object class
   * that cannot be found by the resolver.
   * 
   * @return boolean  True if the item is enabled
   */
  public function isEnabled() {
    return is_null($this->requireObjectClass) || !is_null(sfObjectResolver::resolve($this->routeObject, $this->requireObjectClass));
  }
 
  /**
   * Check if the item is currently selected.
   * An item will be selected if the current routeName matches
   * any route in the items allRouteNames property.
   * 
   * @return boolean  True if the item is currently selected in the menu
   */
  public function isCurrent() {
    return in_array($this->routeName, $this->allRouteNames);
  }
 
  /**
   * Wrap an item with the container that is set. If no container
   * is defined, just return the item.
   * 
   * @param string $text    Text content
   * @param array $options  Options array passed to content_tag() helper
   * 
   * @return string         Rendered content tag
   */
  protected function containerTag($text, $options = array()) {
    if ($this->container != '') {
      return content_tag($this->container, $text, $options);
    }
    return $text;
  }
 
  /**
   * Render the current menu item.
   * 
   * The item is rendered inside the element given as "container" parameter.
   * The container defaults to the HTML list element ("li").
   * 
   * Items that require an object route without existing object of that type
   * have their class attribute set to "disabled". Items that match the current
   * route have their class attribute set to "current".
   * 
   * @return string   Rendered menu item HTML code
   */
  public function render() {
    $text = $this->renderContent();
    if (!$this->isEnabled()) {
      return $this->containerTag($text, array('class' => 'disabled'));
    } elseif ($this->isCurrent()) {
      return $this->containerTag($text, array('class' => 'current'));
    }
    return $this->containerTag($text);
  }
 
  /**
   * Get the sfRoute object associated with all the menu items.
   * 
   * @return sfRoute  sfRoute object
   */
  public function getRoute() {
    return $this->route;
  }
 
  /**
   * Get the route name associated with all the menu items.
   * 
   * @return string   Route name
   */
  public function getRouteName() {
    return $this->routeName;
  }
 
  /**
   * Get the route object out of sfObjectRoute.
   * 
   * @return mixed    Route object generated by sfObjectRoute
   */
  public function getRouteObject() {
    return $this->routeObject;
  }
 
  /**
   * Render all menu items of a given child level related to this item.
   * 
   * The rendered items are added to the $rendered array parameter grouped 
   * by their position.
   * 
   * @param int $level          Level to render. 0 will return the current item, 1 all items of the first child level and so on.
   * @param array $rendered     Contains all items rendered so far. Rendered items will be appended to the array.
   * @param boolean $forceAll   Force the rendering of all sub items, even if their tree is not in the current route
   */
  public function renderLevel($level, array &$rendered, $forceAll = false) {
    if ($level == 0) {
      $rendered[$this->position][] = $this->render();
    } elseif ($level > 0 && ($forceAll || in_array($this->routeName, $this->allRouteNames))) {
      $level--;
      foreach ($this->children as $child) {
        $child->renderLevel($level, $rendered, $forceAll);
      }
    }
  }
 
  /**
   * Render all menu items into a tree structure.
   * 
   * @param string $container   The HTML container tag to use. Defaults to 'ul'.
   * 
   * @return string             Rendered item and child items, wrapped in container tag
   */
  public function renderTree($container = 'ul') {
    $children = '';
    foreach ($this->children as $child) {
      $children .= $child->renderTree($container);
    }
 
    $text = $this->renderContent();
    if ($children != '') {
      $text .= content_tag($container, $children);
    }
    if (!$this->isEnabled()) {
      return $this->containerTag($text, array('class' => 'disabled'));
    } elseif ($this->isCurrent()) {
      return $this->containerTag($text, array('class' => 'current'));
    }
    return $this->containerTag($text);
  }
}

All the configuration options

Now you can see the full parameter set of sfMenuItem – but what do all those values actually mean? I think looking at the commented parameter definitions in my sample yaml file will make it more understandable:

all:
  menu:
    items:
 
      # Each item must use its route name as in routing.yml as its index.
      # If you provide the custom_url parameter, the route name will be
      # ignored, so you may provide a name that does not exist.
      first_item_route_name:
 
        # The title is the text that is displayed for the item.
        # This text will automatically be translated if an i18n instance is passed
        # to the sfMenuItem's initialize() method.
        title:                My first item title
 
        # Alias routes are route names that should set the same menu item as current.
        # If your applications uses different routes for the same page (e.g. "update" 
        # routes in form actions) you must provide them here, otherwise the menu
        # will not display correctly.
        alias_routes:         [first_item_update_route_name, ...]
 
        # Using the position option items can be grouped into separate arrays.
        # This is used for the rendering of tab levels, where the level contains
        # an array with the positions as indexes.
        # Typical applications might use options like "left" and "right" to separate
        # the tabs of a level into different positions. If no position is provided it 
        # defaults to 'default'.
        position:             default
 
        # This is the HTML container to use for rendering the item's content. If no container
        # is provided, it defaults to 'li'. You may also provide an empty container (''), 
        # which will make the item content return without an outer tag. Beware though, that
        # without this tag the options "disabled" and "current" have no element to be applied to.
        container:            li
        container:            ''
 
        # This option indicates that this item requires an object of a specific type.
        # The sfMenuItem will try to get this object through the sfObjectRoute
        # and (if the route object is different) through sfObjectResolver.
        # If no object of this type is found the item will be set to "disabled".
        require_object_class: SomeClass
 
        # If you provide a custom function, it will be called instead of rendering the
        # item's content using the title. You can provide any callable, either a globally
        # accessible function name or an array holding a class name and a static method name.
        # The sfMenuItem object is passed to the function, so the item's public methods can 
        # be used to access nearly all the parameters and settings.
        # 
        # The function footprint should be something like this:
        # 
        # function some_function_name(sfMenuItem $item) {
        #   // do custom rendering here
        #   return $itemContent;
        # }
        custom_function:      some_function_name
        custom_function:      [SomeClass, someMethod]
 
        # Providing a custom url you can generate menu items that link somewhere else.
        # It will be used in an url_for() call, so everything that works in there will be fine.
        custom_url:           http://www.symfony-project.org/my_custom_url
 
        # In the children option you can provide child items of the given menu item.
        # Each child item may have children itself, recursively. Of course all the options
        # as for this item may be defined for any child item.
        children:
          child1_route_name:
            child1_title:       Some title
 
          child2_route_name:
            child2_title:       Some other title
 
            children:
              # I think you get it...

Any questions?

I think those comments should explain the options quite well. Since I can’t think of another example at the moment and also may not publish what the menu I use at work actually looks like I can only ask for user feedback if you don’t understand something or just can’t see its usage. If I see that something is still unclear I will try to make it more specific. I can only tell you that at the moment every single option except custom_url is in use in my application and I’m glad for having all of them (and I may need custom_url in the future myself).

Dynamic menus

As promised in part 3, I want to think about how sfMenuBuilder could be used dynamically. The first thing that comes to mind is having a tree-like database structure (if you need nested menus), using nestedSet features provided (AFAIK) both by Propel and Doctrine. The basic schema for a dynamic menu could look like this:

propel:
  menu_item:
    id:
    route_name:           { type: varchar(255), required: true }
    title:                { type: varchar(255), required: true }
    alias_routes:         { type: varchar(255), required: false }
    position:             { type: varchar(10), required: false, default: 'default' }
    container:            { type: varchar(10), required: false, default: 'li' }
    require_object_class: { type: varchar(255), required: false }
    custom_function:      { type: varchar(255), required: false }
    custom_url:           { type: varchar(255), required: false }

Just add the code for transforming these database objects into the arrays needed for sfMenuItem and you’re done!

You could also extend statically defined menu arrays by merging with dynamically created arrays. Due to the simple array syntax nearly anything can be used to describe a menu.

That’s it!

Finally we have come to an end and the sfMenuBuilder is ready to use. I hope my articles were not too bulky and rather helpful for you guys out there. When designing something as large as this and writing about it, I always want my readers to understand what goes through my mind and how I arrived at my destination. In the end, my articles shouldn’t be about the final code but more about designing things and working them out.

What started as a proof of concept for sfObjectResolver has in the end become a fully usable little library that will hopefully evolve and be used in various applications, and at the same time teach people about OOp and clean design. I know, I always exaggerate, but that’s just me…

Have fun!

Up until now we have defined a tree structure in yaml and created a PHP class to generate menu items recursively as well as render their content. We are able to load the object assigned to an sfObjectRoute and even find related objects and create route links for those through the sfObjectResolver class.

The next step

Now I want to show you how to use those sfMenuItem objects to generate your menu HTML code. There are 2 typical menu variants I want to implement:

• Generate one flat level of a menu (e.g. for tab navigation)
• Generate a complete tree menu (e.g. for a sidebar menu)

During the first part I only showed the HTML code for the tab row version – this is mainly because I haven’t used the menu code for trees myself yet, but now I think the tree version might be even more important for some users, so I decided to implement it, too.

Flat (tab) menu generation

When designing a tab menu based on a tree structure you have to keep a few things in mind. Most important is that when providing sub level tabs, only tabs that are descendants (children) of the active tab one level above should be shown.

To achieve rendering of a single level, I added a renderLevel() method to sfMenuItem.class.php:

  public function renderLevel($level, array &$rendered) {
    if ($level == 0) {
      $rendered[] = $this->render();
    } elseif ($level > 0 && in_array($this->routeName, $this->allRouteNames)) {
      $level--;
      foreach ($this->children as $child) {
        $child->renderLevel($level, $rendered);
      }
    }
  }

The code more or less explains itself. If the $level parameter is 0 (when the level is the one that is to be rendered) the item is rendered and added to an array passed by reference. If the level is too high and the current item is parent of the route to display, the level is decreased by 1 and renderLevel() is called for all child items. Thus only the items of a specific level and inside the required route path are rendered.

To create the complete menu I added another class: sfMenuBuilder.class.php:

class sfMenuBuilder {
  protected $menuItems = array();
 
  protected $route = null;
  protected $routeName = null;
  protected $routeObject = null;
 
  public function __construct(array &$itemsData) {
    foreach ($itemsData as $routeName => $itemData) {
      $this->menuItems[$routeName] = new sfMenuItem($routeName, $itemData);
    }
 
    $this->routeName = sfContext::getInstance()->getRouting()->getCurrentRouteName();
    $this->route = sfContext::getInstance()->getRequest()->getAttribute('sf_route');
 
    if ($this->route instanceof sfObjectRoute) {
      $options = $this->route->getOptions();
      if ($options['type'] == 'object') {
        $this->routeObject = $this->route->getObject();
      }
    }
 
    foreach ($this->menuItems as $item) {
      $item->initialize($this->routeName, $this->route, $this->routeObject);
    }
  }
 
  public function renderLevel($level = 0) {
    $rendered = array();
    foreach ($this->menuItems as $item) {
      $item->renderLevel($level, $rendered);
    }
    return $rendered;
  }
}

Now you can generate your menu like this:

  $builder = new sfMenuBuilder(sfConfig::get('app_menu_items'));
  $mainItems = $builder->renderLevel(0);
  $subItems = $builder->renderLevel(1);
 
  $mainItemsHtml = content_tag('ul', implode("\n", $mainItems));
  $subItemsHtml = content_tag('ul', implode("\n", $subItems));

You could place this code inside a helper function or directly in the view. But don’t do it until I’ve showed you how to do this even nicer in part 4

Tree menu generation

To generate a tree menu we have to split up sfMenuItem::render() a little because we need to reach inside the li elements:

  public function isCurrent() {
    return in_array($this->routeName, $this->allRouteNames);
  }
 
  public function renderContent() {
    $i18n = sfContext::getInstance()->getI18n();
 
    if (!$this->isEnabled()) {
      return content_tag('a', $i18n->__($this->title));
    } else {
      if (is_null($this->requireObjectClass)) {
        return link_to($i18n->__($this->title), '@'.$this->myRouteName);
      } else {
        return link_to($i18n->__($this->title), $this->myRouteName, sfObjectResolver::resolve($this->routeObject, $this->requireObjectClass));
      }
    }
  }
 
  public function render() {
    $text = $this->renderContent();
    if (!$this->isEnabled()) {
      return $this->containerTag($text, array('class' => 'disabled'));
    } elseif ($this->isCurrent()) {
      return $this->containerTag($text, array('class' => 'current'));
    }
    return $this->containerTag($text);
  }

Now we can define a method to render the tree:

  public function renderTree($container = 'ul') {
    $children = '';
    foreach ($this->children as $child) {
      $children .= $child->renderTree($container);
    }
 
    $text = $this->renderContent();
    if ($children != '') {
      $text .= content_tag($container, $children);
    }
    if (!$this->isEnabled()) {
      return $this->containerTag($text, array('class' => 'disabled'));
    } elseif ($this->isCurrent()) {
      return $this->containerTag($text, array('class' => 'current'));
    }
    return $this->containerTag($text);
  }

In sfMenuBuilder.class.php we also define a method to render the tree:

  public function renderTree($container = 'ul') {
    $rendered = '';
    foreach ($this->menuItems as $item) {
      $rendered .= $item->renderTree($container);
    }
    return content_tag($container, $rendered);
  }

Creating the tree is even easier than creating the tab rows:

  $builder = new sfMenuBuilder(sfConfig::get('app_menu_items'));
  $treeHtml = $builder->renderTree();

Using the code above we are able to create tree-like menus as well as tab menu rows out of the same sfMenuItem objects.

We are not done yet

Now you know how it all works out. But do you think that was all? Of course not! Just give me a little more time to write the 4th and final part to this series, showing the full classes including phpDoc comments and adding the following features to our menu system:

• Tab groups
• Custom containers
• Callback menu items
• Static url menu items
• A multi-instance sfMenuBuilder with named instances for several independent menus at once
• … and some thoughts about how all this could be used dynamically

Curious? You better be!

Have fun!

The structure again

To make sure you understand what comes next I want to bring the last version of the menu structure we defined in app.yml back to mind:

all:
  menu:
    items:
      homepage:
        title:   Home
        children:
          homepage:
            title:   Home
          about:
            title:   About
 
      article_index:
        title:   Articles
        children:
          article_index:
            title:   Article index
          article_view:
            title:   View article details
            require_object_class: Article
          article_edit:
            title:   Edit article
            require_object_class: Article
            alias_routes: [article_update]
          article_comments_edit:
            title:   Edit article comments
            require_object_class: Article
            alias_routes: [article_comments_update]
          user_view:
            title:   View article author
            require_object_class: User

The object constructor

I want each item out of this menu definition to be a single PHP object. The object should be created using the route name (the key in the yaml structure) and an array containing the node’s data. Both parameters are passed to the constructor of sfMenuItem.class.php:

class sfMenuItem {
  protected $myRouteName;
  protected $children = array();
  protected $allRouteNames = array();
 
  protected $title = '';
  protected $requireObjectClass = null;
 
  public function __construct($myRouteName, array $itemData) {
    $this->myRouteName = $myRouteName;
    $this->allRouteNames[] = $myRouteName;
 
    if (isset($itemData['title'])) {
      $this->title = $itemData['title'];
    }
    if (isset($itemData['alias_routes'])) {
      $this->allRouteNames = array_merge($this->allRouteNames, (array) $itemData['alias_routes']);
    }
    if (isset($itemData['require_object_class'])) {
      $this->requireObjectClass = $itemData['require_object_class'];
    }
 
    if (isset($itemData['children']) && is_array($itemData['children'])) {
      foreach ($itemData['children'] as $subRouteName => $subItemData) {
        $this->children[$subRouteName] = new sfMenuItem($subRouteName, $subItemData);
        $this->allRouteNames = array_merge($this->allRouteNames, $this->children[$subRouteName]->getAllRouteNames());
      }
    }
  }

As you can see the item’s data is stored in the object and child items are automatically added recursively. You can also see that both the own route name as well as all child route names are stored in the allRouteNames property. This will make it easy to find out if a specific node represents any route somewhere down below and thus has to be displayed.

Injecting the routing information

To make the intelligence of the sfMenuItem object work we need to initialize it using the real routing information. This information can be retrieved from the symfony context like this:

    $this->routeName = sfContext::getInstance()->getRouting()->getCurrentRouteName();
    $this->route = sfContext::getInstance()->getRequest()->getAttribute('sf_route');
 
    if ($this->route instanceof sfObjectRoute) {
      $options = $this->route->getOptions();
      if ($options['type'] == 'object') {
        $this->routeObject = $this->route->getObject();
      }
    }

Since it would be a little bloating to do this in all menu items and also prevents you from injecting testing data the best way is to retrieve the data outside the sfMenuItem class (I will show later where to do this) and inject it into each sfMenuItem. This is done in the initialize() method:

  public function initialize($routeName, sfRoute $route, $routeObject) {
    $this->routeName = $routeName;
    $this->route = $route;
    $this->routeObject = $routeObject;
 
    foreach ($this->children as $child) {
      $child->initialize($this->routeName, $this->route, $this->routeObject);
    }
  }

Rendering the output

Now the sfMenuItem object is ready to be rendered. The basic render() method looks like this:

  public function render() {
    $i18n = sfContext::getInstance()->getI18n();
 
    if (!$this->isEnabled()) {
      return $this->containerTag(content_tag('a', $i18n->__($this->title)), array('class' => 'disabled'));
    } else {
      if (is_null($this->requireObjectClass)) {
        $link = link_to($i18n->__($this->title), '@'.$this->myRouteName);
      } else {
        $link = link_to($i18n->__($this->title), $this->myRouteName, sfObjectResolver::resolve($this->routeObject, $this->requireObjectClass));
      }
 
      if (in_array($this->routeName, $this->allRouteNames)) {
        return $this->containerTag($link, array('class' => 'current'));
      } else {
        return $this->containerTag($link);
      }
    }
  }
 
  public function isEnabled() {
    return is_null($this->requireObjectClass) || !is_null(sfObjectResolver::resolve($this->routeObject, $this->requireObjectClass));
  }
 
  protected function containerTag($text, $options = array()) {
     return content_tag('li', $text, $options);
  }

I’m loading the i18n instance inside the render() method to translate the title texts. Of course this could be left out if you either don’t need i18n for your menu or just translate the titles before they are inserted into the sfMenuItems.

Why an object resolver is useful here

You can see 3 additional method dependencies of render(): isEnabled(), containerTag() and the external calls to sfObjectResolver::resolve(). The containerTag() is easy: this way the embracing tag for the menu item (li by default here) can be modified. isEnabled() checks if the item requires a specific object class and looks it up in sfObjectResolver. If no matching object is found, no link can be generated, so the a tag is just left without the href attribute.

See Managing “soft” relations between PHP objects to learn more about the resolver – here it comes in really handy, because the sfMenuItem class has absolutely no clue about the objects it has to link to, but using the resolver moves this dependency into each object’s context. Using this little trick you can have a menu that automatically generates reference route links to objects without the need to know anything about the objects but their class names. Could it be any more comfortable?

That’s it again for today (the articles just grow so long!). In my next article I will show you how to wrap the menu building process in a small builder class and what additional options sfMenuItem may provide.

One small side note: you may have noticed that the code presented here doesn’t follow symfony’s PHP coding style guidelines in terms of bracket placement. I just like them more this way and symfony’s style would make the article even longer, but feel free to change them as you like

Have fun!