Draft/RFC - Anatomy of Drupal for N00B

I've been looking at 5.5 for a few days; I came in without much
php or css familiarity, but enough unix/web background that there was
no major hair pulling getting it going on my linux test machine. In
the handbooks and howtos, I don't see anything like a "basic anatomy
of a drupal site."

I did find nancyw's dive-right-in guidebook, and the neemtree
tutorial about theming, and they were both helpful. However, neither
is the overview I would want as a starting point. Granted, it's
pretty much miraculous that a guy who's not familiar with CMS in the
first place can configure a working interactive site by clicking on
okay while eating popcorn, but...

What I think would be helpful is more like a correct, fleshed out
version of what's below. To that end, any corrections and any flesh
are welcome. Or pointers to documents that already exist with this
type of info. If I get suggestions in private mail or other
signs of interest, I'll post a followup. My email is
username 'spaceman' at this domain: 'futuretk.com' (I forgot that symbol
you usually put between the username and the domain...)

ta-da...

Basic anatomy of a Drupal site

Many users can put Drupal to work without having needing to know
the details presented here, but if you are going to be
installing the software yourself, or customizing it, it is helpful to
have a high level understanding of how the pieces of technology fit
together.

In case you didn't figure this out from looking at some example sites:
Drupal is a collection of programs written in php which creates
on-the-fly layout of content. The content is stored in a single
database. Druapl provides web forms which allow users to add and
categorize content. It also provides tools, usable through a web
browser (*1), to allow an administor to define content types.

[*1 it's not clear to me that it would be possible to add all the
directories needed without shell access, is it?]

A Drupal site consists of:

1. A well-defined directory structure and .css and template files that have
   specific names/name patterns which the code expects to find. The directories and
   initial files are created in installation. They files are customized for the site by
   an administrator using menus via a web browser. (That describes day-to-day use;
   sometimes you will probably edit files with a text editor and use the shell to set
   up/mess up this and that.)
   
2. A database of content, user information, and metadata (like timestamps and permissions).
   • The database is either
     mysql or postgres.
   
   
   • The database name and user name are not specified by drupal;
     they can be anything the database software allows. For one drupal site, there is exactly one database and
     exactly one database user.
   
   
   • the content can contain html markup
   
   
   
   
3. PHP code, which is mostly executed by calling /index.php with arguments, that:
   
   
   
   1. Visitor Facing:
      
      Pulls content from the database and inserts it into templates. The templates
      cosmetically format the content and provide navigational links and buttons.
      
   2. Author Facing:
      
      Creates forms from templates that allow users to add content
      
   3. Admin Facing:
      
      Creates forms from templates that allow priveleged users
      to configure the templates and control user rights.
4. An apache web server

There are several immediate corollaries:

• Apache must be configured to recognize "index.php" as a Directory Index (with
  <DirectoryIndex>)
• The server process must be able to read the directory and files
• As far as drupal is concerned, no one else needs access to the directories and files, they can all be set to be only viewable/writable by the server.
• The php processes must have the datbase's password; which in turn means
  you don't want the file where these are stored visible to any badboys.

Point three alluded /index.php. On a Drupal site, most http
requests for the site's content, and all http calls to andminister the
site, are calls to /index.php (*2) with arguments. To see a
blog entry, for example, you don't have a url like
"www.example.org/blogs/jenny/january2007/05/catpeedinmysangria.html";
instead, you have a URL like "www.example.org/node/115" or
"www.example.org/?=115". (*3) In either event, index.php gets called with the
argument node=115, and starts code which
eventually goes to the database, and finds content piece 115. Piece
115 will have the contents of Jenny's post, and also the metadata
which the php code can use to determine that it's a blog post. Knowing
the content type, the php code knows what templates and what css to
apply.

[*2 is that most/all language true?]

[*3 everything after this is just my speculation]

URLs of the form "www.example.org/node/115" are called "clean URLS",
and you can configure apache to rewrite them to the "/?=115" form. This
is perceived as more user friendly and may be important if you want
the contents of your site to be indexed by search engines. (see blah blah)

(This next is either too obvious to mention or it's wrong, but I
don't know which) If your site has non-drupal administered content,
simply install the content in a directory that drupal doesn't use
(i.e., put it in a directory sibling to /profiles, /scripts, etc., but
not named /misc, /includes, etc..) Than you can have the drupal pages
link to it by using regular URLs, The rewriting options will not
interfere with access to that material.

Mysql or postgres run as network services. Important For setting up
mysql, if the mysql server runs on the same machine as the apache
server, the host for the user must be defined as 'localhost' - the
wildcard, '%', does not match localhost. That is to say: if you have
user 'mike'@'%', when apache sets the php running, it will not be
able to login to a mysql database on the same machine using that user's
name. Not Important:
The UNIX/Windows permission of the mysql user are irrelevant, in fact, it's more
accurate to say that the mysql user doesn't correspond to any
particular *nix/Windows user, even if it happens to share a name; the mysql user that has access to the
database can be named anything that mysql allows.

Peace to you & all earthlings,
Tunamusic the spaceman from space.