Documentation

Before Installation

As of version 5.6.0.1 of concrete5, the Request class needs a manual override in order to make the request path override work. This means that before the installation of this add-on, make sure your web server process (running your site) can write to the root-level /libraries directory in your site's root path.

Also, you should note that some of the functionality might not work correctly if your main domain is running under a /relative_directory/ instead of your domain being just www.my-domain.com. Please see the internal server error section for more information on this matter.

After Installation

During the installation, Multiple Domains installation process should've created an override for the "request.php" file in your /libraries/-folder. If your sub-domains are not working after the installation, the most common reason for this is that writing the override has failed during the installation. To fix this, create the file by hand, so open up a new file named /libraries/request.php in your favourite text editor and add the following line in it:

<?php require_once DIR_PACKAGES . "/multiple_domains/" . DIRNAME_LIBRARIES . "/request.php";

Clear your site's cache after this new file is added. After this, Multiple Domains should be working as expected.

Hide the site name from pages

By default concrete5 writes the main site name in the document head's title field. It means that by default the tab title of the browser states e.g. "Site Name :: Page Name". If you want to disable the site name from the page title, you can do so easily from the site configuration that is already supported by concrete5.

If you want to do this, open /config/site.php and add this line there:

define('PAGE_TITLE_FORMAT', '%2$s');

Add a domain-specific <title> tag for the sites

If you follow the previous tip, you will lose the site name from the <title> of the site which means only the page names are printed out to the <title> tag.

It is also possible to have site-specific names for each site and <title> tags in the following format: Sub-Site Name :: Page Name. If you want to do this, you need to do a slight modification in your theme's header file, usually found in /themes/your_theme/elements/header.php.

In that file, you will see a line similar to this:

<?php Loader::element('header_required'); ?>

You should change that into this:

<?php 
  $siteName = SITE;
  if (class_exists('MultipleDomainsMapping')) {
    $map = MultipleDomainsMapping::getByCurrentDomain();
    if (!is_object($map)) {
      $map = MultipleDomainsMapping::getBySectionOfSite($c);
    }
    if (is_object($map)) {
      $siteName = $map->getMappedPage()->getAttribute('site_name');
    }
  }
  Loader::element('header_required', array('pageTitle' => sprintf('%1$s :: %2$s', $siteName, $c->getCollectionName())));
?>

In addition to this, you will also need to create a page-attribute with handle "site_name". Then, you should set this attribute for each of your mapped home pages.

Domain-specific Global Areas (or Stacks)

For more complex site setups, you might need to have domain-specific Global Areas on the mapped sites e.g. for navigations and such site-wide blocks. This can be achieved actually quite easily.

What you need to do is to prefix the global areas with the domain's technical ID number that is always unique for the domains. Normally, one of your Global Area might look like this:

<?php 
  $ga = new GlobalArea('Header Nav');
  $ga->display($c);
?>

First of all, you need to have this code very early in your theme code, e.g. in the theme's header.php file. This needs to be run before any of the Global Areas are shown on the page:

<?php 
  if (class_exists('MultipleDomainsMapping')) {
    $map = MultipleDomainsMapping::getByCurrentDomain();
    if (!is_object($map)) {
      $map = MultipleDomainsMapping::getBySectionOfSite($c);
    }
  }
  define('MD_GA_PREFIX', is_object($map) ? $map->getMappingID() . '-' : '');
?>

And then, you need to change the Global Area code into this:

<?php 
  $ga = new GlobalArea(MD_GA_PREFIX . 'Header Nav');
  $ga->display($c);
?>

Domain-specific tracking codes

You might need to add specific tracking codes for your domains that are using the same theme. This is also possible through a small code adjustment in the theme's code.

The first thing you should do is create a new file in your root-level /elements folder. This will help you use the same code for multiple themes as your sites might be using multiple themes.

So create this file and open up it in your favorite text editor:
/SITE_ROOT/elements/tracking.php

And then, place this code in that file:

<?php defined('C5_EXECUTE') or die("Access Denied.");
global $c;
$domain = isset($_SERVER['HTTP_HOST']) ? $_SERVER['HTTP_HOST'] : $_SERVER['SERVER_NAME'];
if (class_exists('MultipleDomainsMapping')) {
  $map = MultipleDomainsMapping::getByCurrentDomain();
  if (!is_object($map)) {
    $map = MultipleDomainsMapping::getBySectionOfSite($c);
  }
  if (is_object($map)) {
    $domain = $map->getDomain();
  }
}
$trackingDomain1 = <<<EOT

PLACE YOUR FIRST DOMAIN'S (www.domain1.com) TRACKING CODE HERE

EOT;

$trackingDomain2 = <<<EOT

PLACE YOUR SECOND DOMAIN'S (www.domain2.com) TRACKING CODE HERE

EOT;

if ($domain == 'www.domain1.com') {
  echo $trackingDomain1;
} else if ($domain == 'www.domain2.com') {
  echo $trackingDomain2;
}

Once this code is in place and saved, the only thing to do is to include it in your theme files. If you want to include the tracking codes in the footer of the site, place them in your theme's elements/footer.php file. And if you want them to appear in the header of the site, place them in the theme's elements/header.php file.

To include the element in the theme file, use the following code snippet:

<?php Loader::element('tracking') ?>

Multiple Domains Auto-Nav

"My mapped sites' navigation links show the whole page path!"

The multiple domains add-on is not parsing through your page source to update each and every link it finds because this would just be inefficient. This might happen e.g. if your page structure is like this:

  • Home
    • Mapped sites
      • Site 1
      • Site 2
        • Subpage

In this situation, if you had a top navigation under "site 2" using the default auto-nav block, the link would probably show "/mapped-sites/site-2/subpage" instead of "/subpage" like it should under the mapped domain.

To fix this, the add-on comes with a forked version of the Auto-nav block called "Multiple Domains Auto-Nav". Try switching to that one and clearing your cache to fix the problem.

Hard-coding the Multiple Domains Auto-Nav Block

Quite many themes hard-code the navigation block (Auto-Nav) straight into the theme files. If you would like to change these navigations into Multiple Domains Auto-Navs, you just need to change the block handle in these hard-coded block includes.

To do this, the first thing to do is to locate the place from the code where the navigation lies. You will need to find a line similar to this (although the $menu variable might be differently named):

<?php 
$menu = BlockType::getByHandle('autonav');
// ... some other code here
?>

This would need to be changed into this:

<?php 
$menu = BlockType::getByHandle('multiple_domains_autonav');
// ... some other code here
?>

While changing the "Auto-Nav" blocks might fix your site-specific links for the navigations, you might still have links within your site that contain the full page paths because they are generated with the concrete5's own navigation helper. These links might be for instance in your content blocks.

To fix this, you can override the navigation helper with a similar class to the Multiple Domain's alternative navigation helper. Always before doing any overrides, make sure that your "Overrides Cache" is disabled from the Dashboard of the site.

All you need to do is to add the overridden navigation helper file in your system. This file will be initially empty. So, add an empty file in your system in the following location:
/SITE_ROOT/helpers/navigation.php

And once that file is in place, paste this code into that file and save it:

<?php
defined('C5_EXECUTE') or die("Access Denied.");
class NavigationHelper extends Concrete5_Helper_Navigation {

  public function getLinkToCollection(&$cObj, $appendBaseURL = false, $ignoreUrlRewriting = false) {
    $url = parent::getLinkToCollection($cObj, $appendBaseURL, $ignoreUrlRewriting);
    Loader::model("mapping", "multiple_domains");
    $map = MultipleDomainsMapping::getByCurrentDomain();
    if (is_object($map) && is_object($p = $map->getMappedPage())) {
      if ($p->getCollectionID() > 0) {
// Replace the first occurrence of the sub-domain URL $url = preg_replace('#' . $p->getCollectionPath() . '#', "", $url, 1); } } $find = DISPATCHER_FILENAME . "/"; if (($pos = strpos($url, $find)) === strlen($url)-strlen($find)) { // Replace 'DIR_REL/index.php/' with 'DIR_REL/' $url = substr($url, 0, $pos); } return $url; } }

After this, all your internal links generated by concrete5 should be working properly.

Make full page caching work with Multiple Domains

In order to make full page caching work with Multiple Domains, you need to be running version 1.4 of the add-on or newer. In order to do this, you once again need to do a custom override in the system because this is actually a bug in the current core version why full page caching does not work when many pages share the same page path, such as your domain home pages. So, once a gain first thing to do is to ensure that "Overrides Cache" is disabled from the Dashboard.

After this, add this file into the system (initially empty):
/SITE_ROOT/libraries/page_cache/library.php

And then, put this content into that file:

<?php require_once DIR_PACKAGES . "/multiple_domains/" . DIRNAME_LIBRARIES . "/page_cache/library.php";

After this, full page caching should be working normally through any domain.

Domain-specific sitemap.xml

If you want to print out domain-specific sitemap.xml file for each of your domains, this is absolutely possible with the Multiple Domains add-on. This is done dynamically when someone requests a file named "sitemap.xml" at the root of the domain.

To enable this feature, there are two steps:

  1. Enable pretty URLs if you haven't yet done so
  2. Delete the static sitemap.xml file from the root of your concrete5 installation

Allowing top-level single pages, such as "cart" or "checkout" from the mapped domains

Multiple Domains allows you to serve specific pages from any of your domains, so if you have for instance a single page in the main-level of your sitemap, it is possible to allow that page to be accessed through one or many of your other domains. You can build e.g. your store in different url than the main domain but there's just few things to make sure before doing this:

  1. You should allow access to those pages "from all domains" so that they can also be accessed through your mapped domains
  2. Make sure your users will access these pages ONLY from the desired domain, if you allow the page to be viewed from multiple domains, these pages might get blacklisted by Google (especially if they contain a lot of content).

To allow any page from any domain, just edit that page's properties and enable the attribute named "Allow From All Domains".

Again, please note that in general you SHOULD NOT serve the same content from multiple domains. Google might even blacklist you if you do so. Either you should really consider how you do the linking throughout all the sites or build some custom logic that would redirect the users to the correct domains on each of these "special case" pages. This could also be done through .htaccess rewrite rules.

Allowing logging in or dashboard access from subdomains?

If you're about to allow logging in or dashboard access from the settings of this add-on, please take time to consider what you're doing. If you REALLY want to do this, please consider again. That said, if you still consider doing so, you WILL face some problems on the way. Mostly these problems are permission-level issues so you should be comfortable playing with concrete5 permission settings if you want to do so.

Please note that especially if you allow dashboard access from the subdomains, users accessing the dashboard from the additional domains will have the exactly same permissions that you have set for them in ALL DOMAINS. In short, this means: with the same username, they are able to access the dashboard from any of the domains mapped to your site. Under each of these domains, those users will have exactly the same permissions that they have been provided with. This means that you should spend some time with setting up the permissions correctly for each user before allowing the options.

Usually it is much safer to do all the changes to your site from the main domain only as the default configuration suggests.

Once again: your user's permissions are handled globally on your concrete5 installation. The users will have the exactly same permissions on all of your mapped domains. This add-on does not handle permission-level issues!

Please think twice before even considering to allow these options!

Domain setup: Setting up a DNS wildcard

If you need to map all the sub-domains for your domain, this is the correct DNS setup to do so: 

yourdomain.com.		IN A		123.123.123.123
*.yourdomain.com.	IN CNAME	yourdomain.com.

If you don't have straight access to modify the DNS configuration files on your name server and need to do this through a GUI, you can probably set the wildcard just by adding a CNAME record for *.yourdomain.com that will point to the main domain that you've already setup properly. This is supported by many of the DNS service providers but we cannot guarantee it will work with every service provider.

Server setup: Virtual Server configuration for Apache webserver

In Apache webserver, you can set virtual server configuration to allow several domains to access the same concrete5 installation on your server. This guide assumes you're under Debian Linux regarding the folder structure (and example commands) but the Apache configuration will work in any Apache installation, although the configuration files might be stored in different locations.

Assuming you have concrete5 installed in /home/user/public_html/, this is how you setup a virtual server to map multiple domains into that folder (and concrete5 installation):

  1. Login to your server with root-account (or sudo)
  2. Make a new file with the same filename as your main-level domain in /etc/apache/sites-available/
    • E.g.  /etc/apache/sites-available/yourdomain.com
  3. Write the configuration given below to that file
  4. Save that file and write "a2ensite yourdomain.com" with the filename you just created, i.e. replace "yourdomain.com" with your actual domain
  5. Restart the Apache server process with the command /etc/init.d/apache2 restart

The virtual server configuration you need to put into the Apache configuration file is something like this (just an example):

<VirtualHost *:80>
	ServerName yourdomain.com
	# *.yourdomain.com for all the sub-domains
	# separate additional addresses with space
	ServerAlias *.yourdomain.com www.other-domain.com www.third-domain.com
	ServerAdmin webmaster@service.com
	
	DocumentRoot /home/user/public_html/
</VirtualHost>

Common issues

Debugging Multiple Domains

There are already some good tips in this documentation for debugging the add-on. If your site is still not working properly after reading the whole documentation, we suggest that you would try to run our debugging tool.

You can download the debugging too from here »

This tool might give you some hint on what might be wrong with your installation. It is a quick way to find out the most common problems with this add-on.

The tool is packaged in the normal add-on format of concrete5. All you need to do is to unzip the package into your /SITE_ROOT/packages folder and then install the package through the dashboard of your site.

After installation, the tool can be found from Dashboard > Reports > Multiple Domains Debug.

Pretty URLs give me internal server error

When you enable Pretty URLs for the first time and experience an internal server error, this usually has nothing to do with 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're 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.

My main site has pages with the same paths than some of my sub-sites

If you have e.g. /about page on the very top of your sitemap and also have a page with the same path on one of your subsites, like /mapped-sites/site-1/about, you might be experiencing redirect loop when trying to access that page.

This happens because Multiple Domains is trying to redirect you automatically to the correct domain for this page path but it cannot decide which one is correct because these paths are exactly the same and therefore they conflict with each other.

There are two possible suggestions to fix this. These are both explained below.

Option 1: Disable this functionality with a settings change

The behavior explained above can be controlled through a config/site.php definition setting so if you want to disable this, add this to your config/site.php:

define('MULTIPLE_DOMAINS_FULL_PATHS_MAIN_DOMAIN_REDIRECT', false);

Option 2: Change your sitemap structure

Usually the best way to avoid this situation is not to have any conflicting page paths on your site. This means that on the top-level of your site, there should not be similar page paths than on any of your sub-sites.

This can be avoided by not having anything on the main-level of your site. You could even make your "main site" to be one mapped site in your site-tree and then have an own editing domain for accessing the dashboard, e.g. admin.yoursites.com.

The "Custom Attributes" tab gives a fatal error in the Page Properties dialog

If you see a fatal error on the page when you try to access the "Custom Attributes" tab of the "Page Properties" dialog, this might be caused by Multiple Domains if you recently installed it. This error appears because you are probably running an older version of PHP (5.2) that this add-on no longer support.

The error looks something like this:

Fatal error: Call to undefined method AttributeKeyCategory::getAttributeSetName() in /site_root/concrete/elements/collection_metadata_fields.php on line 42

As we clearly state in the main page of this add-on, you need to be running PHP 5.3 or higher in order to run this add-on on concrete5.6.2 or later. In order to fix this you either need to upgrade PHP on your server or change the PHP version as many service providers provide several versions of PHP on the same server. E.g. cPanel allows you quite easily to change the PHP version with the "PHP Version Manager" and some service providers allow changing the PHP version through your .htaccess file. You should contact your service provider for more details on this.

The official support for that version of PHP ended in the beginning of 2011 and we have also officially required at least PHP 5.3 for this add-on since concrete5.6.2 was released. Because of the end of life for PHP 5.2, it is also a wise decision security wise to upgrade your PHP version.

Saving page properties gets stuck in the "loading" phase

In some occasions, your "Page Properties" dialog might seem to get stuck in the saving phase when you click the "Save" button on the dialog. This is probably caused by a misconfiguration of Multiple Domains if it worked without problems before you installed Multiple Domains.

The configuration that might be incorrect is the "Main Domain" setting under the "Common Settings" of Multiple Domains. This needs to match your main domain so if you are currently browsing the dashboard through your main domain, make sure that this setting is equal to the address you see in your URL bar.

Why this happens is that if you have the "Redirect Unmapped Domains to Main Domain" setting enabled, the "Page Properties" saving action actually tries to redirect you back to the main domain because it identifies the page you are trying to request does not belong to your "unmapped domain". Therefore, this setting needs to be always correctly set in order for Multiple Domains to work properly.

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 on 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 cfValue = 'admin.yourdomain.com' WHERE cfKey = '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 cfValue = '0' WHERE cfKey = 'REDIRECT_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.

Upgrade notes

Upgrading concrete5 to 5.6.1 or above.
Before upgrading concrete5, please make sure you're running version 1.3 (or later) of the add on. If you already upgraded c5 and not the add-on, your site probably broke down.

If you managed to break the site, you'll need to do few things to fix the situation:

  • In your root-level /libraries/ folder you should see an override for a file named "request.php", rename that to "_request.php"
  • After that, you'll need to get your environments cache cleared if concrete5 managed to create that already after the core upgrade. Open up /files/cache folder and remove a file there named "environment.cache".
  • Now your site should be working normally without any Multiple Domains  features. If not, let us know through the support section and we'll guide you further.
  • After this, you can safely upgrade Multiple Domains to 1.3 or above (through dashboard or manual installation).
  • After the add-on upgrade, just rename the "_request.php" file back to "request.php".
  • Once this is done, once again, clear your environments cache (check step 2). After this, your site should be working normally with all the Multiple Domains goodies.

Upgrading from a pre-5.5 version of concrete5
In case you've upgraded your concrete5 installation from a pre-5.5 version to the latest version, your /config/site.php might contain some old settings that mess up the inner workings of Multiple Domains. If you're experiencing your sub-domains constantly redirecting you to the main domain eventhough everything else seems to be in order, the reason might be these old settings. So, if this is the case, please take a look at your /config/site.php configuration file and remove these lines from there if they exist:

define('BASE_URL', 'http://www.yoursite.com');
define('DIR_REL', '');

Older concrete5 versions used to need these but they are no longer needed in the more recent versions. Particularly, if the BASE_URL is specified, concrete5 will redirect you to that domain always if you're trying to request the site from some other URL. Naturally, this also affects the inner workings of Multiple Domains as it never has the chance to serve the correct content for the additional domains.