CakePHP 3.0 Namespace

cake3ns.markdown

CakePHP Core

• Core namespace: Cake
• Namespace will follow the directories, ie. Cake\Cache\Engine\ApcEngine, Cake\Controller\Controller
• View files don't need namespaces
• Basic functions will not be namespaced as well
• Use the class loader defined by the PHP Standard Group, see https://gist.github.com/562509
• Suffixes will not be removed (ie. HtmlHelper will be Cake\View\Helper\HtmlHelper instead of Cake\View\Helper\Html)
• Remove App::uses()
• Remove filemap
• Support full class name in configurations, ie. DebugKit\Controller\Component\ToolbarComponent instead of DebugKit.Toolbar

Plugins

• Plugin must use namespaces
• The default top level namespace will be the same of plugin name, but can be configured a custom namespace using the Plugin::load()

Applications

• Application must use namespaces
• Include in core.php a configuration to indicate the application namespace (empty for global)

Suffixes keep the classes more readable and avoid some confusions like Post class is my model, controller, helper, ... or is it all depending from the scope?!

We can look in which namespace the class is.
Maybe I'm wrong but IMO avoiding suffixes is more cleaner. In this case we don't have twice the word "Helper", "Model", etc...

I am with @kamui545 in this one. I would prefer without suffixes too, in any way we can have:

use namespace\to\app;
$post = Model\Post::create();

Another advantage is that we don't have to do a substr() to get the real class name of a controller, model etc... Eg: Controller::__construct();
It's a small improvement but I think it may be usefull in other cases.

What do you think about an RFC on lighthouse ? or is this definitive ?

One benefit of the suffixes is fuzzy finding by filename is moderately easier, as there won't be multiple Post/Posts files.

I'm with juan regarding suffixes, for classes that need it. Specially when using the "use" keyword at the top of the file, would also make it easier for aliasing and also easier to read.

Pop quizz: I have declared the namespace for the class "Form" at the top of the file, and later I do "new Form". The class refers to:

a) Helper
b) AuthComponent adapter
c) A unknown custom lib
e) none of the above

Looking at the beginning of the file is not permitted.

@lorenzo: Perhaps its d? :P

But I think it depends. Following CakePHP convention I would say:
a) Can't be a Helper, the way to access a helper is $this->HelperName from a view file
b) Adapters are handled by the Component. Why would you do "new Form"?
c) Probably the right answer
e) its one of the above

I prefer no suffixes. I don't see the value in using namespaces /and/ class suffixes.

Ambiguity is not likely to be the common case - it should be the exception. You can easily do use Foo\Model\Bar as BarModel but IMO you shouldn't be forced to alias classes to be able to type less in your application code.

Models should never be suffixed, they are the closest to your business ideas you can get, so thy should be named as close as what you want to represent. @AD7six, take a look at the other frameworks in 5.3, there is a LOT of ambiguity, just because they though it was cool to have super short class names.

And I don't get the "type less" argument, the namespace is written just once in the file, when declared or when imported with "use". I you are going to type the namespace every time you use the class in the same file, then you have another problem.

My concern is not just about "collisions" it about making the code self-explanatory when you read it, without having to go back and forth to the top of the file to figure out what a class really is.

We should also keep in mind that for many classes the classname will rarely be typed. Behaviors, helpers, and components (all currently suffixed) are rarely used with a suffix as the ObjectCollections responsible for loading them trim off the suffix.

Off of mark's comment - assuming an object collection is still used - rarely being typed (or perhaps more specifically - rarely typing new Class() ) means to a large extent the problem that suffixes solve when applied to 5.3+ doesn't exist. It also means suffixes won't hurt because you won't be typing them either. What we're really discussing therefore is if we want Foo/Controller/BarController.php or Foo/Controller/Bar.php. Personally - I'd prefer to have to type less.

Mark's point is very valid, most of the class names are not going to be typed by the user, so that should not be a big concern. What I do not want to see in CakePHP is having to address the full name of a class inside the core like 'new \My\Long\Namespaced\Class()', that will be a lot of typing to do. Also, I'm very happy with the fuzzy file search now, since I don't confuse anymore the Model with ModelTask, as I did hundreds of times when working on 1.3 (and stupidly started editing Security instead of SecurityComponent). Going back to that would be a little sad.

For plugins we should use author/creator name as top level in the namespace. For eg. if i want to use simultaneously CakeDC's Search plugin and ADmad' Search plugin (with all classes named similarly), it would be possible only if author name is top level in namespace.

@ADmad won't that create an issue in the filesystem as well? Both plugins will be expecting to be in app/Plugin/Search/. We'd have to add even more configuration to allow custom filepath -> namespace pairs. And additionally require more namespaces. I think its worth asking how often we expect this to happen and whether or not this can be solved by ignoring the problem. If the community just chooses more unique names for things, then there is no need for all this additional configuration, namespace & filepath resolution hijinks. It feels like we're trying to solve a people/communication issue with computers.

@markstory Well if were to include author name as top level in namespace, then as per PSR-0 wouldn't the folders be app/Plugin/CakeDC/Search and app/Plugin/ADmad/Search ?

@ADmad I implemented and forgot to update this document. You will be able to put the files as you described, but you will have to setup the custom namespace in the Plugin::load(). Ie, Plugin::load('ADSearch', array('namespace' => 'ADmad\Search')) will load files on APP/Plugin/ADmad/Search/....

So you can use like $components = array('ADSearch.PrgComponent');.

I will update the document with that.

@jrbasso That takes care of two plugins with same name. Will that also allow me to simultaneously load PrgComponent from both the Search plugins? If that's the case then I am happy :)

Yes, you can use the className option available in the collections, so you can load simultaneously like that:

public $components = array(
  'ADPgr' => array(
    'className' => 'ADmad\Search\Controller\Component\PgrComponent'
  ),
  'CakePgr' => array(
    'className' => 'CakeDC\Search\Controller\Component\PgrComponent'
  )
);
// use $this->ADPgr and $this->CakePgr

Silly me, totally forget we already have classname aliasing.