Documentation

Before Installation

It is highly suggested to turn off all caching from your site for the installation process.

Make sure you follow all the instructions in the installation screen of the add-on. There are few things to worry about prior to installing this add-on:

  • All your domains should be actually set to point to your server from your DNS
  • Your server software (Apache) should be set to point all requests to these domains to be handled by your concrete5 instance

You can also do these steps after the installation if you wish so but in that case you should not expect the add-on to work properly, naturally.

Read more about server and DNS setup.

After Installation

If you get an internal server error after your installation in the mapped domains, it is most likely due to a misconfigured .htaccess file. Please see the internal server error section for more information on this matter.

Domain Specific Functionality and Built-in Overrides

When using Multiple Domains, your mapped domains work a bit differently than the core normally works. This is mostly due to the fact that the page path is overridden to generate cleaner URLs in your mapped domains.

For this reason, we need a few overrides to the core components and settings. The sections below describe these overrides more specifically.

Navigation Helper Override

As you use Multiple Domains to map the external domains to specific nodes in your sitemap, by default concrete5 will still display the full page links to those pages. To fix this, we provide a built-in override to take the mapped domain into account when writing the page paths.

This override will automatically fix all your site's links for you, no matter where they are and in which blocks you have defined them.

To apply this override, make sure the checkbox is checked under the "Settings" of Multiple Domains and the section "Enhanced Core Components" in that view.

By default, this override is already enabled in Multiple Domains.

Auto-Nav Block Override

The auto-nav block works by default based on the default structure of your sitemap (first level, second level, etc.). With Multiple Domains this might be a problem sometimes as you might want the "first level" to mean the actual first level under your mapped domain.

For this purpose, Multiple Domains comes with a built-in override for the Auto-Nav block. This takes care of this problem automatically and makes each domain's first level to be the actual first level under that domain and not the actual first level of the site.

The enhanced block also modifies the logic of the second and third level navigations, so these are also relative to the domain's home page when this override is enabled.

To apply this override, make sure the checkbox is checked under the "Settings" of Multiple Domains and the section "Enhanced Core Components" in that view.

By default, this override is already enabled in Multiple Domains.

Domain-specific Site Name

Multiple Domains provides you the possibility to set the site name specifically to each domain as you might have noticed from the "Domains" view. This means the site name visible for search engines (or other bots) and the name visible in the browser's tab.

This automates the process of hacking your site's titles in your themes and makes the site name to be domain specific automatically, without any effort from you.

To apply this override, make sure the "Site Name Override" checkbox is checked under the "Settings" of Multiple Domains and the section "General" in that view.

By default, this override is already enabled in Multiple Domains.

Domain-specific sitemap.xml

When you serve different domains from the same installation, you might quickly realize that the default sitemap.xml provided by core concrete5 does not work for you. This is because it contains the whole main level structure of your site.

Multiple Domains comes with a built-in override to deal with this problem. This takes care of your domain specific sitemap.xml files automatically providing only the structure that is meant to lie under that domain where the sitemap.xml is accessed from. This also takes the main domain into account, removing all the pages from there that are mapped to some domains.

To apply this override, delete your static sitemap.xml file from the root of your installation if you have one there. This route is registered by Multiple Domains and it serves it automatically based on the domain.

PageCache Library Override

The page cache in concrete5 works in a specific way according to the request paths visible after the domain part of the web page's address. Because of this it does not work properly by default with Multiple Domains since the page paths may conflict with each other under different domains. This is true especially for the home pages of your domains since they all share the same path.

Because this library is loaded very early in the bootstrapping process of concrete5, it cannot be overridden as easily as the other overrides provided by this package. But don't worry, overriding it is quite straight forward by following these steps:

  • Open up your /application/bootstrap/autoload.php file
  • Make the file's content look like the following example:
<?php defined('C5_EXECUTE') or die('Access Denied.');

// Add this for using the MapClassLoader:
use Symfony\Component\ClassLoader\MapClassLoader;

/**
 * ----------------------------------------------------------------------------
 * Load all composer autoload items.
 * ----------------------------------------------------------------------------
 */
if (!@include(DIR_BASE_CORE . '/' . DIRNAME_VENDOR . '/autoload.php')) {
    die('Third party libraries not installed. Make sure that composer has required libraries in the concrete/ directory.');
}

// Add this for overriding the PageCache library in the core:
$mapping = array(
    'Concrete\\Core\\Cache\\Page\\PageCache' => DIR_PACKAGES . '/multiple_domains/src/Core/Cache/Page/PageCache.php'
);
$loader = new MapClassLoader($mapping);
$loader->register();

If you have previously modified this file, make sure you also take your other changes into account when adding these changes to the file.

In addition, add the following lines to the end of your /application/bootstrap/app.php:

$em = ORM::entityManager('core');
$driver = $em->getConfiguration()->getMetadataDriverImpl();
$driver->addExcludePaths(array(
    DIR_BASE_CORE . '/' . DIRNAME_CLASSES . '/Cache/Page/PageCache.php'
));

Common issues

Here are some commonly noticed issues with Multiple Domains that you might face along the way. We will be also adding new points here as we hear from them.

Pretty URLs give me internal server error

When you enable Pretty URLs for the first time and experience an internal server error, this usually is not because of Multiple Domains itself but rather your server settings or .htaccess override settings.

The most common reason for this is that you're running a development/testing domain under relative path like: www.my-domain.com/testing 

And your mapped domains don't have the same relative path in them (i.e. /testing, you've mapped them to the main-level instead).

In this situation your .htaccess configuration contains this line:

RewriteBase /testing/

This means that all your re-writable requests should begin with /testing/ which might not apply to your mapped domains. To fix this problem, serve your main domain also from the root-level without the relative path (/testing/). Instead, you could use a testing subdomain if you are not willing to go live just yet like testing.my-domain.com.

After this, remember to update your RewriteBase in your .htaccess file:

RewriteBase /

Other possible solution would be to disable the RewriteBase setting by commenting that line out but this is not suggested since it cannot be guaranteed whether this affects some of the internal functionality of concrete5.

Impossible to access the site after changing the "Main Domain"

Always when you are changing the "Main Domain" setting of your site, you should be extremely careful that you do not mistype the URL or type an incorrect URL into this setting because this might mess up a couple of things with the internal working of Multiple Domains.

The first issue you might see is that you are constantly being redirected out of the domain you tried to put into the "main domain" setting. Second, this might also cause an endless redirection loop in some occasions.

To fix this, you need to touch your database because there is basically no other way to access your site when this happens. In order to update the "Main Domain" setting straight to your database, use a DB query similar to this one: 

UPDATE Config SET configValue = 'admin.yourdomain.com' WHERE configNamespace = 'multiple_domains' AND configGroup = 'system' AND configItem = 'main_domain';

If you still experience problems, it is suggested to disabled the "Redirect Unmapped Domains to Main Domain" so that you can access your site overall to further debug the situation. To do this, run this DB query in your database:

UPDATE Config SET configValue = '0' WHERE configNamespace = 'multiple_domains' AND configGroup = 'redirect' AND configItem = 'unmapped';

Site stopped working after installation or uninstallation

If you recently installed and uninstalled the add-on and all you see when you try to access your site is a blank screen or an error on top of the page, it is possible that something went wrong with the "Overrides Cache" flushing during the installation/uninstallation process.

If this happens, all you need to do is to remove the "Overrides Cache" file from your file system by hand. To do this, follow these steps:

  1. Open up /SITE_ROOT/files/cache folder
  2. Remove a file there named environment.cache

After this, your site should be working normally when you load it the next time.

If you had used the PageCache library override, please make sure that you have removed that from your autoload.php and app.php files.