Welcome! This book is meant to launch you into the world of programming with the open-source web content management system known as Drupal. Hopefully, with the aid of this book, you will pass smoothly through the stage of being a novice Drupal programmer, while avoiding making the mistakes that many expert Drupal programmers made in their first Drupal programming endeavors. If you make an effort to learn the "Drupal Way" of programming and follow the guidelines in this book, you can look forward to many enjoyable and fruitful years of programming with Drupal.

Intended Audience

This book was written primarily for people with a background in programming who are new to using and programming with Drupal. If you fit this profile, the main reason to read this book is that whatever your programming background, your experiences have taught you certain lessons—and only some of them apply well to Drupal. This book aims to make you aware of which lessons are which, and help you make a successful transition to being an expert Drupal programmer: someone who knows just how and where to apply your programming skills to have the greatest effect.

This book should also be useful for the following audiences:

  • Anyone working with Drupal who wants to understand how it works "under the hood."
  • Drupal site builders and themers who have realized they need to do some programming for customization, and want to do it "the Drupal way."
  • Drupal users who want to contribute to the Drupal open-source project by programming.

The backend of Drupal and most of its code is written in PHP, utilizing some variety of SQL for database queries. Accordingly, this book concentrates on PHP and database programming for Drupal, although there are definitely opportunities to program in Flash, JavaScript, and other frontend languages with Drupal.

Because this book was written for a programming audience, it assumes knowledge of the following:

  • The basics of the Web and HTTP requests.
  • The basics of PHP programming and programming in general (standard programming terminology is not explained).

See Where to Find More Information to find resources about these topics, if you need additional background.

How to Use This Book

In order to get the most out of this book, I would suggest that you start by reading Chapter 1 and making sure you are familiar with all the material in it. If you have never installed Drupal at all or tried to use it, you should definitely also do that now (there are installation instructions in the INSTALL.txt file that comes with Drupal, or at

After that, you should be ready to start looking at some Drupal programming examples, so I would suggest that you download the Examples for Developers project from, which is a comprehensive set of programming examples covering Drupal core (the base Drupal system, not including add-on modules). The Examples project is maintained by many contributors within the Drupal community, and it is an excellent resource; its existence has allowed this book to concentrate on the background information you will need to become a Drupal programming expert and on giving examples that are beyond the scope of the Examples project.

The next step I’d suggest would be to install one or two of the example modules from the Examples project, try them out, and then look through their code (check the README.txt file for installation instructions). If there’s a programming topic that you’re particularly interested in, you could choose an example module on that basis; I would particularly recommend the Block and Page example modules as good general starting points. Keep in mind when you are reviewing the code that the official Drupal API reference site,, is the best place to go to find documentation on particular Drupal API functions.

That should give you a little bit of experience looking at Drupal code, at which point I would suggest returning to this book and reading Chapter 2 and Chapter 3 carefully, to learn about the dos and don’ts of Drupal programming. At that point, you should have the necessary background for the special topics and examples of Chapter 4, and to return to the Examples for Developers project and look at examples there of interest; skim them so you know what’s there, and then come back to individual topics and examples when you need them.

Finally, Chapter 5 offers a few closing tips and suggestions, and many sections of this book have suggestions for further reading.

Drupal Versions

Every few years, the Drupal project releases a new major version of Drupal (Drupal 6, Drupal 7, and so on). Each major version of Drupal brings large, incompatible changes to the architecture and API, and generally, programming that you do for one major version cannot be used without modification in other major versions. Contributed modules (additional modules downloaded from also make large, incompatible architectural and API changes with their releases (Views 6.x-2.x versus 6.x-3.x, for instance).

The code samples in this book are compatible with Drupal 7, and with particular Drupal 7 versions of contributed modules as noted in their sections. The descriptive sections of this book are also written primarily with Drupal 7 in mind, with notes about changes expected in Drupal 8 (which was still in development as of this writing).

Where to Find More Information

Drupal Site Building and General Drupal Information

When I started using and programming with Drupal, there weren’t really any books available on using Drupal to build websites, so I don’t have any specific general Drupal book recommendations; the Drupal project maintains a list of current books about Drupal at

Here is a list of online resources on site building and the Drupal project in general:
The Drupal Community Documentation, a wiki-like compendium of pages about nearly everything in Drupal (installation, site building, programming, etc.). It has a lot of coverage, but since it is open to editing by all members of the Drupal community, it is of varying quality and only somewhat organized. Within this documentation, the "Developing for Drupal" section and the "Theming" section are of most use to programmers; other sections are aimed at setting up sites with Drupal, configuring modules, and the like.
Drupal Planet, which is an aggregated feed composed of many Drupal-related blogs. Subscribe to keep up-to-date on new developments in Drupal and to read blog posts on programming topics.
Central place to find topical and geographical Drupal groups, each of which has a forum. Many of them also have meetings and events (online or in-person) that you can attend.
The Drupal community uses IRC for online chatting, and this section of the Drupal website contains a channel list and background information.
Website of the Drupal Association, the nonprofit organization behind the Drupal project. and
Search for downloads of contributed Drupal modules and themes here.

Drupal Programming Reference and Background

The Drupal API changes often enough that if someone tried to write an API reference book, it would probably be outdated before it was published. So, the following online resources are recommended (in addition, some of the general Drupal resources of the previous section have programming information):
The API reference site for Drupal. As of this writing, this site only includes Drupal core and a few contributed modules; is a similar reference site that includes all of the Drupal contributed modules. Use one of these sites to find documentation about a specific Drupal function, class, or constant whose name you know. See Using for more information.
Tutorials and conceptual explanations for the various Drupal APIs. Use this reference if you do not know what function you need to use, or if you need more background information.
The Examples for Developers project, which is a set of well-documented example modules that aim to illustrate all of the core Drupal APIs. There has been some discussion about distributing these examples as part of the Drupal core download, but as of this writing, they are still a separate project.
Documentation about writing secure code in Drupal. Also, Greg James Knaddison, one of the prominent members of the Drupal Security Team, has written Cracking Drupal: A Drop in the Bucket (John Wiley and Sons), which is widely considered to be the definitive reference for Drupal security.
The coding standards for the Drupal project.
A list of tasks for people with a variety of skill sets, with step-by-step instructions, suitable for people who are new to contributing to the Drupal project.
Detailed instructions on how to contribute patches (code fixes) to Drupal.

PHP Resources

There are hundreds of books about PHP, and everyone should be able to find one that suits their needs, background, and style preferences. For an experienced programmer who is new to PHP, I recommend:

  • PHP in a Nutshell by Paul Hudson (O’Reilly) to learn the PHP language.
  • Web Database Applications with PHP and MySQL by Hugh E. Williams and David Lane (O’Reilly) to learn the basics of web applications with PHP, including security concerns and how all the pieces fit together.
  • For reference information about specific PHP functions, (that is always the most up-to-date reference; you can also download the entire reference for local or offline access).

Database Resources

Drupal can run on a variety of databases; most commonly, people use either MySQL, a MySQL clone such as MariaDB, or PostgreSQL. If you program with Drupal, you will need to use the Drupal Database API for maximum portability rather than writing MySQL or other database queries directly. Because of this, websites and references aimed at specific databases are of limited use to Drupal programmers. Instead, I recommend:

  • Web Database Applications with PHP and MySQL (previously mentioned) as a good starting point for learning the basics of queries useful for web programming.
  • SQL Pocket Guide by Jonathan Gennick (O’Reilly), which highlights the similarities and differences between the various databases' query syntax and capabilities.

Other Web Technology Resources

Again, Web Database Applications with PHP and MySQL is a good starting point for learning about how the web server, PHP scripting language, database, and browser interact in web applications in general. For reference on HTML, CSS, and JavaScript, I recommend:

Conventions Used in This Book

The following terminology conventions are used in this book:

  • While on some operating systems directories are called "folders," this book always refers to them as "directories."
  • Sample site URLs use "" as the base site URL.
  • Sample modules have machine name 'mymodule', and sample themes have machine name 'mytheme'.

The following typographical conventions are used in this book:

Indicates new terms, URLs, email addresses, filenames, and file extensions.
Constant width
Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.
Constant width bold
Shows commands or other text that should be typed literally by the user.
Constant width italic
Shows text that should be replaced with user-supplied values or by values determined by context.


This icon signifies a tip, suggestion, or general note.


This icon indicates a warning or caution.

Using Code Examples

This book is here to help you get your job done. In general, if this book includes code examples, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Programmer’s Guide to Drupal by Jennifer Hodgdon (O’Reilly). Copyright 2013 Poplar Productivityware, LLC., 978-1-449-34331-6.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at .

Safari® Books Online


Safari Books Online is an on-demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business.

Technology professionals, software developers, web designers, and business and creative professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training.

Safari Books Online offers a range of product mixes and pricing programs for organizations, government agencies, and individuals. Subscribers have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology, and dozens more. For more information about Safari Books Online, please visit us online.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

O’Reilly Media, Inc.
1005 Gravenstein Highway North
Sebastopol, CA 95472
800-998-9938 (in the United States or Canada)
707-829-0515 (international or local)
707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at

To comment or ask technical questions about this book, send email to .

For more information about our books, courses, conferences, and news, see our website at

Find us on Facebook:

Follow us on Twitter:

Watch us on YouTube:


Writing this book would not have been possible without the world-wide Drupal open-source project community, and I would especially like to acknowledge the support of the women of Drupal and the members of the Seattle and Spokane Drupal Groups. Without their help and encouragement, I would never have even gotten in touch with O’Reilly (thanks Angie!), much less decided to write this book. The daily cheerleading of my partner, Zach Carter, was also a great help in completing it. And all of the contributors to the Examples for Developers project made it possible for this book to concentrate on principles and pitfalls, without the need for it to include as many examples in its pages.

I would also like to thank Will Hartmann (PapaGrande), Michelle Williamson (micnap), Melissa Anderson (eliza411), Katherine Senzee (ksenzee), and Michael J. Ross (mjross) for providing technical reviews of this book.

And finally, I would like to thank my editor at O’Reilly, Meghan Blanchette, for many valuable suggestions, and for patiently guiding me through the publishing process.

Get Programmer's Guide to Drupal now with the O’Reilly learning platform.

O’Reilly members experience live online training, plus books, videos, and digital content from nearly 200 publishers.