README

Download | Packagist | Issues

Swap connected Textpattern CMS MySQL database link on the fly using a template tag. The plugin has the potential to allow pulling templates, articles and other content from different databases.

Install

Using Composer:

$ composer require rah/rah_swap

Or download an installer package.

Basics

<rah::swap db="myNewDatabase">
    ...contained statement...
</rah::swap>

The plugin introduces a new tag, <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

db
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: undefined

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

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

host
The database 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: undefined

dbcharset
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: undefined

client_flags
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: undefined

reset
A boolean attribute that when set, resets the database connection back to its original state. If the tag is used as a container, resetting is done automatically on the closing tag pair without the need of the 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 Default: undefined

link
Name of predefined database credentials config item. If the link attribute is defined, the used credentials are pulled from a pre-defined config array variable, $rah_swap, stored in Textpattern’s configuration file, config.php.
Example: link="template_db" Default: undefined

Configuration

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) instead of them being specified with the tag attributes.

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, allowing multiple links to be configured. Example config would look similar to following:

$rah_swap['link1'] = [
    'db' => 'MyDatabase1',
    'user' => 'MyUsername1',
    'pass' => 'MyPassword1',
    'host' => 'localhost',
];

$rah_swap['link2'] = [
    'db' => 'MyDatabase2',
    'user' => 'MyUsername2',
    'pass' => 'MyPassword2',
    'host' => 'localhost',
];

Where link1 and link2 would be the name of the link configurations and would be used as a rah_swap tag’s link attribute’s value.

<rah::swap link="link1" />
<rah::swap link="link2" />

Examples

Simple usage example

The contents wrapped in the <rah::swap> tags will be pulled from database named as promotional_content_db.

<rah::swap db="promotional_content_db">
    <txp:article_custom category="promo_2011_06">
        <txp:body/>
    </txp:article_custom>
</rah::swap>

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

<rah::swap db="downloads">
    <txp:file_download>
        <txp:file_download_link>
            <txp:file_download_name/>
        </txp:file_download_link>
    </txp:file_download>
</rah::swap>

Above serves file downloads from downloads database using Textpattern’s file tags.

As a self-closing tag

Templates are going to be fetched from templates database.

<rah::swap link="templates"/>
<txp:output_form form="header"/>
<txp:output_form form="cdn_template_banner_256x145"/>
<txp:output_form form="cdn_template_banner_256x145"/>
<rah::swap reset/>

The connection is reset back to normal using the reset attribute.

Changelog

Version 0.2.0 – 2022/04/17

Textpattern >= 4.7.0 and PHP >= 7.0 compatibility.
Now requires Textpattern >= 4.7.0.

Version 0.1.0 – 2013/05/06

Initial release.

rah / rah_swap

Maintainers

Details