How to convert to ProcessWire 3.0 namespaces?

[thetuningspoon]

I've built a custom (hierarchical) MVC-like framework for the front-end of our PW sites. I have not worked with PHP namespaces very much before, and when I upgraded one of our projects to PW 3.0 as a test, the automatic conversion process (through the new template compiler) failed to produce a working result.

I would like to turn off the template compiler and manually update my templates/framework to work with namespaces. Is there a straightforward explanation somewhere on what steps need to be taken to upgrade templates and classes to work natively in PW 3?

[AndZyk]

If you don't want to use the template compiler, all you need to do is to add the ProcessWire namespace on top of your template file:

<?php namespace ProcessWire;

Here you can find the blog post about this topic.

[thetuningspoon]

Thanks for the link, AndZyk. I did try adding the namespace line, but was still having problems. When I get back into the code I can provide more specifics.

[thetuningspoon]

Ok, I got it working. The problem was with my autoloader, which wasn't accounting for the namespace portion of the class name. Also, there were a couple places I was instantiating built-in php classes, and I had to add a "\" before the class name to specify the global(root?) namespace.

I'm still not convinced this namespace thing is worth all the trouble. Seems like a bunch of extra effort to achieve the same effect as using longer class names, but I digress...

[DaveP]

I'm still not convinced this namespace thing is worth all the trouble. Seems like a bunch of extra effort to achieve the same effect as using longer class names, but I digress...

+1 for that. 

[LostKobrakai]

As soon as one is using essentially any external php library you've to deal with namespaces and it's really not that complicated after some time using them. At least from my experience.

[qtguru]

Ok, I got it working. The problem was with my autoloader, which wasn't accounting for the namespace portion of the class name. Also, there were a couple places I was instantiating built-in php classes, and I had to add a "\" before the class name to specify the global(root?) namespace.

I'm still not convinced this namespace thing is worth all the trouble. Seems like a bunch of extra effort to achieve the same effect as using longer class names, but I digress...

Nope Namespace is a must, it's the way to ensure modules don't collide and none of us want to be involved in loading file manually. and also 3rd Party Library support. don't worry I will write an article about this and why Processwire needs this

[thetuningspoon]

What if the namespaces collide?

[LostKobrakai]

This might happen, but should actually be a rare edge-case, especially as namespace and classname must collide to be an issue. The difference is that the chances of two libraries having a User class is certainly much higher than both having a ProcessWire\User class. 

[qtguru]

This might happen, but should actually be a rare edge-case, especially as namespace and classname must collide to be an issue. The difference is that the chances of two libraries having a User class is certainly much higher than both having a ProcessWire\User class. 

 He explains it well, 

[thetuningspoon]

It depends how unique your namespace name is. I guess what I'm really wondering is why ProcessWire\User is preferable to ProcessWireUser. Neither one is any more or less likely to conflict. Adding a slash between the names and the extra bit of complexity that comes with having to work woth namespaces doesn't change the likelihood of a conflicting name one iota. But maybe I'm missing some other advantage.

I'm not saying that PW shouldn't support namespaces. If that is where the php community is headed then I think PW should be there with it. I'm just not convinced that the idea is a good one to begin with.

[szabesz]

Introducing a (usable) standard is always a good idea. You might use ProcessWireUser, but what if my convention was WireUser_Process? How can my fellow programmers figure out my intention easily, just by taking a quick look at my code? The other advantage is "reminding" the developer to actually use "prefixing" which we tend to forget otherwise.

EDIT: not to mention the possibility of organized libraries with autoloading...

Edited April 17, 2016 by szabesz

[LostKobrakai]

The simplest answer is that classnames cannot be shortened, but namespaces can. The ProcessWire namespace is not the best example here, because it's still not to long, therefore I'll use some namespaces from the flysystem package.

use Aws\S3\S3Client;
use League\Flysystem\AwsS3v3\AwsS3Adapter;
use League\Flysystem\Filesystem;

$client = S3Client::factory($credentials);
$adapter = new AwsS3Adapter($client, 'your-bucket-name', 'optional-prefix');
$filesystem = new Filesystem($adapter);
[…]
if(!$filesystem instanceof Filesystem) die();

// vs.

$client = Aws\S3\S3Client::factory($credentials);
$adapter = new League\Flysystem\AwsS3v3\AwsS3Adapter($client, 'your-bucket-name', 'optional-prefix');
$filesystem = new League\Flysystem\Filesystem($adapter);
[…]
if(!$filesystem instanceof League\Flysystem\Filesystem) die();

Now imagine you'd need to use these classes 15 times in a file. You'd have to write them 15 times in their full glory without namespaces. With them you can always use the shortname of a class in your code, which keeps it readable and even if the shortname would collide you can do this to use an alternative short name for one of those in the file. (Alternativ naming does even work if classes don't clash.)

<?php namespace kobrakai;

use ProcessWire\User as PwUser;

class User extends PwUser {}

The use statement is super useful because you hardly need conflicting classes in a single file. Therefore you declare once which class you want to use in a file and never care about it later on. With longer classnames you need to constantly care about it trying to remember that one special long class name.
 
The next benefit is the "folder" structure namespaces give yourself. As long as classes are in the same namespace you don't actually need to do anything besides the namespace declaration once. Only accessing classes outside the current namespace does need you to specify the namespace in any way.

> kobrakai
  > Form
  > ImageGallery
  > …

<?php namespace kobrakai;

use DateTime;
use ProcessWire\PageArray;

class Form {
  public function ImageGalleryButtons(PageArray $options) { // Namespace needed
    $g = new ImageGallery(); // No namespace needed
    […]
    $date = new DateTime(); // DateTime is a core class, therefore also another namespace (root)
  }
}

Like you've seen above namespaces are great to extend classes. If I want to change a already existing file, which does use ProcessWire\User to use my own implementations (with maybe some additional business logic) I just change the use statement and I'm done. The file is still as readable as before. There were 100% no accidents in trying to search/replace classnames. We are still talking about users.

<?php

use kobrakai\User; // from: use ProcessWire\User;

$u = new User;
$u->name = 'my-user';
…
if($another_u instance of User) $u->friend->add($another_u);
…

[qtguru]

also you can always rename namespace use NameSpace\App as EatMe

[thetuningspoon]

Thanks for your comprehensive and educational reply, LostKobrakai. I didn't mean to cause such a stir. As I get more experience with namespaces I'm sure I will come to appreciate them better. I'm just venting a little because right now they're solving a problem for me that hasn't needed solving, and doing it in a way that I don't find intuitive.

[asbjorn]

I am relatively new to namespaces. But although ProcessWire 2.x doesn't support it. Can I add

<?php namespace ProcessWire;

to the top of php files while running ProcessWire 2.x? Without anything breaking.

The reason I am asking is that I am thinking of modifying a small scale site with no development environment live, and preparing the template files (if possible) would be my first step.

[LostKobrakai]

Just do nothing and everything should work fine in 2.x as well as 3.x. One has only to care about namespaces if it's explicitly wanted/needed.

[Doc]

Hi,

Just landed here through "namespace" keyword search.

Do I need to add "<?php namespace ProcessWire;" at the beginning of my template or include files ? I don't have any php classes but maybe I will add some modules which use them... 

Thanks

[szabesz]

1 hour ago, Doc said:

Do I need to add "<?php namespace ProcessWire;"

Hi,

Short answer: It is recommended.

Some TL;DR for you  :

https://processwire.com/blog/posts/processwire-3.0.21-and-2.8.21/#news-for-processwire-2.x

https://www.google.hu/search?as_sitesearch=processwire.com%2Ftalk&as_q=migrate#q=namespace+site:processwire.com%2Fblog

[Doc]

Thanks @szabesz