PHP Naming Conventions

[Bernhard Schussek]

Splitting this off of the "[Cache][Survey] Pool or Cache?" topic.

2014-03-28 19:36 GMT+01:00 Jeremy Lindblom <jerem...@gmail.com>:

Some people focus on the contextual class name, or the name you use to reference it once it is imported into your scope.

> use Psr\Cache\PoolInterface

> ...

> if ($foo instanceof PoolInterface)

People that are more concerned about this tend to have repetition in their FQCNs:

> Psr\Cache\CachePoolInterface

Since the contextual class name is more explicit this way.

However, I don't think the PHP community has reached a general consensus on what is the preferred way.

I think this is due to PHP's non-namespaced history. For example, what used to be called Zend_Filter_Encrypt is now called Zend\Filter\Encrypt. This was a logical step, but neglected the fact that we now write:

new Encrypt();

Without namespace, the name doesn't make sense anymore.

I'm not sure whether it makes sense to release a PSR for this. What we need is a brain shift away from PEAR to proper namespaced code.

Cheers :)

Bernhard

--

Bernhard Schussek
Blog: http://webmozarts.com
Twitter: http://twitter.com/webmozart

[Marco Pivetta]

This will likely just open a can of worms.
You can see the discussion that went on at http://verraes.net/2013/09/sensible-interfaces/ to have just a very very small example on why this will (probably) make everybody unhappy: both who is for the suffixes/prefixes and for who isn't.

I would simply avoid this particular discussion about naming style as a part of the PSRs simply because both approaches make sense in their own way.

Cheers,

Marco Pivetta

http://twitter.com/Ocramius     

http://ocramius.github.com/

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAHjTTqOsYBWB6kFyaGWj6H8mMNgR5Vnpe_g%3DrknEeLbx3uByNg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[Bernhard Schussek]

You are probably right.

However, I think this might well go into a bylaw so that we at least avoid this discussion within FIG.

--

Bernhard Schussek
Blog: http://webmozarts.com
Twitter: http://twitter.com/webmozart

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CADyq6sJSPVydP%2B72Ppm%3DRNANb%3DunH_Lx0fWZ56Tbz41m%3D0%2BdCA%40mail.gmail.com.

[Crypto Compress]

Am 29.03.2014 03:53, schrieb Marco Pivetta:
> This will likely just open a can of worms.
> You can see the discussion that went on at
> http://verraes.net/2013/09/sensible-interfaces/ to have just a very
> very small example on why this will (probably) make everybody unhappy:
> both who is for the suffixes/prefixes and for who isn't.
>
> I would simply avoid this particular discussion about naming style as
> a part of the PSRs simply because both approaches make sense in their
> own way.

Naming is very important and divisive topic for interoperability group.
No question it deserves own PSR. Maybe this thread is a good start?

<?php

namespace Psr\Cache {
interface Repository {}
interface Collection {}
interface Item {}
}

namespace MyProject\Cache {
use \Psr\Cache;

class Tag implements Cache\Item {}
class Tags implements Cache\Collection {}

class Level1 implements Cache\Repository {}
class Level2 implements Cache\Repository {}
class Level3 implements Cache\Repository {}

class Preheat {
public function __construct(Cache\Repository $repo) {}
public function dump() {}
public function restore() {}
}
}

[Alexander Makarov]

That's very tough topic. It popped up many times in Yii 2.0 naming discusssions and resulted in nothing particular i.e. we're still checking if the name makes sense in each separate case.

[Don Gilbert]

This is something that we struggled with in the Joomla Framework as well. The old-style "poor man's namespaces" didn't translate into useful classnames after the conversion. But we ended up doing a massive renaming before 1.0, so it all turned out ok. We now have descriptive class names, and I'm super thankful for that. It really helps retain context without having to use namespace class aliases.

[Karsten Dambekalns]

Hi.

On 29.03.2014, at 18:14, Crypto Compress <cryptoc...@googlemail.com> wrote:
> Naming is very important and divisive topic for interoperability group. No question it deserves own PSR. Maybe this thread is a good start?

A really hard topic.

> namespace Psr\Cache {
> interface Repository {}
> interface Collection {}
> interface Item {}
> }

In Flow we always suffix interfaces with “Interface” and whenever we work with Doctrine I am confused by the fact that Collection is an interface ;) - so we’d probably never adopt such a naming convention.

For us it is

* FooInterface
* BarManager
* AbstractSomething

i.e. always prefix abstract classes with “Abstract”, suffix interfaces with “Interface” and never use "non-speaking” names standalone (e.g. Manager, Service, Repository).

Other than that common sense always wins ;)

Regards,
Karsten

[Alexander Makarov]

We're also using -able suffix sometimes like Arrayable (same as PHP's Serializable).

[Phil Sturgeon]

This topic is not about suffix v prefix or adding 'able instead of Interface, this is about the tricky situation where package namespaces are called something like "Cache" then a class inside that package namespace is called "Client" or whatever. What client? 

Another example from his post:

Zend_Filter_Encrypt is now called Zend\Filter\Encrypt.

new Encrypt();

That might be a little tricky. Right? 

Either way, that is what Bernhard was asking about, not the same old interface discussions. 

[Jeremy Lindblom]

To give another example, we are kind of asking something like this:

Which would you rather see in your code?

A. use Foo\Cache\CacheItem /* ... */ $item = new CacheItem();

B. use Foo\Cache\Item; /* ... */ $item = new Item();

C. use Foo\Cache\Item as CacheItem; /* ... */ $item = new CacheItem();

D. use Foo\Cache; /* ... */ $item = new Cache\Item();

E. or something else

--
Jeremy Lindblom
PHP Software Engineer at Amazon Web Services

Co-author of the AWS SDK for PHP

Co-organizer of the Seattle PHP User Group

@jeremeamia | http://webjeremy.com | https://github.com/jeremeamia

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/a027063e-452f-448a-ba1c-5ac790e3c8e6%40googlegroups.com.

[Don Gilbert]

I would choose A first, D second. But only D if it was impossible to change the class naming structure to fit A. And since we haven't even released anything yet, I'd say for sure A.

[Chuck Burgess]

The convention I had settled on personally was that any use alias that I make would always be a lowercased indicator of the real namespace, at least given some useful context in that given file.

To fit the current discussion, for all those options, my usage would be thus:

A. given Foo\Cache\CacheItem as the FQCN:
use Foo\Cache as cache;

$item = new cache\CacheItem();

B. given Foo\Cache\Item as the FQCN:

use Foo\Cache as cache;

$item = new cache\Item();

C and D would not apply in my case, because the actual FQCNs are the same as A and B.

I have no particular preference myself between CacheItem and Item, but in light of this convention of mine, Item alone still has enough context for me to know it's a cache\Item.

CRB
about.me/ashnazg

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CALDVup%2BfiYzy5V-xumat43zMpP7iEESHTgGMY_ZhtRW7ft6wOw%40mail.gmail.com.

[Chuck Burgess]

A corollary to this convention is that I never alias a class itself... only a namespace.  Thus, I would never do:

use Foo\Cache\Item as CacheItem;

CRB
about.me/ashnazg

[Chris Wilkinson]

A.

Class names must make sense on their own. Namespaces are for grouping.

(I do find myself doing the likes of 'use Symfony\Bundle\FrameworkBundle\Templating\EngineInterface as TemplatingEngine' where sensible names haven't been used. My class takes a templating engine, not any old engine!)

[Paul Dragoonis]

This is a very similar approach to what's happening in PPI Framework.

If something has a singular name such as Library\User\Manager, we will not do: "new Manager()" we will always use *class aliasing* so:

use Library\User\Manager as UserManager;

$um = new UserManager();

I can see a little merit in this discussion but I'm unsure it requires bylaw/spec modification.

Common sense wins, if you need to alias to make something more clear, then go for it.

 

Regards,
Karsten

[Phil Sturgeon]

I don't think people are suggesting we actually Spec or Bylaw this, but a conversation seems like something that could benefit the PSR-6 efforts. We're all doing different things it seems, which doesn't make life easy.

[Aaron Scherer]

In that particular situation area, I've always gone with something like

Zend\Filter\EncryptFilter

 

new EncryptFilter;