Problem/Motivation

Drupal 8 now contains an increasing number of PHP namespaces. Currently the API module does not support them in any way, and it needs to.

Here are references to how namespaces can be used in code, and what to understand from various namespace-related syntax uses:
http://us.php.net/manual/en/language.namespaces.basics.php
http://us.php.net/manual/en/language.namespaces.importing.php

Proposed resolution

The API module should support namespaces in the following ways [note: this list is a work in progress, and may be updated]:

  1. Class pages, member pages, and class listing pages should show the namespaces the classes belong to.
  2. Linking and references for classes and class members should be namespace-aware. For instance, if class A extends class B, or instantiates a new object of class C in its code, and there are namespaces involved, then we should recognize that B/C are in those namespaces.
  3. If namespaces are put into files ad-hoc (e.g., $x = new \name\space\XyzClass();, recognize that for display (currently I think the \ character is getting lost in code display), as well as for purposes of linking and making references.

Note that "linking" here refers to the way the API module, in both code and documentation, turns function and class names (etc.) into links. And "references" refers to the reverse process: building the "N functions call this" links/pages, as well as other constructs like class hierarchies, which methods override other methods, etc.

Remaining tasks

- Finalize the definition of what "support namespaces" means for the API module (see Proposed Resolution section above).
- Modify the Grammar Parser module so that it parses namespace and use declarations in files, and so that it can deal with namespaces being used ad-hoc on code lines. See issue #1704294: Add support for use and namespace statements and expressions
- Modify the API module so that it supports namespaces in the way that has been defined.

User interface changes

TBD.

API changes

TBD.

Original report by jhodgdon

Drupal 8 now contains an increasing number of PHP namespaces.

Currently the API module does not support them in any way.

This issue is to figure out how the API module should support them, and then to make that happen.

Note that the Grammar Parser module also doesn't support namespaces yet, and that will probably be a prerequisite. See issue
#1704294: Add support for use and namespace statements and expressions

CommentFileSizeAuthor
#8 api-namespaces-pass1.patch123.96 KBjhodgdon
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

Just to elaborate on this...

Right now the API module doesn't understand namespaces at all, and I think the \ characters in namespace lines are not being displayed. Which is I am usre not the right thing.

Also, since it doesn't understand namespaces, all classes with the same final name are created equal, so if you have in one namespace:

class Foo extends Bar {
   function foo_bar() {
       $x = new Baz();
   }
}

etc. it has no idea that Baz and Bar are specifically (maybe?) in this (or another) namespace, so in making links and references it will just find any old class named Baz or Bar. It will need to be smarter, but I'm not sure exactly how smart.

jhodgdon’s picture

One idea mentioned by pounard on #1507828-45: [policy, no patch] Revised standards for class naming within namespaces:
On the Classes listing page, list classes by their fully-qualified names (including namespace).

I think this is a good idea, and it's somehow consistent with what we're currently doing on the Files page (listing files by directory).

jhodgdon’s picture

Version: 6.x-1.x-dev » 7.x-1.x-dev
Priority: Major » Critical
jhodgdon’s picture

In conjunction with #1541318: Database error in api_shutdown() function (once it's committed, which should be shortly), I added a bunch of @todo notes to the code where I think namespaces will come into play. Specifically, in regards to having multiple classes with the same name in different namespaces, and making intelligent links and references.

jhodgdon’s picture

I just added an issue summary here, and am seeking feedback from the core Drupal devs on whether this proposed resolution is what we want/need.

jhodgdon’s picture

Issue summary: View changes

add an issue summary

jhodgdon’s picture

Issue summary: View changes

clarification

jhodgdon’s picture

Issue summary: View changes

add links to php.net explanations

jhodgdon’s picture

Assigned: Unassigned » jhodgdon

I'm working on this now. The grammar_parser support seems straightforward; the hard part is figuring out what to do with the information.

jhodgdon’s picture

I ran into this bug (or support need?) in Grammar Parser:
#1899502: PHP use statements with multiple classes

Other than that, I pretty much have the first pass of this working. I need to write some tests for the new functionality (I have the old tests passing again, after massive code refactoring to use namespaces), and a few more things... should be committing the new code sometime early next week!

jhodgdon’s picture

FileSize
123.96 KB

Here's the patch up to this point, just so it is somewhere other than just my machine (would hate to lose several days of work on this). LOTS of changes... several functions in api.module have new arguments added, etc.

jhodgdon’s picture

Status: Active » Fixed

I just made a commit (well, two actually, since the first one was missing files) to add this support to the API module.

Lots of api_* functions had their signatures changed, and the default Views that the API module is using for listing pages changed as well, with incompatible arguments/contextual filters. So, if you are relying on any API functions in a dependent module, or have changed the default views, your site may break. Sorry.

jhodgdon’s picture

Oh, and to run this you need the patch from:
#1899502-6: PHP use statements with multiple classes
on the Grammar parser module.

jhodgdon’s picture

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.

Anonymous’s picture

Issue summary: View changes

update grammar parser issue link