This appendix is for all the things I promised in the rest of the book. It is a helper for commonly used reference materials, such as Drupal's API section, http://api.drupal.org—the best place to learn about the functions and classes available in Drupal. Remember, the Drupal core is always evolving and the calls might change from version to version. The Drupal API site will also show you the most recent version of all interfaces.
In Chapter 7, I talked about using Drupal's theme template engine to get control over the look of various parts of the content created by the Drupal database engine. The Drupal core ships with a number of templates. Each of these templates makes available certain variables, depending on the template.
Each of the variables ($styles, $site_name, $content, $search_box, etc.) must be generated in a module and made available as global variables so the Drupal's page-creation logic can render them. Table C-1 provides a list of variables for each template that ships with the Drupal 7 core.
Table C.1. Drupal 7 Core Templates
SimpleTest is the testing framework that is built into Drupal 7. Table C-2 shows some binary assertions. Table C-3 lists content assertions. Table C-4 shows SimpleTest navigation functions. Table C-5 shows request modifiers.
Table C.2. SimpleTest Binary Assertions
Assertion | Description |
|---|---|
| Fail if $x is false. |
| Fail if $x is true. |
| Fail if $x is set. |
| Fail if $x not set. |
| Fail if $x is not the class or type $t. |
| Fail if $x is of the class or type $t. |
| Fail if $x == $y is false. |
| Fail if $x == $y is true. |
| Fail if abs($x - $y) < $m is false. |
| Fail if abs($x - $y) < $m is true. |
| Fail if $x == $y is false or a type mismatch. |
| Fail if $x == $y is true and types match. |
| Fail unless $x and $y are the same variable. |
| Fail unless $x and $y are identical copies. |
| Fail unless the regex $p matches $x. |
| Fail if the regex $p matches $x. |
| Swallow any upcoming matching error. |
| Fail on failed expectation object $e. |
Table C.3. SimpleText Content Assertions
Description | |
|---|---|
| Pass if title is an exact match. |
| Pass if matches visible and "alt" text. |
| Pass if doesn't match visible and "alt" text. |
| A Perl pattern match against the page content. |
| A Perl pattern match to not find content. |
| Pass if a link with this text is present. |
| Pass if no link with this text is present. |
| Pass if a link with this id attribute is present. |
| Pass if no link with this id attribute is present. |
| Pass if an input tag with this name has this value. |
| Pass if an input tag with this id has this value. |
| Pass if HTTP response matches this list. |
| Pass if MIME type is in this list. |
| Pass if the current challenge is this protocol. |
| Pass if there is no current challenge. |
| Pass if the current challenge realm matches. |
| Pass if a header was fetched matching this value. |
| Pass if a header was not fetched. |
| Pass if there is currently a matching cookie. |
| Pass if there is currently no cookie of this name. |
Table C.4. SimpleTest Navigation Methods
Description | |
|---|---|
| Get the current location. |
| Send a GET request with these parameters. |
| Send a POST request with these parameters. |
| Send a HEAD request without replacing the page content. |
| Reload the last request. |
| Like the browser back button. |
| Like the browser forward button. |
| Retry after a challenge. |
| Restart the browser as if a new session. |
| Get the cookie value for the current context. |
| Age current cookies prior to a restart. |
| Go back to treating all frames as one page. |
| Click the first button with this label. |
| Click the button with this name attribute. |
| Click the button with this ID attribute. |
| Click an input tag of type image by title or alt text. |
| Click an input tag of type image by name. |
| Click an input tag of type image by ID attribute. |
| Submit a form without the submit value. |
| Click an anchor by the visible label text. |
| Click an anchor by the ID attribute. |
| Get the name of the currently selected frame. |
| Focus on a frame counting from 1. |
| Focus on a frame by name. |
Table C.5. SimpleTest Request Modifiers
Description | |
|---|---|
| Get the last socket error. |
| Dump the outgoing request. |
| Dump the incoming headers. |
| Dump the raw HTML page content. |
| Do not load framesets. |
| Set a cookie from now on. |
| Always add this header to the request. |
| Stop after this many redirects. |
| Kill the connection after this time between bytes. |
| Make requests via this proxy URL. |
In Chapter 10, I covered the Drupal installation process. Table C-6 lists hooks that are specific to the .install file.
Table C.6. Install Hooks
Hook | Description |
|---|---|
| Perform setup tasks when the module is installed. |
| Remove any information that the module sets. |
| Perform a single update. For each patch that requires a database change, add a new |
| Define the current version of the database schema. |
| Perform necessary actions after modules are installed. |
| Perform necessary actions after modules are uninstalled. |
Return an array of tasks to be performed by an installation profile. | |
| Alter the full list of installation tasks. |
| Check installation requirements and do status reporting. |
| Perform necessary actions after module is enabled. The hook is called every time the module is enabled. |
| Perform necessary actions before module is disabled. The hook is called every time the module is disabled. |
A Drupal schema definition is an array structure representing one or more tables and their related keys and indexes. A schema is defined by hook_schema(), which usually lives in a modulename.install file.
By implementing hook_schema() and specifying the tables your module declares, you can easily create and drop these tables on all supported database engines. You don't have to deal with the different SQL dialects for table creation and alteration of the supported database engines.
Drupal defines a number of structures for content management. The most ubiquitous is the node, which is the core container for content types. All Drupal-managed content extends from the node.
The field framework allows the user to create custom content types that extend the Drupal content even farther for specialized needs.
But there are other managed objects, such as users, blocks, and taxonomy terms, for which there are many functions to query, modify, and delete these objects.
These Drupal-managed objects are handy and create a powerful, extensible platform, but might be too cumbersome if you merely want to store away a small piece of data, or even a large set that would not necessarily be considered traditional Drupal content.
In other words, you might want to add tables to the Drupal database that you will manage in your modules and that the Drupal core doesn't really need to know or care about.
Creating database tables in a database-agnostic way is a bit tricky, but fortunately, Drupal's Schema API makes it possible. Instead of passing CREATE TABLE or ALTER TABLE queries directly to the database, we use a syntax that's consistent with other Drupal structures.
Drupal has a number of classes that can be used to access your schema information in a database-agnostic way. The classes are listed in Table C-7.
Table C.7. Schema API Classes
Description | |
|---|---|
| Implements |
| Throws exception if an object being modified doesn't exist yet. |
| Throws exception if an object being created already exists. |
DatabaseSchema_mysql DatabaseSchema_pgsql DatabaseSchema_sqlite DatabaseSchema_sqlsvr | Implements features specific to a particular database engine. |
If you will be creating custom schemas for your module, you'll probably create schemas using the schema hook in the .install file. In addition, there are a number of functions and methods that allow you to manipulate the schema in your code. These are listed in Table C-8.
Table C.8. Schema API Functions and Methods
Name | Description |
|---|---|
| Adds a new field to a table. |
| Adds an index. |
| Adds a primary key to a database table. |
| Adds a unique key. |
| Changes a field definition. |
| Creates a new table from a Drupal table definition. |
| Drops a field. |
| Drops an index. |
| Drops the primary key of a database table. |
Drops a table. | |
| Drops a unique key. |
| Checks if a column exists in the given table. |
| Returns an array of field names from an array of key/index column specifiers. |
| Sets the default value for a field. |
| Sets a field to have no default value. |
| Finds all tables that are like the specified base table name. |
| Checks if an index exists in the given table. |
| Renames a table. |
| Checks if a table exists. |
| Gets the schema definition of a table, or the whole database schema. |
| Returns the unprocessed and unaltered version of a module's schema. |
| Creates all tables in a module's |
| Retrieves a list of fields from a table schema. The list is suitable for use in a SQL query. |
| Removes all tables that a module defines in its |
| Saves a record to the database based upon the schema. |
| Defines the current version of the database schema. See next section. |
The best way to create schemas for your module is to create an array that defines all aspects of your data structures and use the schema hook in your .install file. I discuss this topic in Chapter 10.
The schema hook should return an array with a key for each table the module defines. The following keys are defined:
'description': A string in non-markup plain text describing this table and its purpose. References to other tables should be enclosed in curly-brackets. For example, thenode_revisionstable description field might contain "Stores per-revision title and body data for each {node}."'fields': An associative array ('fieldname' => specification) that describes the table's database columns. The specification is also an array. The following specification parameters are defined:'description': A string in non-markup plain text describing this field and its purpose. References to other tables should be enclosed in curly-brackets.'type': The generic data type:'char', 'varchar', 'text', 'blob', 'int', 'float', 'numeric', 'serial', 'date', 'datetime'or'time'. Most types just map to the corresponding database engine-specific data types. Use'serial'for auto-incrementing fields. This will expand to'INT auto_increment'on MySQL.'serialize': A Boolean indicating whether the field will be stored as a serialized string.'size': The data size:'tiny', 'small', 'medium', 'normal', 'big'. This is a hint about the largest value the field will store and determines which of the database engine-specific data types will be used (e.g., on MySQL,TINYINTvs.INTvs.BIGINT).'normal', the default, selects the base type (e.g., on MySQL,INT, VARCHAR, BLOB, etc.). Not all sizes are available for all data types. SeeDatabaseSchema::getFieldTypeMap()for possible combinations.'not null': If true, noNULLvalues will be allowed in this database column. Defaults tofalse.'default': The field's default value. The PHP type of the value matters:'', '0', and0are all different. If you specify'0'as the default value for a type'int'field it will not work because'0'is a string containing the character "zero", not an integer.'length': The maximal length of a type'char', 'varchar'or'text'field. Ignored for other field types.'unsigned': A Boolean indicating whether a type ('int', 'float', and'numeric'only) is signed or unsigned. Defaults toFALSE. Ignored for other field types.'precision', 'scale': For type'numeric'fields, indicates the precision (total number of significant digits) and scale (decimal digits right of the decimal point). Both values are mandatory. Ignored for other field types.
All parameters apart from
'type'are optional except that type'numeric'columns must specify'precision'and'scale'.'primary key': An array of one or more key column specifiers (see below) that form the primary key.'unique keys': An associative array of unique keys ('keyname' => specification). Each specification is an array of one or more key column specifiers (see below) that form a unique key on the table.'foreign keys': An associative array of relations ('my_relation' => specification). Each specification is an array containing the name of the referenced table ('table'), and an array of column mappings ('columns'). Column mappings are defined by key pairs ('source_column' => 'referenced_column').'indexes': An associative array of indexes ('indexname' => specification). Each specification is an array of one or more key column specifiers (see below) that form an index on the table.
A key column specifier is either a string naming a column or an array of two elements: column name and length, specifying a prefix of the named column.
The Drupal core uses certain global variables in the construction of a page. Global variables are discussed in Chapter 3. The globals used in the core are listed in Table C-9.
Table C.9. Drupal Core Global Variables
Name | Location | Description |
|---|---|---|
|
| The base path of the Drupal installation. This will at least default to '/'. |
|
| The root URL of the host, excluding the path. |
|
| An array of objects that represent the base theme. |
|
| The base URL of the Drupal installation. |
|
| An associative array containing title, link, description, and other keys. Links should be an absolute URL. |
|
| Site configuration values defined in the global settings file. |
|
| Array of persistent variables stored in 'variable' table. |
|
| The domain to be used for session cookies. For hosts such as 'localhost' or those that expos only an IP address, the cookie domain will not be set. |
| Array of database connections. | |
|
| Global variable that holds information about the tests being run. |
|
| Structured array describing the data to be rendered. |
|
| An array of forum topic header information. |
|
| Current image tag used by aggregator parsing. |
|
| The name of the profile that has just been installed. |
|
| General string or array. |
|
| Array of items used by aggregator. |
|
| An object containing the information for the active interface language. It represents the language the user interface textual elements such as titles, labels or messages, are to be displayed in. |
|
| An object containing the information for the active content language. It is used by the Field API as a default value when no language is specified to select the field translation to be displayed. |
|
| An object containing the information for the active URL language. It is used as a default value by URL-related functions such as |
|
| Boolean indicating that a menu administrator is running a menu access check. |
| The current multibyte mode. Possible values: | |
|
| Array of the number of items per page for each pager. The array index is the pager element index (0 by default). |
|
| Array of current page numbers for each pager. |
|
| Array of the total number of pages for each pager. The array index is the pager element index (0 by default). |
|
| Array of the total number of items for each pager. The array index is the pager element index (0 by default). |
|
| Active tag name. |
|
| Active theme name. |
|
| The theme engine related to the active theme. |
|
| Active theme object. |
|
| Name of the active theme. |
|
| The path to the active theme. |
|
| Timers that have been created by |
|
| Allows the |
|
| An object representing the currently logged-in user. Contains preferences and other user information. |
The Field CRUD API is for creating fields, bundles, and instances. Fields are covered in Chapter 9. Functions and methods are shown in Table C-10.
Table C.10. Field CRUD API Functions and Methods
Name | Description |
|---|---|
| Creates a field. |
| Creates an instance of a field, binding it to a bundle. |
| Marks a field and its instances and data for deletion. |
| Marks a field instance and its data for deletion. |
| Reads a single field record directly from the database. |
| Reads in fields that match an array of conditions. |
| Reads a single instance record directly from the database. |
| Reads in field instances that match an array of conditions. |
| Updates a field. |
| Updates an instance of a field. |
| Acts on a field being created. |
| Acts on a field instance being created. |
| Acts on a field being deleted. |
| Acts on a field instance being deleted. |
| Acts when a field record is being purged. |
| Acts when a field instance is being purged. |
| Acts on field records being read from the database. |
| Acts on a field record being read from the database. |
Removes field storage information when field data is purged. | |
| Removes field storage information when a field record is purged. |
| Removes field storage information when a field instance is purged. |
| Acts on a field being updated. |
| Forbids a field update. |
| Acts on a field instance being updated. |
| Stores an instance record in the field configuration database. |
The Field Attach API allows you to operate on Field API data that has been attached to Drupal entities. Fields are covered in Chapter 9. Functions and methods are listed in Table C-11.
Table C.11. Field Attach API Functions and Methods
Name | Description |
|---|---|
| Notifies |
| Deletes field data for an existing entity. This deletes all revisions of field data for the entity. |
| Notifies |
| Deletes field data for a single revision of an existing entity. The passed entity must have a revision id attribute. |
| Adds form elements for all fields for an entity to a form structure. |
| Performs field validation against form-submitted field values. |
| Saves field data for a new entity. |
| Loads fields for the current revisions of a group of entities. |
| Loads all fields for previous versions of a group of entities. |
| Prepares an entity for translation. |
| Prepares field data prior to display. |
| Populates the template variables with the field values available for rendering. |
| Performs necessary operations just before field data gets saved. |
| Notifies |
| Performs necessary operations on field data submitted by a form. |
Saves field data for an existing entity. | |
| Performs field validation against the field data in an entity. |
| Returns a renderable array for the fields on an entity. |
| Acts on |
| Acts on |
| Acts on |
| Acts on |
| Acts on |
| Acts on |
| Acts on |
Performs alterations on | |
| Alters |
| Acts on |
| Acts on |
| Acts on |
| Acts on |
| Acts on |
| Acts on |
| Performs alterations on |
| Alters |
| Performs alterations on |
| Invokes a field hook. |
| Invokes |
| Helpers for |
| Invokes a field hook across fields on multiple entities. |
| Invokes |
Drush, the Drupal shell, is a handy tool for performing certain tasks in Drupal from the command line. Installing and running Drush is covered in Appendix A. Table C-12 shows a list of core Drush commands.
Note that Drush is an extensible tool, so other modules and themes can add functionality to an installed version of Drush.
Table C.12. Drush Commands
Description | |
|---|---|
| Processes operations in the specified batch set. |
| Clears a specific cache, or all drupal caches. |
| Clears a specific cache, or all drupal caches. |
| Enters a new shell optimized for drush use. All |
| Displays README.txt. |
| Rsyncs the Drupal tree to or from another server using |
| Runs all |
| Returns the file system path for projects and themes and other key folders. Used by the |
| Disables one or more modules or themes. |
| Downloads core Drupal and contributed modules and themes. It will automatically figure out which project version you want based on its latest release, or you may specify a particular version. |
| Enables one or more modules or themes. |
| Evaluates arbitrary php code after bootstrapping Drupal. |
| Clones a field and all its instances. |
| Creates fields and instances. Returns URLs for field editing. |
| Deletes a field and its instances. |
| Views information about fields, field_types, and widgets. |
| Returns URL for field editing web page. |
| Prints this help message. See |
| Evaluates arbitrary php code after bootstrapping Drupal. |
Runs the given php script(s) after a full Drupal bootstrap. A useful alternative to | |
| Shows info for one or more projects. |
| Views all releases for a given project (modules, themes, profiles, translations). Useful for deciding which version to install or update. |
| Uninstalls one or more modules. Modules must be disabled first. |
| Notifies of pending db updates. |
| Refreshes update status information. |
| Prints site alias records for all known site aliases and local sites. |
| Indexes the remaining search items without wiping the index. |
| Forces the search index to be rebuilt. |
| Shows how many items remain to be indexed out of the total. |
| Installs Drupal along with modules, themes, and configuration using the specified install profile. Be careful with this command; it will drop your database and create a fresh one. |
| Shows a list of available modules and themes. |
| Prints database connection details using |
| A string for connecting to the DB. |
| Drop all tables in a given database. |
| Prints the whole database to |
| Copies source database to target database using |
| Opens a SQL command-line interface using Drupal's credentials. |
| Execute a query against the site database. |
Provides a birds-eye view of the current Drupal installation, if any. | |
| Provides a birds-eye view of the current Drupal installation, if any. |
| Shows a list of available modules and themes. |
| Executes a major version upgrade for Drupal core and enabled contributed modules. Command will download next version of Drupal and all available contributed modules that have releases (if not already downloaded). |
|
|
| Reads detailed documentation on a given topic. |
| Blocks the specified user(s). |
| Cancels a user account with the specified name. |
| Creates a user account with the specified name. |
| Displays information about a user identified by username, uid or e-mail address. |
| Displays a one-time login link for the given user account (defaults to uid 1). |
| Uninstalls one or more modules. |
| Displays available update information and allow updating of all installed projects to the specified version (or latest by default), followed by applying any database updates required (as with running |
| Displays available update information and allow updating of all installed project code to the specified version (or latest by default). |
| Performs update functions. |
| Executes the |
| Sets or resets the password for the user account with the specified name. |
| Adds a role to the specified user accounts. |
| Removes a role from the specified user accounts. |
Unblocks the specified user(s). | |
| Deletes a variable. |
| Gets a list of some or all site variables and values. |
| Sets a variable. |
| Deletes watchdog messages. |
| Shows available message types and severity levels. A prompt will ask for a choice to show watchdog messages. |
| Shows watchdog messages. |
Drush has a set of global options that work on most commands. See Table C-13.
Table C.13. Drush Global Options
Option | Description |
|---|---|
| Drupal root directory to use (default: current directory). |
| URI of the Drupal site to use (only needed in multisite environments). |
| Displays extra information about the command. |
| Displays even more information, including internal messages. |
| Hides all output. |
| Assumes "yes" as answer to all prompts. |
| Assumes "no" as answer to all prompts. |
| Simulates all relevant actions (doesn't actually change the system). |
| A list of paths to search for drush commands. |
| Specifies a config file to use. See |
| Specifies a user to login; may be a name or a number. |
| Hides all output and returns structured data (internal use only). |
| Emits a compact representation of the command for scripting. |
| Suppresses color highlighting on log messages. |
| Shows database passwords in commands that display connection information. |
| This help system. |
| The absolute path to your PHP interpreter, if not 'php' in the path. |
The Drupal core is a powerful framework for managing content and displaying it for visitors to your web site. The power derives from the rich set of functions and classes that comprise the Drupal API.
In this appendix, I have listed tables of common API functions that I use a lot. Still, the best place to find information about any part of the Drupal API is http://api.drupal.org.