Swap Textpattern CMS database on the fly

0.1.0 2013-05-06 09:35 UTC


Packagist | Twitter | Donate

Swap connected MySQL database on the fly. The plugin has the potential to allow pulling templates, articles and other content from different databases. Rah_swap adds a single neat Textpattern tag that can be used to change and bend connected database server link.


Using Composer:

$ composer.phar require rah/rah_swap


<txp:rah_swap db="myNewDatabase">
	...contained statement...

The plugin introduces a new tag, <txp:rah_swap/>. The tag can be used both as a container and as a single, self-closing tag.

When used as a container the database connection link is changed for just the wrapped code. The original link is restored on the closing tag pair.


Attributes for <txp:rah_swap> tag are as follows.

Database’s name. If db is the only attribute set, currently connected database is changed using current connection’s credentials (user, password, host). A new link isn’t created, but merely the database is swapped reusing the old connection.
Example: db="myDatabase" Default: ""

Username used to connect to the database.
Example: user="username" Default: ""

User’s password. Can be left empty if the user doesn’t have a password.
Example: pass="password" Default: ""

The database (MySQL) server. The host can contain a hostname, a port number or a path to a local socket. Defaults to localhost.
Example: host="hostname.tld:3306" Default: "localhost"

Database’s character set. Usually this attribute should not be used, but should be left as it is. Textpattern uses UTF-8, and using non-unicode character set can cause unexpected results.
Example: dbcharset="latin1" Default: "utf8"

Extra flags passed to the database client. Normally you shouldn’t worry about this attribute. Usually the attribute should not be used.
Example: client_flags="" Default: "0"

If set to 1, resets the original database connection the Textpattern installation uses. If the tag is used as a container, resetting is done automatically on the closing tag pair without the need of reset attribute. When rah_swap’s tags are used as self-closing single tags, use reset when you want to resume to Textpattern’s original database connection.
Example: reset="1" Default: "0"

Name of predefined database credentials stack. If the link attribute is defined, all other tag attributes are ignored. Instead of using the attributes, the credentials are pulled from a predefined config array stored in Textpattern’s configuration file.
Example: link="template_db" Default: ""

Using a separate configuration file

With the help of the tag’s link attribute, database connection credentials can be saved to Textpattern’s configuration file (i.e. /textpattern/config.php).

Defining the database’s connection credentials is done basically in the same way as Textpattern’s core database details are defined. Rah_swap expects a global variable named as $rah_swap, containing a multi-dimensional array. Example stack would look similar to following:

$rah_swap['db_link_name'] = array(
	'db' => 'MyDatabase',
	'user' => 'MyUsername',
	'pass' => 'MyPassword',
	'host' => 'localhost',

Where in above, db_link_name would be the name of the configuration stack and would be used as a rah_swap tag’s link attribute’s value.

<txp:rah_swap link="db_link_name" />

Multiple definitions can be set the same way. Same code, different stack name and connection details.

$rah_swap['templates'] = array(
	'db' => 'central_templates',
	'user' => 'user1',
	'pass' => 'pass1',
	'host' => 'localhost',

$rah_swap['promotional'] = array(
	'db' => 'promotional',
	'user' => 'user2',
	'pass' => 'pass2',
	'host' => 'localhost',

$rah_swap['address_book'] = array(
	'db' => 'client_network',
	'user' => 'user3',
	'pass' => 'pass3',
	'host' => 'localhost',

Connecting to those different databases then happens by using the tag’s link attribute.

<txp:rah_swap link="address_book" />

	Fetch something from the address book

<txp:article_custom />

	Fetch something from the template db

<txp:rah_swap link="templates" />

<txp:output_form form="cdn_template_banner_256x145" />

	Reset the default, original database connection

<txp:rah_swap reset="1" />

Features and rules that apply to the tag’s attributes, also apply to configuration stacks. For example, connected database can be switched while keeping the current user and connection. Just as with the tag, set only the database’s name.

$rah_swap['db_link_name'] = array(
	'db' => 'client_network',

Default values apply too. By default host will be set as localhost. If your host is localhost, you don’t have to define it.

$rah_swap['db_link_name'] = array(
	'db' => 'database',
	'user' => 'username',
	'pass' => 'password',


Simple usage example

The tags wrapped in the <txp:rah_swap> tags, will be pulled from database named as “promotional_content_db”.

<txp:rah_swap db="promotional_content_db">
		Content pulled from "promotional_content_db" database

	<txp:article_custom category="promo_2011_06">
		<txp:body />

In the example promotional_content_db would be a database used by second Textpattern installation. The installation would be used to host promotional content and campaigns redistributed to multiple sites.

Showing downloads from a second installation

<txp:rah_swap db="2ndSiteWithDLD">
			<txp:file_download_name />

Above serves file downloads from 2ndSiteWithDLD database using Textpattern’s file_download, file_download_link and file_download_name tags.

Toolshed notice

This is a toolshed project. Experimental and not part of the main supported product line of Rah. Not yet at least. Please use at your own risk.


Version 0.1.0 – 2013/05/06 – Download

  • Initial release.