Symfony Resources Central

The Roots - Part I - HTTP is the web's language

Romain Dorgueil — Sun, 24 Jan 2010 23:30:00 +0100

Everybody working in web development knows about this, right?

I realized recently that it was far from being true. While frameworks and ORMs make web developers' job easier and easier, more and more people comes to develop websites without knowing about the real basics. They use relational databases without knowing anything about SQL, and they develop websites without understanding how the client will talk with their website.

I don't pretend to make a revolution there, but if I bring my car to the car mechanic, I hope he will know a bit more about it than "engine makes power, and so the car is working". So are my exigences when I ask a specialist to work on a website.

To give a parallel with playing music, you can learn to play some songs without knowing anything about harmony and rhythm, but is you want to get serious about what you play, it will become an absolute requirement.

I so decided to make some short articles explaining in simple terms what those basis are, to my humble opinion. First one is about HTTP.

So what is HTTP ?

HTTP is a communication protocol that comes at application level. In easier terms, it means that it's a language that allows two applications to communicate by exchanging messages. How those messages will transit between the two applications is not HTTP purpose, and in a network-less world, you can even imagine exchanging messages on floppy drives. In the real world, we prefer make it transit over networks, using some low levels network protocols like TCP/IP.

As it's true 99% of the time, we will assume it's always true: HTTP is the communication language, TCP/IP will handle the transport of HTTP messages between actors.

Let's go back to the original definition.

HTTP 1.1 (the last protocol version) is defined by RFC 2616, which says:

The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. HTTP has been in use by the World-Wide Web global information initiative since 1990.

...

The HTTP protocol is a request/response protocol. A client sends a request to the server in the form of a request method, URI, and protocol version, followed by a MIME-like message containing request modifiers, client information, and possible body content over a connection with a server. The server responds with a status line, including the message's protocol version and a success or error code, followed by a MIME-like message containing server information, entity metainformation, and possible entity-body content.

This is the absolute minimum to know. HTTP is a communication language, and works in a request-message, response-message way. This is extremely simple. The RFC then explain that it can do much more complicated things, like handling messages that will go through many nodes before reaching destination, but let's keep it simple, and say that from a client or server point of view, it will result in exactly the same thing.

The RFC also makes clear that HTTP is not dependent on the transport mean:

HTTP communication usually takes place over TCP/IP connections. The default port is TCP 80, but other ports can be used. This does not preclude HTTP from being implemented on top of any other protocol on the Internet, or on other networks. HTTP only presumes a reliable transport; any protocol that provides such guarantees can be used; the mapping of the HTTP/1.1 request and response structures onto the transport data units of the protocol in question is outside the scope of this specification.

And it will be out of the scope of this blog post too. HTTP doesn't care about how the message transport is done, but it's usually handled by TCP/IP.

Messages, requests, responses

So the basic communication tool will be messages. A client to server message is called a request, and the server to client "answer" is called a response. Even if it may seems obvious, a response cannot be the server initiative: a client must have made a request, and server response is the response to this request.

Now we're pretty confident about HTTP messages being Tupperware boxes containing informations. Let's make a step forward and look at how this box content is structured.

Messages consists of three parts: the start line, the headers, and the body. As each part has specific rules depending on if the message is a request or a response, we'll have a look at both separately.

The request

The request start line is pretty easy to understand, it will tell the server what we are requesting.

GET /path/to/file/index.html HTTP/1.0

Here it tells we're using HTTP GET method, to retrieve resource located at the /path/to/file/index.html URI (uniform resource identifier). It also contains what protocol variant we're using, to be sure we speak the exact same language.

I will come back a bit later on what are HTTP methods, and will refer them as "methods" from now on.

After this, the client will send the headers. Headers are a key-value list of properties, that transmit various informations about the client, it's capabilities, what it's expecting, and the message itself. I won't go over every standard request headers.

Depending on what method is used, the request's body may or may not contain data. For example, if we simply get google's homepage, it won't contain any data. If we're uploading a file, or POST-ing form data to the server, the body will be those data container.

The response

Once server received the request, it will pass it to a handler, which can be about anything. In PHP applications, hosted on an apache server, chances are that apache will call mod_php to handle the request, and build a response it will send back to the client. But that's only one possibility amongst a huge infinite list, which is outside the scope of this blog post.

Anyway, the handler takes an http request as its input, and builds an http response, starting by the response start line.

HTTP/1.0 200 OK

This is a pretty standard response. Server starts by saying which protocol variant it's using, then sends a computer readable status code, followed by an human readable translation of this status code.

A complete list of HTTP status codes is available at many places on the internet, and it's useless to know them all. Googling "http status code" when you're looking for the adequate status should be far enough.

The most important thing to know is the different status code classes, defined by the first digit of the code:

1xx: Informational - Request received, continuing process.
2xx: Success - The action was successfully received, understood, and accepted.
3xx: Redirection - Further action must be taken in order to complete the request.
4xx: Client Error - The request contains bad syntax or cannot be fulfilled.
5xx: Server Error - The server failed to fulfill an apparently valid request.

Some practical direct application of this is when you need to choose between sending back a 404 error and a 500 error. 404 is client's fault. He asked for something that does not exist, and you tell him so. No problem. 500 means that server tried hard to build a response, but something forbid it to achieve its goal. This is a server-side application problem, and you should monitor, and correct this as soon as possible.

After sending the start line, the response, being a faithful HTTP message, will go on by sending the headers. Like for the request, headers will give informations about the server and the message content. You can consider it as the README file that will help the user agent (http client software) to understand the response.

Then, the response message will often contain a body (unless you're using some method requiring not to have it), and the most seen cases are either HTML content, XML/JSON (or similar) response that will be treated by a client-side web application (flash, javascript, ...), or binary content (for a file download, for example).

HTTP methods

What is it? Beside being one word in the request start line, the HTTP method is the client's way to tell the server what kind of operation it wants to perform on the resource requested. The method used in a request have direct implications on what kind of work you can do server-side, and should be choosen carefully (of course, you can break this rule, but it's a very bad idea).

Safe methods

Some methods are said "safe". This means that request is a retrieval operation, and should not do any other work. Notice that "should" does not mean "must", but user cannot be held responsible for breaking something if the method used was "safe".

For example, you should not allow GET methods to create, delete or change files, database records, or LDAP nodes (non exhaustive, of course).

This is the case of GET and HEAD methods.

Idempotent methods

Idempotents methods are those which won't have any side-effect if repeated more than once.

For example, the DELETE method, which asks for a resource deletion, should have the exact same effect if it's called only once on resource A, or if it's called ten times. The overall effect should be the resource deletion (if allowed), not less, not more.

This is the case of GET, HEAD, PUT and DELETE methods.

Non-safe and non-idempotent methods

But of course, some requests needs to take risky and/or non-repeatable actions server side. When an user agent uses such a method, he will be aware of the risks.

For example, POST-ing a comment will create a database record, and if you make twice the same request (unless some protection has been developed to prevent this), you will actually create two database records.

It's the exact reason why browsers ask for user confirmation before repeating a POST request, if user asks for a refresh. It's also the reason why you should redirect to a safe idempotent resource after a successful form submission, to forbid user to be able to repeat request.

This is the case of POST method.

And the real world

All those methods are defined by the HTTP RFC, but the real world is much more restricted than that. In fact, modern browsers only support GET and POST methods, so you should only care about those.

You should just keep in mind that other HTTP methods exist, and for example HTTP extensions like WebDav (which is used by microsoft and their "online folders") use them. A simple way to try out PUT, DELETE, or any other method is to use curl as an http client.

To learn more about specificities of all methods, you can still refer to the original RFC.

Example

The request...

GET /index.html HTTP/1.1
Host: www.example.com

Nothing complicated here, but for curious people (and you should be curious):

example.com is a special domain reserved by the RFC 2606. This domain won't bring any conflict with a real domain, never. You should use it for all your tests and examples.
The "Host" header is required by HTTP 1.1 protocol, and is used by web servers to provide name based virtual hosting of different websites on the same IP address.

and the response!

HTTP/1.1 200 OK
Date: Sun, 24 Jan 2010 22:38:34 GMT
Server: Apache (Boubounetout/Linux)
Last-Modified: Fri, 01 Jan 2010 23:11:55 GMT
Etag: "f3f80-1b6-de1b034b"
Accept-Ranges: bytes
Content-Length: 438
Connection: close
Content-Type: text/html; charset=UTF-8

<html>
  <head></head>
  <body>
    <h1>Welcome</h1>
    <p>Hello, world!</p>
  </body>
</html>

Conclusion

I hope that I'm far from being alone claiming that this is the very basis of any serious web development, and that it will makes your web developer life easier just because you understand the underlying communication language. Yes, HTTP is definitely the web's language, and you should be aware of it.

Ok folks, this will be all for today. But keep tuned, next episodes are already in the pipes.

Thanks to Bertrand Zuchuat for giving feedback and ideas before the article publication.

sfDynamicsPlugin towards 1.0 release

Romain Dorgueil — Wed, 16 Dec 2009 23:45:00 +0100

It's been quite a while since the last big update, and after today's one, I decided to release 0.9.6 version (0.9.5 did not have symfony 1.4 support advertised in package.xml, so I created a new one for this).

Little sum up of new features:

Symfony cache is now used in debug mode too, but it checks assets modification timestamps to know if a recompilation is needed. This timestamp check is not done in non-debug mode, to avoid overhead.
An asset filter chain, fully configurable, extensible and backward compatible is now there. The process is pretty simple: you can write subclasses of sfDynamicsBaseAssetFilter to implement your last great idea about assets filtering. Then, just register it in your app.yml under the section sfDynamicsPlugin/concatenated_javascript_filter_chain (or the same with stylesheet). A full working example is available on the new application configuration page, that describe all app.yml configuration directives. By the way, the default asset filtair chain is exactly the same as before.
To demonstrate this new feature, a sfDynamicsExperimentalClosureAPIJavascriptFilter class has been added. It is an asset filter that calls the Google Closure Compiler API, via an HTTP POST request. Of course, it is not a good idea to do so on a «real» website, but this class is here for demonstration purpose.
Along with the new documentation page, a set of configuration values that were guessed depending on if you are in debug mode, or not, are now configurable via the app.yml of each applications. Of course, the default value is fully backward compatible.
Last feature, which is more polishing than a feature, is that your project won't show up if the sfDynamics module is disabled but required for some assets. Instead, an exception will explain what's missing.

All those features are tested since a few weeks, and a simple cache:clear after upgrading the plugin should keep your project in a nice state. Or at least, I hope so...

The global goal of this release is to tend towards 1.0, by making all existing features configurable and extensible, so that 1.0 branch will be able to remain stable and 100% backward compatible for a long time.

See you space symfonists!

All about backward compatibility...

Romain Dorgueil — Wed, 23 Sep 2009 23:30:00 +0200

Backward compatibility sounds nice, but it's not so easy to respect it in big projects. And the whole interest is on big projects: it's maybe not such a problem if your grand-ma's blog breaks its API on each release, but there would be a revolution (or not?) if win32 API was changing on each ~~enslavement~~ service pack microsoft releases.

Here is a real story case study of a BC break that happened on the PHP language itself.

It's always tempting to say «hey, this feature is so great, and has so little impact on the way it works, it may be cool to include it it the stable branch, don't you think?». Well, it can be cool, if it cannot have any effect on existing projects. But let's think again. How can it have no effect on the existing projects? And if it has no effect, why include it in this branch?

I don't think there is a definite answer to this, as it may have pros sometimes. But most of the time, it will have much more cons than pros. And if you doubt, forget it. Bigger is the project you work in, more it will have users depending on it, and if there is any way users could have used the old "buggy" feature, for sure they did.

I want to expose some real life case that happened recently, on the PHP distribution itself, showing its snowball effect through symfony to real life projects.

Let's have a look at this php bug report. It says «spl_autoload_functions() should return object instances, not class names, when appropriate.»

Two words are really interesting in this bug report. It is "should" and "when appropriate". There is many assumptions behind this. When is this "appropriate"? Why "should" it return instances? I would better rephrase it as «Feature request: spl_autoload_functions() must return object instances, as it is more appropriate than strings containing class names.». The overall formulation is not so much important as the facts that:

it is a feature request, not a bug
the function is currently working, but its behaviour can be changed to a more convenient one.

But it's ok, right? The target version was 5.3 while still no stable releases existed.

Yes it is.

Oh wait, let's read the comments now.

«Thanks for the fix. Do you think, by any chance, we can sneak this into PHP 5.2, or is that impossible?»

The definite answer to this question should be «It is actually impossible. Introducing a behavior change into 5.2 (years) stable release would break backward compatibility.»

And the patch made it to PHP 5.2.11.

Is there any consequences? Yes of course. In fact any symfony 1.3 projects were broken at this stage, because symfony used this behaviour with the reintroduced sfAutoloadAgain autoloader, which checked the return value for strings, and got instances, causing an infinite loop that made apache segmentation fault.

This is now fixed, by http://trac.symfony-project.org/cha..., but was the feature worth the hassle? How many projects can this kind of change break?

So for all you that work on big projects, think well, then think again, then don't do such a change. Usual formula says «With great power comes great responsibilities». I'd add «Great notoriety induce great responsibilities».

Yes millions of people uses PHP, and that's the main reason why stable branch should stay stable. Rock solid stable. And it's the same reason why symfony branches stay stable, as much as possible. And any exception to this always have bad feedback.

(thanks to Pierre Joye for his reminder at http://news.php.net/php.internals/4...)

Note: Software stability does not only mean bug-free. It also means «not changing», and it's the main definition used there. Bugs are annoying, but they can be fixed to get the wanted behavior back, so it's not a problem. And the only wanted behavior of a stable piece of software is the behavior it always had.

Some sfDynamics news...

Romain Dorgueil — Sun, 20 Sep 2009 23:30:00 +0200

Long time no see...

I'm very happy to get more and more comments and feedback about sfDynamics. I sure know it's not perfect, but seeing it's really usefull for other people than me and my colleagues is rewarding.

But I've also been so busy lately that I did very few writing and coding work around it, so I'll write about last months work, and about the future road-map.

I moved all my plug-ins ticketing from their different homes (lighthouse for sfDynamics, and symfony-project's trac for the others) to a brand new redmine instance I set up on trackeet.org. This will greatly enhance how I can see the issue list, prioritize and assign different stuff to people willing to help. Additionally, it helps cleaning up symfony-project's trac instance which suffers from plug-in issues since a long time.
I fixed the easiest issues, and they're packaged into the 0.9.4 release.
Since 0.9.2 release, we don't support anymore symfony 1.1, as the routing system was radically different and way less power-full.
After I released 0.9.4 this week, next step will be a documentation clean-up, and some tutorial writing. Yes, the fourth part is still missing, and it will come to life very soon.
Upcoming 1.0 release will support symfony 1.2, 1.3, and 1.4. The aim for this release is to fix all 0.9 tickets that are not radically new features. A refactoring session before the first 1.0 release will be planned.
Next 1.1 version will at least support symfony 1.4, and if it's possible 1.2 and 1.3 too. But the main goal will be to stick to the next LTS symfony version, which will be 1.4.

I know, no dates were given on this page, but the new roadmap page solves this.

Some more news soon...

The first sfDynamicsPlugin beta is out!

Romain Dorgueil — Mon, 06 Apr 2009 23:48:00 +0200

After a long alpha development stage, I released this morning the first BETA version of sfDynamicsPlugin. But... You may wonder, what is that?

sfDynamicsPlugin is a flexible assets manager for symfony which can be used to manage javascript libraries and their associated stylesheets. It supports packing, and CSS minifying, while keeping the full readable source in development environment.

Finally out

After more than one year of thinkings about the right way to manage dependencies and relations between dynamic components, and a few months of intermitent coding, I'm proud to present sfDynamicsPlugin.

Look at the plugin's page at symfony project

Features at a glance:

JS framework agnostic
Built-in assets cache/supercache
Flexible XML configuration of packages
Dependencies/conflict management
Ease of use within plugins without repeating JS code
Built-in configuration for the most used frameworks including jQuery, jQuery UI, ExtJS, Prototype and Scriptaculous.

Use what you like

To give some more details about the last feature, those are bundled as non-default configuration files, that you may, if you want, import in your project/app/plugin dynamics configuration file.

By doing so, there is absolutely no parsing overhead, as unused configuration files will be, he, unused.

Documentation, documentation and even more documentation!

As documentation is very important, full documentation is available both in markdown and HTML versions, along with a tutorial and a short hello world example.

Reporting bugs, suggesting features

We use lighthouseapp as our ticketing system. Don't hesitate to report bugs, we're looking forward to make this plugin a «YFast» answer to highly dynamic websites.

Ok, show me the issues...

How to render a component in an action with symfony 1.1+

Romain Dorgueil — Thu, 12 Mar 2009 13:34:00 +0100

public function executeBarfoo(sfWebRequest $request)

{

  return $this->renderComponent('my_module', 'my_component', array());

}

This is an attempt to take over the first place on google for the query how to render component action symfony.

Foreign key's onDelete for dummies

Romain Dorgueil — Thu, 10 Jul 2008 23:55:00 +0200

Any modern relational database engine supports the onDelete and onUpdate attributes on foreign keys. Propel and Doctrine of course allows to define it in the schema file (yaml or xml) and I believe it is important to explicitly set it.

Restrict mode

«Better do nothing than something stupid.»

The default behaviour is ON DELETE RESTRICT. This is the most secure setting, so it is normal to have it as default.

If we try to DELETE a record referenced by the current object, the database engine just raise an SQL error. If it was not an error to DELETE this, you will have to start by removing the linked object, or setting the foreign key value to something different.

Cascade mode

«No need to keep obsolete things.»

But our database engines are able to do better. For example, if you have an user's settings table and you delete an user, you may not wan't to keep his settings. You just set ON DELETE CASCADE on user's setting foreign key column referencing the user table, and if a user is ever deleted, all his associated properties will be destroyed.

Along with ON DELETE CASCADE, we usually add a NOT NULL constraint (or required: true), as the existence of current object is directly related to the existence of linked object. This may be wrong from time to time, but it is usually the case.

Set null mode

«We don't rely on this. Just forget it.»

The last behavior is the ON DELETE SET NULL option. It does exactly what it says. If linked object is removed, we set our foreign key value to null.

This the behavior you may want to use for articles having a link to their author for example. If the author is removed from database, we don't want to delete his articles, so we just loose the author information (well ok, this is a simplification, but it basically shows the idea).

Why I think we should explicitly use it

The default database engine behavior is «I don't know how to handle it». Setting it will add power to your database model, while taking profit of your RDBMS features. Not setting it is like saying «I don't know which way I want my database to behave in case we delete a linked object», and that's like saying «I don't know how I want my model to react». Thinking a little to understand which way you want it to work will make you certain you're understanding the behavior you need in your project.

How to set it in your favorite ORM:

schema.yml with Doctrine

Article:
  columns:
    title:   string(255)
    body:    string(4096)
    user_id: integer(4)
  relations:
    User:
      onDelete: CASCADE

PHP model with Doctrine

public function setUp()

{

  $this->hasOne('User', array('local'    => 'user_id',

                              'foreign'  => 'id',

                              'onDelete' => 'CASCADE'));

}

schema.yml with Propel

    data_id:  { type: integer, primaryKey: true, foreignTable: data, foreignReference: id, onDelete: cascade, onUpdate: cascade }

schema.xml with Propel

<foreign-key foreignTable="data" onDelete = "setnull">

    <reference local="data_id" foreign="id" />

  </foreign-key>

Symfony 1.1 is out, and the winner is... 1.2!

Romain Dorgueil — Tue, 01 Jul 2008 23:52:00 +0200

The longly awaited 1.1 version is finally out after long months of development. After doing this, Fabien started the 1.2 branch, and you can take a look at that magnificient revision which for sure opens a new era of symfony developments.

A lot of nice new features are greatly awaited in the next version.

First of all, the admin generator will be completely rewritten, to make a good use of the new form framework. That will for sure open incredible new possibilities and remove the permanent need for hacks to customize your own admin interface (or frontend interface, if you do use admin generation in frontend too). At least, the first one amazed more than one person, and we can be pretty sure that new version will kick asses.

Some people were complaining about Ruby on Rails having a great advantage over symfony, by their deployment tool Capistrano, while symfony only allow to rsync to one server. Hopefully this won't be true for long anymore. For information, Capistrano allows to create real deployment scripts, like "Disable frontend app on this server, make backups of site and database, synchronize, remotely run tests, clear the cache and enable the frontend app". That will easify a lot our projects delivery procedures.

Amongst some other details, the last major point Symfony 1.2 will see is some further decoupling of the technical choices symfony 1.0 gave us, like Propel or Prototype. Prototype and the helpers will still be bundled with symfony, but as a plugin, like Propel is since 1.1. This is very important IMHO, because symfony should never force any technical choice to the teams. But many people complained that helpers was one of the easy and magic things that attract newcomers to symfony. The plugin solution is keeping everyone happy. In the same spirit, symfony 1.2 will bundle the sfDoctrine plugin thanks to Jonathan Wage work to stabilise and manage branches/features.

And for the short term, the unpublished chapters of the form framework online book are still to come too, along with a symfony 1.1 "First project" tutorial.

Long life to symfony :-)

Towards symfony 1.1

Romain Dorgueil — Mon, 16 Jun 2008 23:55:00 +0200

After more than one year since symfony 1.0 was released, symfony 1.1 goes more and more mature each day. Recent RC releases are a proof of it, but many people are still concerned about whether or not they should migrate.

Documentation?

Many people are complaining about the fact it lacks documentation. In fact, it seems that many people fears that because François announced he was leaving the symfony core team, nobody would take care of documenting the project.

But that's something any big open-source project come to see one day, a former or important team member leaves the project, because he or she doesn't have anymore time for it, differ views, change interest, or whatever else.

As he said, no-one is irreplaceable, and new people comes in too, hopefully. Developpers from many countries started recently to fix and translate existing documentation for symfony 1.1, a new mailing list is being created for documentors and the symfony core team is currently putting a great effort on it too.

Documentation!

The symfony documentation page is split by version and language, and the 1.1 english version is getting attention to adapt parts of it in the need. But even without that, if you know symfony 1.0 pretty well, you should not have hard time to updating, as every changed part were because they were judged too complex, or not "clean" enough. The new way to do things is usually easier.

To demonstrate it, people from symfony core team published a little serie of articles on symfony-project.org recently:

Nicolas Perriault published an article about form internationalization, something you could not do to do so easily with symfony 1.0 helpers.
Fabien Potencier demonstrated how handy was the new sf_format feature, to provide the same logical content within different formats, or for instance, different views. He also explained how to customize a project's directory structure, showing the use of ApplicationConfiguration and ProjectConfiguration classes.
Carl Vondrick explained how to use Propel 1.3 to boost your ORM layer performances (be aware though that PHP 5.2 is needed, while symfony 1.1 only requires PHP 5.1.4).
I published two little tutorials about sending emails and using tasks.

And more are to come, of course!

And about forms?

The only part of symfony which needs a bit of learning is the new form framework, which is quite radically different from the 1.0 way to create form. And about this, Fabien recently announced he will publish an entire book about it.

To migrate or not to migrate

Symfony 1.0 is Long Term Support version, which means that symfony team will go on fixing bugs for three years since the original release. If your project is nearly released or already released, I would not bother upgrading, because you would not benefit of symfony 1.1 new features, while you'd suffer the upgrade process.

On the other hand, if your project is very young, I think the time to take the step is now, the official 1.1 release being real soon. You'd benefit of all new features with a very active community and a very reactive development team.

Overview of symfony 1.1 event dispatcher

Romain Dorgueil — Wed, 30 Apr 2008 23:56:00 +0200

As you may now by now, Symfony 1.1 introduces a new powerfull event dispatcher inspired by Apple Cocoa's NotificationCenter. Basically, it allows any entity to "listen" to events, and get a call on the registered callback if this event ever happens.

Symfony 1.1 provides some default events you can listen to, but of course you can create your own events if you need.

Listen to an event

To listen to an event, you need to use the "connect" method on the event dispatcher instance. The first parameter is the event name, and the second is a PHP callable that will get called if the event happens.

$dispatcher->connect('user.change_culture', array($this, 'listenToChangeCultureEvent'));

Create a custom event

To use the dispatcher for your own needs, you just need to define your event name in your project specifications, and send notifications to it. Depending on the behaviour needed, three options are offered:

Simple notifications

The simpliest way is to notify all listeners with the ->notify method.

$dispatcher->notify(new sfEvent($this, 'my.super.cool.event'));

Notifications until something

Sometimes, you prefer to notify all listeners until one says "Ok guys, I handled this one. Don't worry about it anymore".

$dispatcher->notifyUntil(new sfEvent($this, 'my.super.cool.event'));

The first listener that will return non-false value will stop the event chain.

Filtering notifications

The last notifying method is called filtering. You set this up when you want to permit anything to act as a filter on something, meaning any listener can modify a source object.

$dispatcher->filter(new sfEvent($this, 'my.super.cool.event'), $objectToFilter);

Every listener must return the filtered value (or the original object if nothing was done) to pass to the next listener.

Practical use: Register routes in your plugins

One of the first practical applications that came to me was the new way of registering routes in plugins. In symfony 1.0, a coincidence made possible to use the routing in a plugin's config.php but that's not possible anymore in symfony 1.1, so you have to use the event dispatcher. To accomplish this, we're going to set up a routing.load_configuration listener in the plugin's config.php:

$this->dispatcher->connect('routing.load_configuration', array('myPluginRouting', 'listenToRoutingLoadConfigurationEvent'));

Then you just need to create the callback class/method:

class myPluginRouting

{

  /**

   * Listens to the routing.load_configuration event.

   *

   * @param sfEvent An sfEvent instance

   */

  static public function listenToRoutingLoadConfigurationEvent(sfEvent $event)

  {

    $r = $event->getSubject();



    // preprend our routes

    $r->prependRoute('my_route', '/my_plugin/:action', array('module' => 'myPluginAdministrationInterface'));

  }

}

Here we go :-D

Don't be fooled by awkward view.yml js/css positionning syntax!

Romain Dorgueil — Mon, 21 Apr 2008 23:55:00 +0200

Short post today about advanced view.yml configuration (in symfony 1.0, and 1.1) for assets.

You can give additional options to "javascripts:" and "stylesheets:" sections, but the sin equa non condition is to know about the yet very un-documented view.yml assets syntax.

So here it is:

  javascripts: [ jquery: { position: first } ]
  stylesheets: [ mycss: { position: last, media: screen } ]

I don't know if there are others options like thoose available, but taken the 'position' attribute apart, which is extracted to become the $position method argument of sfWebResponse::addJavascript() and ::addStylesheet, any other option is passed in the $options array.

Methods prototypes below:

class sfWebResponse ...

{

  /* ... */

  public function addJavascript($js, $position = '', $options = array());

  public function addStylesheet($css, $position = '', $options = array());

  /* ... */

}

HashBin now available in open-source flavor

Romain Dorgueil — Mon, 17 Mar 2008 23:58:00 +0100

Our first violin missed his plane yesterday, so Kwatuor is still not available in the upcoming unusable buggy pre-alpha (that miss all the functionalities anyway).

But while we're waiting for him to be available, I released HashBin in open-source, so anybody can dive into the code, and help me making it evolve. It still needs many attention, but hey, time is not the most available resource I have, and that's one of the two major reasons to give it to the community. Another one is that there is not so much open source symfony applications, and even less open source doctrine applications. After the doctrine 1.0 feature-freeze announcement, this could be a step to have simple sample applications (I hear little sarcastic laughs in the background...) people could dive in to learn this amazing ORM.

Well stop talking, here is the code.

TRAC web interface: http://trac.dakrazy.net/
SVN DAV repository: http://svn.dakrazy.net/hashbin/trunk/

SVN access is read-only for anyone, if you ever want to contribute, I'll be glad to grant you a commit access either on trunk or branch (still have to make up my mind, but at beginning that's not very important). Just ask me on IRC (hartym@freenode).

What amazing feature will you invent today?

Complex relations population in propel

Romain Dorgueil — Thu, 31 Jan 2008 23:47:00 +0100

Since quite a bit, I've been faced with an annoying problem on every projects I use propel on. Propel builders only generates some specific cases selection methods, which consists of pretty ugly copy paste of the same code to populate the objects, and if your needs are not satisfied by the finite little number of propel handled cases, you'll have to either use pure SQL, or write a custom doSelect method. That seems okay at first sight, but it is not. In fact, you're about copypasting the propel generated method, and that's a rude violation of D.R.Y. principle.

I found no solutions during the two last years, but maybe things will change soon with the new sfPropelImpersonatorPlugin. This plugin is aiming at doing arbitrary object population based on informations provided by propel's introspection methods (DatabaseMap/TableMap/ColumnMap) to link populated objects.

The plugin is currently in very early stage, but is working pretty well for my needs, and I'm looking forward to know what others are thinking about it.

sfForms11Plugin: use symfony 1.1 form/validation framework in symfony 1.0 or non-symfony project

Romain Dorgueil — Mon, 07 Jan 2008 23:32:00 +0100

The new symfony 1.1 form/validation framework is 100% symfony-independant, and though is not limited to the (very) awaited 1.1 stable release. To use it in your own symfony 1.0 projects, you can use sfForms11Plugin. It's content is very thin: it only sets up externals to symfony 1.1 form/widget/validator libraries.

To use it, simply add the following external to your project:

sfForms11Plugin http://svn.symfony-project.com/plugins/sfForms11Plugin

Or check it out from your project base directory:

svn co http://svn.symfony-project.com/plugins/sfForms11Plugin plugins/sfForms11Plugin

Let's try it...

Now you'll be able to define sfForm sub-classes to materialize forms:

class HelloWorldForm extends sfForm

{

  public function configure()

  {

  }



  public function setup()

  {

    $this->setWidgetSchema(new sfWidgetFormSchema(array(

            'name' => new sfWidgetFormInput(),

            )));



    $this->setValidatorSchema(new sfValidatorSchema(array(

            'name' => new sfValidatorString(array('required'=>true, 'min_length'=>1, 'max_length'=>50)),

            )));



    $this->widgetSchema->setNameFormat('hello[%s]');

    $this->errorSchema = new sfValidatorErrorSchema($this->validatorSchema);



    parent::setup();

  }

}

This class define the model of your HelloWorldForm, and you can now use it in your actions:

class testActions extends sfActions

{

  function executeHelloWorld()

  {

    $this->form = new HelloWorldForm();



    if ($this->getRequest()->getMethod() == sfRequest::POST)

    {

      if (null !== ($hello = $this->getRequestParameter('hello', null)))

      {

        $this->form->bind($hello);



        if ($this->form->isValid())

        {

          $this->redirect('@hello?name='.$this->form->getValue('name'));

        }

      }

    }

  }

}

At this point, the only little detail still missing is the view, containing actual form display:

<form method="POST">

<table>

<?php echo $form; ?>

<tr>

  <td colspan="2" align="right">

    <input type="submit" value="Greetings, Mr Computer!" />

  </td>

</tr>

</table>

</form>

That's it! You now have a simple form, self-validating, protected against CSRF attacks and redirecting to some place if values entered matched our sfValidatorSchema.

Tired of spam? Try dkAntispamPlugin

Romain Dorgueil — Sun, 30 Dec 2007 23:49:00 +0100

After last week hashbin's new release, I decided to publish dkAntispamPlugin. That's an early release, and by now it is not very feature-full, but it's doing the job we ask it, and since now, proved efficient on HashBin to make not public the pretty large amount of spam I get on it.

In One week, we got 40 messages with spam_value<10 (all checked, no spam), 14 more with spam_value<20, some of those were not spam but either inconsistent, or URL-full, 97 more between 20 and 50 (100% spam) and 498 more over this, which i'll consider as spam (don't really feel like reviewing all those).

For now, the plug-in only makes some reg-exp check, length check and URL count checks, but I'm planning in adding IP check and refining reg-exps to be less CPU eating. If any of you have anymore ideas to improve it... You're all welcome :-)

At the same time, I refactored sfGeshiPlugin to dkGeshiPlugin, to leave sf prefix for official symfony plugins, so be sure to check the wiki or documentation if you're using it.

Creating custom config handlers in symfony 1.0

Romain Dorgueil — Mon, 24 Dec 2007 07:30:00 +0100

When writing plugins, you often want to do it the symfony way, by putting configuration stuff in YAML files to allow the final user to override your default values in a harmless way.

To do this, the correct way is to create a config handler, extending sfConfigHandler, or its child class sfYamlConfigHandler.

Here is a simple one, just dumping YAML data found in your config file into an sfConfig::get()-able PHP dataset.

class myStupidConfigHandler extends sfYamlConfigHandler

{

  public function execute($configFiles)

  {

    // retrieve yaml data

    $config = $this->parseYamls($configFiles);



    $code = sprintf("<?php\n" .

                    "// auto-generated by myStupidConfigHandler\n" .

                    "// date: %s\n" .

                    "sfConfig::set('my_stupid_config_entry', %s);",

                    date('Y-m-d H:i:s'), var_export($config, 1));



    return $code;

  }

}

We could enhance it a bit, to take advantage of symfony's environments and permit an 'all' (as a default section) and as many environment specific sections as you want. Here is it.

class myStupidConfigHandler extends sfYamlConfigHandler

{

  public function execute($configFiles)

  {

    // retrieve yaml data

    $config = $this->parseYamls($configFiles);



    // get current environment

    $environment = sfConfig::get('sf_environment');



    // merge default and environment specific config

    $config = sfToolKit::arrayDeepMerge(isset($config['all'])?$config['all']:array(), isset($config[$environment])?$config[$environment]:array());



    $code = sprintf("<?php\n" .

                    "// auto-generated by myStupidConfigHandler\n" .

                    "// date: %s\n" .

                    "sfConfig::set('my_stupid_config_entry', %s);",

                    date('Y-m-d H:i:s'), var_export($config, 1));



    return $code;

  }

}

Next step will be to tell symfony which configuration file patterns should be loaded using our class. To do this, add the following entry to config/config_handlers.yml (whether in your app, plugin or module, depending on the scope of your config handler)

config/stupid.yml:
  class:    myStupidConfigHandler

Once this is done, the very little remaining last step is to mak sure you include the compiled yml.php file with the following magic command, that will rebuild it when unexistant or outdated:

require_once(sfConfigCache::getInstance()->checkConfig('config/stupid.yml'));

/* ... */

$stupid_config = sfConfig::get('my_stupid_config_entry');

easy one :-)

Hashbin v3 just went to public beta

Romain Dorgueil — Mon, 24 Dec 2007 06:57:00 +0100

I'm proud to annouce that HashBin v3 is out, using the latest improvements to dkGeshi (old sfGeshi, soon public) and the brand new dkAntispamPlugin, which can give a text a note about its probability of being spam, or junk. If everything goes well with hashbin, and after some required (i guess) tuning to the plugin, it will go opensource to let you take advantage of it.

For thoose who never used it, HashBin is a free PasteBin service, a collaborative debugging tool allowing developpers to share source code snippets. Hashbin is powered by the Symfony Framework and PHP Doctrine ORM.

Using DBMS functions with sfDoctrine

Romain — Tue, 30 Oct 2007 22:11:00 +0100

I recently had a peek on symfony forum, and seen someone asking "How can I make a SELECT count(*) FROM .... with doctrine?". An answer to such a question should be pretty obvious as it's of everyday use, but the question seems to have come to life many times as well on IRC than on the forum/mailing list. Here is my two-cents how-to.

Using builtin DQL aggregate functions

Basically, you can add aggregate functions (functions that operates on a group of records instead of one record, also called GROUP BY functions) to your DQL query the same way you'd do in SQL, provided the fact you're using one of the builtin DQL aggregate functions (COUNT, MAX, MIN, AVG, SUM).

$result = Doctrine_Query::create()

     ->select('COUNT(t.id) cnt')

     ->from('Table t')

     ->execute()

     ->getFirst();



echo $result['cnt'];

Using DBMS specific aggregate functions

If the function you need is in the list, no need to go further. But some functions are DBMS specific, for example MySQL provides a GROUP_CONCAT() function. It would be nonsense for DQL to provide that, as it would not be translatable in some of the other DBMS SQL, but it would also be nonsense to restrict functionalities to the smallest common functionnalities set of every DBMS that Doctrine supports.

The way to go is to change the portablility level of doctrine, to match your needs. As the name implies, you're loosing in portability between the different DBMS, but you're gaining specific functionnalities of yours.

The following code, running in PORTABILITY_ALL mode, will throw a Doctrine_Query_Exception:

Doctrine_Manager::getInstance()->setAttribute(Doctrine::ATTR_PORTABILITY, Doctrine::PORTABILITY_ALL);

    

$result = Doctrine_Query::create()

     ->select('GROUP_CONCAT(t.value) concatedstring')

     ->from('Table t')

     ->execute()

     ->getFirst();

Now remove the Doctrine::PORTABILITY_EXPR bit to this attribute, and you will get the correct result (with mySQL):

Doctrine_Manager::getInstance()->setAttribute(Doctrine::ATTR_PORTABILITY, Doctrine::PORTABILITY_ALL ^ Doctrine::PORTABILITY_EXPR);

    

$result = Doctrine_Query::create()

     ->select('GROUP_CONCAT(t.value) concatedstring')

     ->from('Table t')

     ->execute()

     ->getFirst();



echo $result['concatedstring'];

Extending to other functions

Ok aggregate functions are usefull, but other functions can be very handy too, string functions for example. Doctrine manual tells us that builtin DQL string functions are CONCAT, SUBSTRING, TRIM, LOWER, UPPER, LOCATE and LENGTH.

Doctrine_Manager::getInstance()->setAttribute(Doctrine::ATTR_PORTABILITY, Doctrine::PORTABILITY_ALL);

    

$results = Doctrine_Query::create()

     ->select('LENGTH(t.value) val_len, t.value')

     ->from('Test t')

     ->execute();



foreach ($results as $result)

{

  echo $result['value'] . ' => ' .$result['val_len'] ."\n";

}

This code will display all records' value fields, followed by their character length computed by the DBMS, in PORTABILITY_ALL mode.

Now let's say you want to use BIT_LENGTH MySQL function...

Doctrine_Manager::getInstance()->setAttribute(Doctrine::ATTR_PORTABILITY, Doctrine::PORTABILITY_ALL ^ Doctrine::PORTABILITY_EXPR);

    

$results = Doctrine_Query::create()

     ->select('BIT_LENGTH(t.value) val_len, t.value')

     ->from('Test t')

     ->execute();



foreach ($results as $result)

{

  echo $result['value'] . ' => ' .$result['val_len'] ."\n";

}

This is the way to go again.

No need to say, this extends to every type of functions available in the different DBMS.

Testing Symfony 1.1

Romain Dorgueil — Sun, 28 Oct 2007 12:03:00 +0100

Wondering what symfony 1.1 will look like? Well, I couldn't hold my curiosity neither, so I upgraded one of my websites to symfony 1.1, and I describe here how to setup a box to run both versions. The upgrade process being definitive for a given project, make backups or svn commit before upgrading.

WARNING: Symfony 1.1 is a development version, and should not be used for production. Use it at your own risks.

First of all, i did not want the upgrade to be definitive, I needed a simple way to go back to older version. But SVN would handle this, no problem. On an other side, I needed to keep the two symfony version running on the same box, as other sites are running on it.

My approach to it was to checkout the symfony trunk/lib and trunk/data in /usr/share/pear/symfony1.1 and /usr/share/pear/data/symfony1.1 respectively. This way, i can switch any project I want to symfony 1.1 by changing the config/config.php to use the development version paths.

cd /usr/share/pear/
svn co http://svn.symfony-project.com/trunk/lib symfony1.1
svn co http://svn.symfony-project.com/trunk/data data/symfony1.1

That should retrieve a local copy of the latest development version on your computer.

Upgrading a 1.0 project

To upgrade a project, your first need is to tell the symfony batch script where to find its libraries. Hopefully, symfony's structure permits to set per-project library paths by changing config/config.php. Edit this file and replace the file content by the new 1.1 paths

// symfony directories

$sf_symfony_lib_dir  = '/usr/share/pear/symfony1.1';

$sf_symfony_data_dir = '/usr/share/pear/data/symfony1.1';

You can test your changes were effective by typing symfony in your project directory. You should now see the new namespaced pake tasks that come with symfony 1.1. As in every version, an upgrade pake task that automates the changes you have to make to your project to make it work with the new version is given, and you can do:

symfony project:upgrade1.1
symfony cache:clear

(Note that old symfony cc alias still exists for the cache:clear task)

At this point, I tryed to see if my project would be working, but a nice uncaught LogicException was showing up in development environment, and I had to manually change %project_dir%/apps/*/config/config.php (look at spl_autoload_register line...).

After a little investigation, i found that running the task twice would autocorrect it, and that it was a little problem in lib/task/project/upgrade1.1/sfAutoloadingUpgrade.class.php, so i sent a ticket on Symfony's TRAC.

Now you should have your project up and running.

Generating a new 1.1 project

That's easier than upgrading, but the only (little) difficulty comes from the fact that 'symfony' script will look for 1.0 libraries. For this, you'll create a copy of /usr/bin/symfony to /usr/bin/symfony1.1 (you'll need to be root for this), and change its content to:

#!/usr/bin/env php

<?php



/*

 * This file is part of the symfony package.

 * (c) 2004-2006 Fabien Potencier <fabien.potencier@symfony-project.com>

 * 

 * For the full copyright and license information, please view the LICENSE

 * file that was distributed with this source code.

 */



// project exists?

if (file_exists('config/config.php'))

{

  include('config/config.php');

}



if (!isset($sf_symfony_lib_dir))

{

  if (is_readable(dirname(__FILE__).'/../../lib/VERSION'))

  {

    // SVN

    $sf_symfony_lib_dir  = realpath(dirname(__FILE__).'/../../lib');

    $sf_symfony_data_dir = realpath(dirname(__FILE__).'/..');

  }

  else

  {

    // PEAR

    $sf_symfony_lib_dir  = '/usr/share/pear/symfony1.1';

    $sf_symfony_data_dir = '/usr/share/pear/data/symfony1.1';



    if (!is_dir($sf_symfony_lib_dir))

    {

      throw new Exception('Unable to find symfony libraries');

    }

  }

}



include($sf_symfony_data_dir.'/bin/symfony.php');

You can now run

symfony1.1 generate:project

in a new directory to have a 1.1 project skeleton built there.

Have fun with it, I'll post articles about the new form/validation system and upgrading your doctrine schemas to the rewritten sfDoctrinePlugin (that works both in 1.0 and 1.1) soon.

A new index.php controller for subdomains

Romain — Sun, 21 Oct 2007 23:24:00 +0200

The default behaviour of symfony, is to create one myapp.php and one myapp_dev.php public controller by application, knowing that the first application you create will have its prod controller renamed to index.php (default application). But this behaviour can be easily overriden to take advantage of subdomains.

Here is a little file replacing every public controllers of symfony by an unique index.php, to select the application and environment depending on current subdomain (you can even change it to select depending of the domain though). The aim is to get your different applications on the following domain names:

http://blog.example.com
http://blog-dev.example.com
http://forum.example.com
http://forum-dev.example.com
http://www.example.com
http://www-dev.example.com

The *-dev domains are the development environment version of their matching non-dev subdomains, and thoose will only be available from authorized IPs, to avoid exposing too much information to the public. You only need to get the source given at the bottom of this article and substitute %project_dir%/web/*.php by this unique index.php, then customize it to fit your applications name and your subdomains.

Note that in this example, i have a fallback 'website' app for non existing subdomains, that pass the current subdomain to it through the SF_SUBDOMAIN constant. Using this, you could for example give a homepage to each of your users, or create a white label site for each of your clients... Possibilities are just limited by your imagination.