Symfony-docs: [RFC] Consider using PHP's short syntax arrays in Symfony Documentation

[javiereguiluz]

Symfony documentation boasts a tremendous reach among PHP community. That's why our actions and decisions can produce an immense positive effect. Considering all this, I'd like to propose the use of the PHP's short syntax array in the Symfony Documentation starting from 2.6 version.

Some context information:

• Symfony requires PHP 5.3.3
• Short syntax array was introduced in PHP 5.4.0 (released in March 2012).
• PHP 5.3.x is completely deprecated since 14th August 2014. It no longer receives any update, even for security bugs (view details). In other words, if you still use PHP 5.3, you are putting your company at risk.
• PHP 5.4 no longer receives updates since 14th September 2014 and it will stop receiving security updates on 14th September 2015 (view details).

Pros:

• ['bar', 'foo'] is much more beautiful than array('bar', 'foo').
• The new syntax is so concise that some code listings would be greatly improved.
• It would raise awareness of some of the new features of modern PHP versions.
• ...

Cons:

• It's a non-negligible amount of work for no practical benefit (except for the code beauty and the reasonable code modernization)
• Some PHP 5.3 developers will suffer from copy-pasting code samples that result in errors.
• ...

[wouterj]

To be honest, I can see only cons:

• As you already mentioned it takes much time for almost no effect
• I want code examples to be as easy readable as possible. The Symfony API helps me a lot with this, since it has very verbose and readable method and class names. The [] is not verbose and not as easy to understand as array(). It at least requires a minimum knowledge about newer PHP versions.
• PHP 5.3, while deprecated, still has a lot of support in most unix based servers (e.g. CentOS). I believe there are many users of the Sf2 framework which are still stuck to PHP 5.3. Using [] in the code examples means we are not 100% friendly for them. On the other side, >PHP5.3 still supports the array() syntax, using array() doesn't reduce PHP5.3+ friendlyness.
• PHP core still supports 5.3 and I believe we should always follow the core in the documentation.

[javiereguiluz]

@WouterJ thanks for your comments. I'd like to clarify two things that you mentioned:

PHP core still supports 5.3 and I believe we should always follow the core in the documentation.

That's wrong. PHP 5.3 is completely deprecated. It doesn't receive ANY update, not even security updates. Total and completely deprecated.

It at least requires a minimum knowledge about newer PHP versions.

That's wrong. The short array syntax was released in 2012 and PHP 5.4 is not only "the future of PHP" but its past. PHP 5.4 is also deprecated since September 2014 (although it will still receive security updates for a year).

[wouterj]

That's wrong. PHP 5.3 is completely deprecated. It doesn't receive ANY update, not even security updates. Total and completely deprecated

Sorry for the confusion, I meant Symfony core.

[Nek-]

If Sf still supports outdated version (with all debate that can be, and I'm personally against support of deprecating things when there are potential security problem), it does not force the documentation to be outdated.

In facts using [] in the documentation can make people realize that their php version is deprecated. If they know, it will encourage theme to upgrage.

I think this is a very very good idea ! :+1:

[wouterj]

it does not force the documentation to be outdated.

Using array() is as valid PHP5.6 as [] is. Using array() doesn't make your code/documentation outdated.

[Nek-]

Of course this is totally valid (I didn't said the documentation will be deprecated ^^), but the good practice tends to be brackets usage. Not using it make the doc a bit "oldschool".

But anyway this is not the main point here.

[javiereguiluz]

Closing this issue because opinions are very divided. We'll reconsider this issue when 3.0 is released and some of its code starts using the short array syntax.

[ghost]

@javiereguiluz It's released now. I think short syntax arrays are better.

[javiereguiluz]

@JHGitty that's true ... but the decision won't change for now. Symfony won't use the short syntax neither for its code nor for its documentation.

[ghost]

Okay .. :( Thanks for your fast reply!

[stof]

@JHGitty we have to support Symfony 2.8 for the next 3 years, merging its codebase with the 3.0 one each week. We don't want to handle conflicts between these branches all the time just because of a syntax change for arrays. This is why we made the decision to avoid using it (but your own code can of course the short array syntax)