When I was new to MODX, I was often confused about where and how MODX got configuration information about the site. Clearly MODX knew where to find things, but I had a very vague notion of how it was done. In this article, we'll look at the process, and at the contents of the config files. We'll also take a look at the MODX constants and how to refer to file locations from various places in MODX.
The Basics
All the configuration information available for your site is contained in four files (five, if you count the one in the setup directory, which is usually removed). One is the master configuration file config.inc.php. All the other files do is tell MODX how to find the master config file. That master config file can be renamed, but it will always be found in the config/ directory just below the MODX core directory.
The other files are all named config.core.php. Their only job is to tell MODX where to find the master config file. The config.core.php files can't be renamed. They are located in the MODX root, connectors, manager, and setup/includes directories. Once MODX is installed the config.core.php files should all be the same and should contain correct information about where the core is and what the config file is named.
Here's an example of the config.core.php file contents from the MODX root directory of a localhost install:
<?php
define('MODX_CORE_PATH', 'C:/xampp/htdocs/mysite/core/');
define('MODX_CONFIG_KEY', 'config');
This file contains only two pieces of information. First, it has the path to the core directory: C:/xampp/htdocs/mysite/core/. In MODX Revolution 2, the core directory could be moved and renamed. In MODX Revolution 3, this is no longer possible. The second piece of information here (in the second line) tells MODX the name of the config file. In this case, it's the default: config.inc.php. If the second line looked like this:
define('MODX_CONFIG_KEY', 'myconfig');
MODX would know to look for a config file named myconfig.inc.php in the directory specified in the first line.
The Process
When MODX is launched, it looks at the config.core.php file in the MODX root directory. This file is the one that's used most often. The other config.core.php files contain the same information and are only there for convenience and the option to use simpler relative URLs in the other directories. Once the root config.core.php file has been read, MODX knows exactly where to find the master config file. It reads that master config file, and has no more use for the config.core.php file, since the master config file contains everything it needs to operate.
Setup
When you run setup, one of its jobs is to rewrite the various config.core.php files and the master config file (by default: config.inc.php). It uses the information provided in the forms of the setup process for this. It doesn't always get everything right, especially when you move a site to a new server. When you move a site, always run setup before trying to log in. It's also a good idea to delete all files in the core/cache directory. If the site still has problems, take a look at the config.core.php file in the MODX root to make sure that the location of the core and the name of the master config file are correct. If they are, look in the master config file itself and check all the paths and URLs. The MODX_CONNECTORS_PATH and MODX_CONNECTORS_URL are most likely to be incorrect.
<?php
if (!defined('MODX_CORE_PATH')) define('MODX_CORE_PATH', MODX_INSTALL_PATH . 'core/');
if (!defined('MODX_CONFIG_KEY')) define('MODX_CONFIG_KEY', 'config');
define ('MODX_SETUP_KEY', '@traditional@');
In the current traditional distribution of MODX, setup assumes that if the core path hasn't been defined, it will be called "core" and will be located in the MODX root. If this isn't correct, and the core can't be found in the that location, setup will ask you where the core is.
If you're using Friendly URLs (FURLs) in MODX, the rewrite rules in .htaccess will route requests through the index.php file in the MODX root directory. This only happens, however, if the file referenced in the URL is not found. By default, MODX stores the content of its web pages in the Database. When you enter a URL like mysite.com/home.html, your browser will look for that physical file. When it doesn't find it, the rewrite rules will launch index.php and MODX will build the page on the fly based on the information in the URL.
If, on the other hand, you actually have a file called home.html in the MODX root directory, it will be found. Your browser will display it, and MODX will never be involved in any way. I've helped new MODX users who were converting a site to MODX and tearing their hair out because none of the stuff they did in the MODX Manager had any effect. This happened because they still had an index.html file in the MODX root directory. MODX's index.php file never came into play, and MODX was never launched.
Because MODX routes everything through the index.php file in the MODX root directory, any paths or URLs in your HTML code need to be relative to the MODX root. This includes img, css, and js references in the code — more on this in a bit.
URLs versus Paths
I've been working with MODX for years, but this issue still bites me occasionally. If you are using include, include_once, require, or require_once to include a file in your PHP code, you want a file path, not a URL. The path needs to give the physical location of the file on the server. For images, CSS, and JS files, on the other hand, you want a URL, not a file path.
It's important to remember that if the reference is a URL, the location must be available by URL. That means it has to be in or under the web root of the site. The usual place for images, CSS, or JS files that need to be accessed via URL is somewhere under the assets/ directory. It's possible to use other directories for those files as long as web access to them is not denied, but putting them all under the assets/ directory can make them easier to find when you need to modify them. It also makes them easier to move in bulk (say, to a new server), and assures that they are accessible to a browser.
When hardening your site to make it secure, you will disallow web access to the core/ directory so you can't put images, CSS, or JS there. Some people store those files in the root directory to make them load a few milliseconds faster, but that also makes them easier to find for miscreants who want to slow down your site by requesting them over and over.
Troubleshooting
If your CSS or JS seems to be having no effect, clear the MODX cache. If that doesn't work, try adding &x=1324 to the end of the URL for the page. This will force the browser to ignore its cache. Use a different number each time.
If you're still not seeing your changes, in most browsers you can see the source code of a page by pressing Ctrl-u. You'll see the links to the CSS and JS files in the raw HTML. This will tell you where the browser is looking for those files. In most browsers, you can click on the link. If it's valid, you should see the code of the file itself on the screen. If you can't, the link is wrong.
Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.