| 6 module.inc | module_load_include($type, $module, $name = NULL) |
| 7 module.inc | module_load_include($type, $module, $name = NULL) |
| 8 module.inc | module_load_include($type, $module, $name = NULL) |
Load a module include file.
Examples:
<?php
// Load node.admin.inc from the node module.
module_load_include('inc', 'node', 'node.admin');
// Load content_types.inc from the node module.
module_load_include('inc', 'node', 'content_types');
?>Do not use this function to load an install file. Use module_load_install() instead.
Parameters
$type: The include file's type (file extension).
$module: The module to which the include file belongs.
$name: Optionally, specify the base file name (without the $type extension). If not set, $module is used.
File
- includes/
module.inc, line 280 - API for loading and interacting with Drupal modules.
Code
<?php
function module_load_include($type, $module, $name = NULL) {
if (empty($name)) {
$name = $module;
}
$file = './' . drupal_get_path('module', $module) . "/$name.$type";
if (is_file($file)) {
require_once $file;
}
else {
return FALSE;
}
}
?>
Comments
Sub-directory includes
When your included file is in a sub-directory, such as admin or includes, precede the $name parameter with the directory.
In the case of including my_module.include1.inc file within the includes directory in the my_module module:
<?phpmodule_load_include('inc', 'my_module', 'includes/my_module.include1');
?>
in case of wsod
If you have some WSOD, probably you have some function declared twice, activate: display_errors in php.ini, to see what's wrong or check the logs
Use === or !== test for successful include
This function returns '' (empty string) if the include is successful and a definite FALSE if not. You could also test against '' (!= ''). This is because the function has no real return value if it is successful.
You should definitely do any checks for files long before, but if something is mission critical (or if you add an external lib to your module directory), this might be useful to have.
<?php
// If successful, this will still be true
if (!module_load_include('inc', 'some_module', 'an_inc_file')) {
}
// Same as above
if (module_load_include('inc', 'some_module', 'an_inc_file') == FALSE) {
}
// Hacky way to test, this if successful
if (module_load_include('inc', 'some_module', 'an_inc_file') == '') {
}
// Successful include
if (module_load_include('inc', 'some_module', 'an_inc_file') !== FALSE) {
}
?>
It does not return a string at all
Hi Andy Udvare,
the function returns NULL when success, if there is no explicit return statement, it is always NULL.
<?php
NULL == ''; // true
NULL === ''; // false
?>
you can check for success using:
<?phpis_null( module_load_include(...) );
?>
regards,
Careful where you use
Worth noting, if you want to include data (e.g. a views object) in an include file, you cannot use this function - because the data will only be available within the scope of module_load_include() function, not within your own function that invoked it.
If you want to use module_load_include() for such a task, you need to wrap the object you need back in a function (which will be available beyond the scope of this function) with a return value of the data you need.
Otherwise you must require/include yourself and not use this function.
Not necessarily True
Yes, you do have to be careful were you place module_load_include() in your code. But you don't necessarily have to go out of your way to wrap it in functions. Proper placement can be more valuable than excessive function wrapping.
For example, I wanted an Events module I had written to tap into the Views 2 module. When I had written the module, I trusted that Drupal's table schema would use DateTime correctly, but it decided to save a String to the database, not the long integer Unix Epoch I had hoped for. This wasn't an issue until I had laid out my Views Data hook and realized the 'views_handler_field_date' only accepts the Unix timecode from the database and will NOT convert a string.
Luckily, there's a hook for that (Gotta love Drupal for its Hooks) and the smart cats who wrote Views were cool enough to let me tap that hook. So I copied the 'views_handler_field_date' handler and put a strtotime() function on the value and placed it in my module. I got a nice error telling me the 'views_handler_field' extension class couldn't be found.
This is where the module_load_include() came into play. But where to put it? I could stick it in the hook_views_handlers() function, but that would be a bit ambiguous and what if I need other handlers that won't be using this include; why load what isn't needed? Furthermore, would loading the include here allow my include to access it when it's actually being loaded by the Views module? After all, I'm just passing it along.
Solution: No functions, no crap like that. Just simplicity. I put module_load_include('inc', 'Views', 'handlers/view_handler_field'); on the line in my 'views_handler_field_date_string.inc' file (which is being passed through the hook to Views) just before the class definition. Just calling it straight forward and it worked like a charm. Drupal included the file right when I needed it and ignores it when I don't.
Furthermore, if Views isn't installed, the Hook is never called, so therefore, I never have to worry about including a 404. Even if I did, Drupal would keep plugging on and shoot me an error in the Watchdog.
include_once vs module_load_include
I was wondering if i must use this function instead of include_once always in Drupal.
Not an 'absolute' requirement
Hi johnnygamba,
You can use include_once if you like, but this is a more drupal-ish method. module_load_include appears to be a wrapper around the require_once php function. I'd use it if I were you, but if you know what you're doing, and include_once can work for you.
HTH.