This should be merged into the 2.5 branch.

@Rootie Can you also update the call in/cookbook/validation/custom_constraint.rst?

Actually, the doc should show code compatible with both the 2.4 and 2.5 API. Otherwise bundle authors might not maintain compatibility with both (for projects, you can skip this need as you control which API is used).

Seesymfony/symfony#11587 for the way it is done in Symfony

That's a valid point. But I think that could well be done in a new cookbook chapter. We can then add a reference to this entry here.

@Rootie You would also have to add aversionadded directive which explains the deprecation.

Well, if you only show the 2.5 API here, I'm sure people will create bundles incompatible with one of the API. Symfony currently supports 3 validation APIs:

• 2.4: the 2.4- API, which is still there for BC
• 2.5: the new backward incompatible API introduced in 2.5
• 2.5-BC: the 2.5 API with an additional BC layer reproducing the 2.4 API, but usable only for PHP 5.3.9+ (due to a limitation in previous PHP versions).

The default config is to use 2.5-BC for PHP 5.3.9+ and to use 2.4 for old 5.3 versions (we cannot switch automatically to the incompatible API).
This means that if your bundle uses the 2.4 API (addValidationAt being part of it), it will be broken for people opting explicitly for the non-BC API. On the other hand, if you use the new API (buildViolation), it will make your bundle incompatible with the default config of FrameworkBundle for some PHP version, and will also make it incompatible with the 2.3 LTS.
given that writing code compatible with both APIs is not that complex, it is better to write the documentation the right way

Well, if you think it's not too hard, we should do that. I didn't dive that deep into the changes. Nonetheless, having a section explaining all differences in detail seems valuable to me. But that's out of scope of this pull request and#4094 also addresses that.

Just noticed: there's also an older pull request for this (#4056).

@stof Thank you very much for the detailed description - I was hoping someone could help us understand this.

But wow, this is a bit nuts! :) To simplify things, we'll obviouslyonly be making changes to the 2.5+ version of the docs. 2.4+2.3 use the 2.4 API, so they'll stay the same.

For 2.5+, I agree with Stof that we should show both. But instead of writing code that's truly compatible with everything, I think we should just show both with comments saying which is which:

// If you're using the new 2.5 validation API (you probably are!)$context->buildViolation('This name sounds totally fake!')    ->atPath('firstName')    ->addViolation();// If you're using the old 2.4 validation API$context->addViolationAt('firstName','This name sounds totally fake!',array(),null);

For a normal user, telling them to have anif statement with some duplicated code in order to support both API's is just a bad experience. But I think this accomplishes it as well as we can. Like@xabbuh mentioned, I think we should have a cookbook article explaining what's going on with all of this :).

Thoughts?

Meanwhile i also updated custom_constraint.rst and added a versionadded hint.

To me having code that is already marked as deprecated in the referecne seems a little strange.
A new cookbook entry sounds good to me too. The two files modified here can reference to that entry with a note like "Public bundles should also support the old api. For details see ."

@Rootie The 2.4 API is marked as deprecated. But given that it is still possible to have a project using the 2.4 API only (because the 2.5-bc API requires PHP 5.3.9+ while Symfony allows 5.3.3+), an open-source bundle must still be compatible with it.

and yes, I agree we could keep the instanceof check to support both together in a cookbook article (but we should add a warning linking to it)

@Rootie Thanks for those tweaks. Can you also update the code to show the old and new syntax. See Stof's comment about it - wemust show the deprecated version because if you're not on at least PHP 5.3.9, then you can't easily upgrade your code to the 2.5 API (since the 2.5-BC API requires PHP 5.3.9+).

Thanks!

Hey@Rootie

I've taken your commit and moved it to#4233 so we can summarize all the changes. Thanks for starting this! I'll close this PR.