[documentation] Workflow diagram for Drupal's core index.php

Mon Nov 5 21:48:59 UTC 2007

Issue status update for 
http://drupal.org/node/172562
Post a follow up: 
http://drupal.org/comment/reply/172562#comment-form

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  jp.stacey
 Reported by:  jp.stacey
 Updated by:   KentBye
 Status:       active

I just wanted to post a follow-up to this thread announcing that I
released the Visualize Backtrace module [1], which is a way to
automatically create a graph of the full function call trace for any
given page load.

My hope is that some people from this thread uses it as a tool to
generate more high-level flowcharts like the one that jp.stacey posted.

There is an introductory screencast [2] that demonstrates the visualize
backtrace module (be sure to expand to full screen mode). And this audio
presentation [3] from a Drupal Camp explains it in more detail.

[1] http://drupal.org/project/visualize_backtrace
[2] http://blip.tv/file/431841
[3]
http://blip.tv/file/get/Kentbye_tech-SFDrupalCampVisualDebuggingWithTheVisualizeBacktraceModul178.mp3

KentBye

Original issue:
------------------------------------------------------------------------
Sunday, September 2, 2007 - 20:49 : jp.stacey
 Attachment:   http://drupal.org/files/issues/drupal_index_php.gif (59.71 KB)

As with http://drupal.org/node/165103 , need a place to put a workflow
diagram for discussion.

This is the behaviour of index.php made as schematic as possible,
delving into drupal_page_footer to bring out the cache+hook nature of
that function.

Any comments appreciated. Specifically, though: if
menu_execute_active_handler returns NULL, am I right in thinking a white
screen of death results? That's what the flow would suggest.

Previous comments (10):
------------------------------------------------------------------------
1. Monday, September 3, 2007 - 10:21 : jp.stacey

Need to add the require_once and theme elements to the legend.

------------------------------------------------------------------------
2. Monday, September 3, 2007 - 10:29 : sime

heya, looks great to me

------------------------------------------------------------------------
3. Monday, September 3, 2007 - 14:55 : sun

Looks great!

However, I'd suggest to negate the decisions for easier and faster
understanding, thus rename

* Not found? to Found?
* Access denied? to Access[ible]? or Access granted?
* Site offline? to Site online?
* Return not-null? to Return content?

which leads to a slightly different layout, of course.

------------------------------------------------------------------------
4. Tuesday, September 4, 2007 - 04:47 : beginner

That is useful, thanks.

In the diagram, there is drupal_set_cache(), but there is not
drupal_get_cache().
It is unclear where the content of the page is actually computed, and
where the content is drawn from cache.

------------------------------------------------------------------------
5. Tuesday, September 4, 2007 - 18:06 : KentBye

These are a great idea, and I've love to see more of them.
I've actually been working on something that could help create more of
this more quickly.

I've been working on creating dynamic function call visualizations that
use XDebug and a text-to-flowchart program called GraphViz.  Here's a
sample: http://flickr.com/photo_zoom.gne?id=1143104488&size=l  (view the
original size)

I've also hyperlinked the function calls to the CVS line numbers where
they were called, as well as linked to the API docs.
It's possible to view them in a SVG (e.g.
http://www.kentbye.com/files/drupal_bootstrap.svg )

But the problem is that the SVG is so big that it quickly becomes
difficult to view in a browser java applet called ZGRViewer.  However,
running ZGRViewer on the desktop works great and so it works for the
developer, and not as well for documentation purposes.

Anyway, some of this stuff that I'm doing may help people create
higher-level flowcharts like this one, and I'm getting pretty close to
releasing some of what I've got so far.

------------------------------------------------------------------------
6. Tuesday, September 4, 2007 - 23:12 : sime

KentBye

Awesome. So how big is big? Btw, perhaps you are a aware that Firefox
will view those SVGs natively?

Needless to say, having this in devel... well, if you ever do, please
link here so I can track. :)

------------------------------------------------------------------------
7. Wednesday, September 5, 2007 - 10:27 : jp.stacey

Thanks for all the comments!

@sun, the logic and the wording was done to try to match the
programming internals as closely as possible while making them
English-language. For example, the switch/case statement makes a
positive check for the "not-found" code, then serves up a 404 page on
request. But I see what you mean about it being a bit convoluted with
double negatives. I'll have a look at that.

@beginner, I've not found cache_get() on my travels yet. From KentBye's
diagram, menu_execute_active_handler calls it, but I think that would
make a good extra diagram in itself. I'll poke around in that function
and see what it's doing, and if any of it can be briefly abstracted up
to this level.

@KentBye, that's a beautiful diagram. I'll definitely be using it as a
starting point for these flow diagrams from now on.

------------------------------------------------------------------------
8. Wednesday, September 5, 2007 - 17:39 : KentBye

@jp.stacey -- Great.  Glad that it's helpful.  The thing about these
diagrams is that they only represent one path, where there are many
other possible forks and conditions that exist.  What would be good is
to give you the capability to create a wide range of graphs under
different conditions to be able to create these types of top-level
flowcharts.  

So this will give you the all of the trees, and then you can map out
the forest. :)

@sime -- How big is big?  Well, a pixel resolution of 221739 x 5728 & a
PNG size of over 16MB is a typical size.  And it explodes when the form
API is called.  So yes, both Safari & Firefox can view SVGs natively,
but at this size it becomes nearly impossible to really view it. 

The good news is that if there was an open source Google Maps type of
interface, then it would work great.  The other good news is that
javascript / jQuery can alter the relevant SVG parameters to do pans and
zooms, and so it's definitely possible to create this type of viewer.
But this will be left as an exercise to someone who can implement it
since the desktop-based ZGRViewer is a good workaround for now.

You can check out a photoset on Flickr where I uploaded a lot of
examples of flowcharts that were autogenerated by GraphViz here:
http://flickr.com/photos/kentbye/sets/72157601523153827/

That'll give you an idea of what's possible to create w/ this
text-to-flowchart program.

Unfortunately, GraphViz is Common Public License 1.0, which is not
really compatible w/ GPL and so there may be issues w/ autogenerating 
PNG & SVG files w/ Drupal. It is possible to do a command-line call,
which I understand may be more legal -- but IANAL.

Fortunately, ZGRViewer is a GPL'd app that is able to read and display
the *.dot syntax, and it works seemlessly as a desktop app launched from
the terminal. There is also a browser-based java applet w/ ZGRViewer
that reads a SVG, but it chokes when the SVG is too big.

So my first iteration of a Drupal module will read in and parse the
XDebug backtrace and autogenerate a GraphViz syntax *.dot file required
to create these flowchart graphs.  

For more info, you can see a set of links that I've aggregated here:
http://del.icio.us/kentbye/graphviz

Let me know if others are interested in this module since it'll help
accelerate the first iteration of it.

------------------------------------------------------------------------
9. Wednesday, September 5, 2007 - 23:08 : sime

Kentbye, I always thought that a being able to view part of the puzzle
would be cool, so if you want to look at one function, it would show you
the related calls. Then if you clicked on the caller or the callee, it
would shft your view, perhaps with some jquery callbacks. I only wish I
had more time to play with xdebug, I love your pics.

jp.stacey, for your chart, one thing that helped me was understanding
the clear distinction between generating the content related to the
current menu item, and then passing the $output into theme page. That
could be better represented in your chart.

------------------------------------------------------------------------
10. Thursday, September 6, 2007 - 01:22 : KentBye

@sime: It's totally possible to look at related calls with what I've got
set up.  The output SVGs [4] are searchable by function name (works
great in Safari), and you can also track specific stack trace paths by
searching by the function call number which is preceded by "f" to
distinguish it from the line numbers (ie. "f49", "f50" "f51").  The
ZGRViewer app that I use also supports searching.

And taking a step back, the function call flowchart that I linked to
before [5] only represents the first 303 function calls -- up to just
before the menu_get_active_item gets called.

A complete page request ranges anywhere from 3000-6000 function calls
depending on what's going on.  To visualize this, take a look at this
plot [6] which shows the different function depths (i.e. the level at
which they are nested) as the function numbers increase.  There are
clusters between drupal_bootstrap, menu_executive_active_handler,
menu_get_active_item, theme and drupal_footer -- the functions that all
happen to be included in index.php

NOTE: This was made with Drupal 5.2 and may look a bit different with
Drupal 6.0 since there have been a lot menu system changes.

[4] http://kentbye.com/files/drupal_bootstrap.svg
[5] http://flickr.com/photo_zoom.gne?id=1143104488&size=l
[6] http://flickr.com/photos/kentbye/1108244604/