Is symfony the best documented OS project out there?

Introduction

Well, I’m not actually going to answer that question because there are many thousands of projects and I don’t actually know how well they are all documented, so it would be completely unfair of me! However, with the release of this year’s advent calendar symfony is at least setting a high standard for others to follow.

So what should you read?

In our office, we have several symfony books kicking around, and new developers often ask where to start. In fact, it can be quite frustrating to have to tell a new guy that the 2 days they’ve spent studying the “Definitive guide to symfony” has really only helped them to maintain our first project from 2 years ago…

Starting a new project & don’t know much about symfony

  • Do the Jobeet tutorial – seriously, no matter how much you think you can wing it, don’t. Set aside a couple of days and go through it. It’s even supported by an svn repository so you don’t have to type much code if you don’t want to – although be aware that the documentation is much more up to date that the code behind it, so if in doubt, trust the doc. The tutorial is also available in the Propel flavour.
  • Scan the reference guide – I’m not saying read it, unless you have bags of time, but at least give it a quick scan so you know what’s there. When you’re struggling later you’ll think “I’ve seen that somewhere” – and chances are it was in the reference guide

Know the basics and want to take it further

  • Read the forms book – The newer versions of symfony still support the forms framework and chances are you will want to use it, so it’s a good idea to give this a read. You will have a good idea already after doing the  Jobeet tutorial but there are things you will have missed and this will open your eyes.
  • Read More with symfony (the 2009 advent calendar) – If you’ve started to get the hang of things and want to know what “the experts” do when they are coding with symfony, this is where to look! This book has been written by members of the symfony community, so comes totally from the perspective of experienced developers who have been through the same process as the one you are going through.
  • Browse the cookbook – If there is something you are wondering about that seems like it would be a common task, there might well be a “recipe” for that very task! The cookbook has not made it to the 1.4 branch of documentation at the time of writing, but most of the recipes (if not all) will work just fine in the later versions. 
  • Check the wiki – this is basically a cookbook with user supplied recipies, whereas the “official” cookbook is maintained by the core team. That’s not to say it’s any less of a resource – just that it’s slightly more likely to contain “opinions” and out of date ideas.

Stuck with something

  • Check through all of the above – in particular the reference guide and cookbook. “Googling” for a well structured phrase will often get you to one of the correct pages in the manual – just be sure to switch it to the correct version, as a lot of the old 1.0 pages still come up first in searches.
  • Browse the API documentation – The symfony codebase is generally very well commented, so if you are wondering about the methods of a particular class, or the options for a widget, or some other property/function/value that you can’t find anywhere in the documentation, there is a good chance the api docs will help you out.

Getting “human” help

Sometimes all the reading and googling gets you nowhere and you can quickly find yourself feeling very frustrated and alone. Fortunately symfony is backed by an enourmous community, and in a rare web-community-twist it’s one that works both ways. Not only do people ask questions, but there are hundreds of people around to answer them too!

My personal “hangouts”

  • IRC – Need a quick answer, this is the place.  You won’t always get a quick answer, because there are a lot of lurkers, but there are also a lot of “regulars” who hang around in there so be patient and try again a bit later if you don’t get a response straight away. Check out freenode channel #symfony (I’m rooster).
  • Symfony forum – Not quite as well publicised as the Google groups, but a valuable resource all the same. It’s really down to your communication preferences if you like forums or mailing lists, so just pick one (or both). What you will find is that different people are active on the forum compared to the Google group – it’s a shame there is not much harmony here as it can be a bit strange for newcomers. One thing I will say about the forum is that you will always get a response, if not by anyone else at least by Halfer, Ryan or myself (Russ).
  • Google symfony users group – Very busy but with a lot of experienced developers around to answer questions. Can take a bit longer than the forum to get a response, but you are generally speaking to a larger audience here. You are more likely to get a response from Fabien if you post here, he hasn’t posted in the forum for 6 months! I’m RussMonkey in this one.
  • Trac – If you have to come to the conclusion that what you are working with is a bug, or maybe it took you way to long to find the answer because the documentation on the subject was wrong, missing or just bad, then please raise a ticket. Depending on the nature of the issue, it can seem like it takes a while to get a response – so rather than “bumping” comments in the ticket itself, it’s normally best to start a discussion in an appropriate place, most likely the dev mailing list and be sure to link to the discussion from the ticket, and link to the ticket in the discussion.

Staying “fresh”

It’s quite hard to keep up with everything that’s going on, so there are a few things that you really should do:

  • Subsribe to the symfony project blog – this is where you’ll get the most important news about changes and future development from the core team.
  • Subscribe to the symfony bloggers feed – blog posts from the community, including this one, appear here. It has grown quite substantially lately, and can get cluttered with non-English blogs, which really should be in a seperate feed to be honest – but if you are using a feed reader you can just skip over them (unless you can read that particular language of course). There are a lot of experienced bloggers here, and you’ll start to recognise some of the more useful ones as you read.
  • Subscribe to the user group mailing list – either as a daily digest, or an rss feed (my preference). It’s useful to scan through and see what people are talking about, so you can recognise recurring problems and issues that you may face one day.
  • Those above things should take no more than a few minutes a day to browse and keep an eye on, but if you really want to get a bit more involved and have a bit more time to spare, then consider IRC, the forum and the dev mailing list also. 

Summary

So, you can see why I am starting to believe that symfony is at least one of the best documented and supported projects out there, in this post alone I have listed 14 resources that the developer can use can make the most of their time developing. Symfony has a (somewhat improving) reputation for being a one man show when it comes to the direction of the project and the core coding, but that is certainly not the case when it comes to the community support side of things – you are not alone!

Random words and phrases – Pondus inspired

I har ikke skrevet anything for a while, so whilst I read the new edition of Pondus I figured I might as well note a few nice ord and phrases I stumble across. I’ll also mention a few day-to-day things that I’ve come across that may be nyttig. Oh, and of course be a bit forsiktig with the “Pondus ord” because many of them are of course quite “slangy”!

  • Det står ingenting på denne lappen – There is nothing on this ticket
  • Overbevist – Satisfied
  • Vellykket – Successful
  • Du er nødt til å… – You really have to…
  • Ta en blund – Take a nap
  • Kan jeg få en sånn – May I have one of those/these? (Whilst pointing at something)
  • Kjempeflaks – Really lucky
  • Kollisjonsputer – Airbags
  • Jeg må tidlig opp – I have to be up early
  • Litt skuffa – A bit disappointed
  • Vidunderlig – Wonderful
  • Jeg er lei av… – I’m sick of…
  • Jeg vil du skal… – I would like you to…
  • Åpenbart – Obviously
  • Ødelegge – Destroy
  • Takk og lov! – Thank goodness!

*vis words that I like:

  • Sannsynligvis – Probably
  • Tilfeldigvis – Accidentally
  • Forhåpentligvis – Hopefully
  • Heldigvis – Luckily

* P.s. When I write på engelsk I am borrowing a format that I really like, used by Kari in her Norwegian blog. I urge you to subscribe to that one too!

PHP Session settings ignored?

I just read an extremely interesting post which explains an unwanted side effect of garbage collection by some Debian based systems. This cleanup process causes (maybe amongst other things) sessions to be cleared every 24 minutes, regardless of any ini setting you have set after the php.ini file is parsed (for example using ini_set() – if you are a symfony user, this is done during initialisation based on a setting in your factories.yml file).

Check it out: http://elephpants.blog.linpro.no/2009/10/02/unwanted-end-of-sessions/

Symfony forms – Flexible widgets based on user credentials (sfcontext is evil)

Background

This issue has come up many times in the symfony forum and on IRC, and whilst it seems like a fairly trivial one, it is important to discuss the best practice around it. Often we want to modify a form based on something outside the form’s scope, like a user’s credentials or the page they are on, or maybe some session values – lets take the example of a dropdown widget where admin users get to see a few more options.

The bad way

Everyone that has been using symfony for a while is aware of the context singleton. This magic sprite allows us to grab all sorts of information about the context we are in, including the user, session, request, view, and many more things. Whilst it certainly has its place, most of the time, however, we should avoid using it. The clue to the reason why is carefully disguised in the class name “Context”.

When we refer to a context in our code, we are locking ourselves in to the fact that the context must exist, so every time we use it we are basically saying that this class can now only be used in a symfony project with a fully initialised symfony stack hanging over it. This becomes a problem in things like unit tests, where you have to mock up a loaded context object with bells and whistles in order to test a simple function or class.

So this is what you might think of doing:

// In your form class
public function configure()
{
  $choices = array(1 => "something boring", 2 => "something dull");
 
  $currentUser = sfContext::getInstance()->getUser();
 
  if ($currentUser->isAuthenticated() && $currentUser->hasCredential("admin"))
  {
    $choices += array(5 => "something cool", 6 => "something leet");
  }
 
  // ....
}

The reason this is bad is that the forms framework is a standalone framework – it should be possible to pick up your form class and drop it into any project. It should also be possible to test it independently of symfony, without being tied in by sfContext. So what is the better way?

The dependency injection approach

You might read that and think “woah, this is getting complicated!” but we’re not talking about dependency injection containers here, we’re simply saying that you can make your form object depend on something to run. The thing it depends on should not be the context singleton, it should be the minimum thing that the form needs to operate correctly – which in this case, is a user object that supports credentials.

// In your actions.class.php
$this->form = new myForm(array(), array("currentUser" => $this->getUser()));
 
// In your form class
 
// ...
if ( !($this->getOption("currentUser") instanceof sfUser))
{
  throw new InvalidArgumentException("You must pass a user object as an option to this form!");
}

The test here is where we are making this form “dependent” on a user object. In this case we are insisting that the object is an instance of sfUser, which you may argue is tying us in to symfony again, but you could use any test here to ensure that the object will have the necessary functionality you need, maybe check for the existence of a “hasCredential()” method for example.

When writing a test for this form class, we now only need to instantiate a user object and load it with some credentials – much easier than doing the same thing and locking into a context singleton. There may be other times when this form could be useful in a lightweight environment, where you can get speedy access to a user object but don’t want the overhead of the symfony context – you might not think of one now, but it’s best to code this way and you’ll have less reasons to kick yourself further down the line.

The completed code, for our single widget form

// In your form class
public function configure()
{
  if (!($this->getOption("currentUser") instanceof sfUser))
  {
    throw new InvalidArgumentException("You must pass a user object as an option to this form!");
  }
  else
  {
    $currentUser = $this->getOption("currentUser");
  }
  $choices = array(1 => "something boring", 2 => "something dull");
 
  if ($currentUser->isAuthenticated() && $currentUser->hasCredential("admin"))
  {
    $choices += array(5 => "something cool", 6 => "something leet");
  }
 
  $this->widgetSchema['my_dropdown']    = new sfWidgetFormChoice(array("choices" => $choices));
  $this->validatorSchema['my_dropdown'] = new sfValidatorChoice(array("choices" => array_keys($choices)));
}

Wrap up

Think about this example the next time you think about modifying a query based on a user object, or session value in a peer class, or Doctrine table class… Maybe you should have passed a parameter there too? Every class and method you write, think about how you can reuse it, will it even be possible the way you have written it? If something simply must be coded in a symfony specific way, think about making a parent and a child class for the problem you are trying to solve. In the parent class, you can make things as generic as possible – so you can re-use that class to your heart’s content. In the child class, you can add the symfony specific code – kept to a minimum.

Chris Ryan inspired Norwegian vocabulary – Blodpenger chapter 1

Why?

I haven’t been too active lately with the Norwegian blog, mostly because of the usal lame excuse regarding time and too much work and all that. One thing I have been doing lately is reading, or at least trying to read the Chris Ryan book “Blodpenger”, and during this reading several words crop up that are interesting – but which I forget way too quickly.

Hopefully by sharing some of them here, it will help me to remember, and also give me a quick reference point for when I inevitably forget again!

Some words – from prologue and chapter 1

  • Sylige – visible
  • Stram – tight (fingrene var stram)
  • Forvridd – contorted, mangled, twisted (På ringfingeren satt en forvridd gullring)
  • Dugg – dew
  • Grundigere – thoughtfully
  • Bøye – bend (han bøyde seg = he bent over)
  • Tilhøre – belong to (måtte ha tilørt en kvinne)
  • Halvannen – one and a half
  • en Grop ( a ditch)
  • Peste – panted (den peste mens den løp)
  • Ryggsøyle – spine
  • Mistanke – suspicion
  • Nøyaktig – precisely
  • Gjørmete – muddy
  • Gned – rubbed
  • Slør – veil
  • Blikk – look, glance (hun løftet blikket)
  • Lynraskt – very quickly, blazingly, “at light speed”
  • Påføre – cause, bring upon
  • Som ventet – as expected (den var som ventet)
  • Ifølge – according to
  • Somle – faff, dawdle, time waste
  • Myke halsen – stiff neck
  • Klesplagg – Garment, Item of clothing (et nytt klesplagg)
  • Øreflippen – the earlobe
  • Slikket – licked
  • Åndsfraværende – vacantly (Han slikket øreflippen hennes åndsfraværende)
  • Ånd – spirit, Fraværende – absent
  • Bekymret – worried, concerned (det som bekymret ham)
  • Fortjener – deserve
  • Halvt fordervet – half to death (han slo henne halv fordervet)
  • Tillatelse – permission

And that’s not even the whole chapter…

« Previous PageNext Page »