====== PunBB 1.3 integration ======
Forum integration is very useful when you want to use the same database for your website as the forum one or if you want to execute some tasks that require the user to be a part of a certain usergroup. Below you will find some integration possibilities.

===== General =====

In order to use PunBB user authentication within your scripts or to have access to the logged in user's information you have to include common.php which can be found in the include/ folder. You have also to define the FORUM_ROOT global variable in your script. For example, if your website front page is located in /home/user/public_html/ and your forums are located in /home/user/public_html/forums/, your FORUM_ROOT should be './forums/'. It can be done like this:
<code php>
<?php

// Add these lines in the very top of your code
define('FORUM_ROOT', './forum/');
require FORUM_ROOT.'include/common.php';

?>
</code>

===== URL schemes =====
PunBB 1.3 natively supports URL rewriting, including SEF URLs.

How to enable URL rewriting:\\
  - Rename file ''.htaccess.dist'' in the root of your forum to ''.htaccess''.
  - Go to Administration => Settings (''/admin/settings.php?section=setup''), find ''URL Scheme'' section there.
  - Choose the URL scheme you like and save changes.

===== Database helpers =====
On ''include/common.php'' inclusion, the proper implementation of [[database layer]] class is being also included according to forum configuration.
An instance of this database layer named ''$forum_db'' is being created in global scope to provide [[database helpers]].

==== How to perform a query ====
  * Direct query. You can simply write an SQL-statement and execute it.
<code php> $result = $forum_db->query('SELECT * FROM topics WHERE id = 10');</code>
Be sure, that your SQL code is cross-compatible with all database engines supported by PunBB.
  * Using [[query builder]]. You may transparently build database queries. All the specific of database engines and database structure will automatically be taken in account. Example of usage (FIXME make it more informative):
<code php>$query = array(
   'SELECT'  => '*',
   'FROM'    => 'topics',
   'WHERE'   => 'id = 10'
);
$result = $forum_db->query_build($query);
</code>
See [[query builder]] page for details.
==== How to work with query results ====
For example, we have this query:
<code php>
  $query = array(
    'SELECT' => 't.id, t.poster, t.subject, t.posted',
    'FROM'   => 'topics AS t',
    'WHERE'  => 't.forum_id = 1'
  );
  $result = $forum_db->query_build($query) or error(__FILE__, __LINE__);
</code>
  * To know how many rows this query returns, use this:
<code php>
  $forum_db->num_rows($result);
</code>
  * To fetch the current row to associative array:
<code php>
  $data = $forum_db->fetch_assoc($result);
  //An example of getting topic_id
  $topic_id = $data['id'];
</code>
  * To fetch the current row to numeric array:
<code php>
  $data = $forum_db->fetch_row($result);
  //An example of getting topic_id
  $topic_id = $data[0];
</code>
  * To fetch only some values from the current row:
<code php>
  //This code will fetch only the topic id and the topic subject
  list($id,, $subject,) = $forum_db->fetch_row($result);
</code>
  * To process all rows in a set you can use this code:
<code php>
  while ($cur_row = $forum_db->fetch_assoc($result))
  {
    //Actions with $cur_row
  }
</code>

===== Template customization =====
==== How to include my file into *.tpl? ====
Use the ''forum_include "file.ext"'' substitute to include the file ''<FORUM_ROOT>/include/user/file.ext'':
<code php><!-- forum_include "file.ext" --></code>

===== Common tasks =====

==== Recent 10 posts ====
<code php>
<?php

header('Content-type: text/html; charset=utf-8');

define('RECENT_POSTS_SHOW_POST', true); // Set to false to show topic subject only
define('RECENT_POSTS_MAX_POST_LENGTH', 20); // Limit length of the post text displayed

if (!defined('FORUM_ROOT'))
	define('FORUM_ROOT', './');

require FORUM_ROOT.'include/common.php';

// Get 10 lastest posts
$query = array(
	'SELECT'	=> 'p.id, p.message, t.subject',
	'FROM'		=> 'posts AS p',
	'JOINS'		=> array(
		array(
			'LEFT JOIN'		=> 'topics AS t',
			'ON'			=> 'p.topic_id = t.id'
		)
	),
	'ORDER BY'	=> 'p.posted DESC',
	'LIMIT'		=> '0,10'
);

$result = $forum_db->query_build($query) or error(__FILE__, __LINE__);

$recent_posts = array();
while ($cur_post = $forum_db->fetch_assoc($result))
	$recent_posts[] = $cur_post;

// Print out posts
if (!empty($recent_posts))
{
	?>
	<ul>
	<?php
	foreach($recent_posts as $cur_post)
	{

		echo '<li><a href="', forum_link($forum_url['post'], $cur_post['id']), '">', $cur_post['subject'], '</a>';

		if (RECENT_POSTS_SHOW_POST)
		{
			if (utf8_strlen($cur_post['message']) > RECENT_POSTS_MAX_POST_LENGTH)
				$cur_post['message'] = utf8_substr($cur_post['message'], 0, RECENT_POSTS_MAX_POST_LENGTH).'…';

			echo '<br />', "\n", $cur_post['message'];
		}

		echo '</li>';
	}
	?>
	</ul>
	<?php
}

?>
</code>

==== Showing all topics ====
<code php>
<?php

header('Content-type: text/html; charset=utf-8');
 
if (!defined('FORUM_ROOT'))
	define('FORUM_ROOT', './');
 
require FORUM_ROOT.'include/common.php';

// Get all topics
$query = array(
	'SELECT'	=> 't.id, subject, t.last_post, forum_id',
	'FROM'		=> 'topics AS t',
	'JOINS'		=>	array(
		array(
			'INNER JOIN'	=>	'forums AS f',
			'ON'		=>	'f.id = t.forum_id'
		)
	),
	'ORDER BY'	=> 'last_post DESC',
);
 
$result = $forum_db->query_build($query) or error(__FILE__, __LINE__);

if (!$forum_user['is_guest'])
	$tracked_topics = get_tracked_topics();
	
?>
<ul>
<?php

while ($cur_topic = $forum_db->fetch_assoc($result))
{
	echo '<li>';

	if (!$forum_user['is_guest'] && $cur_topic['last_post'] > $forum_user['last_visit']
		&& (!isset($tracked_topics['topics'][$cur_topic['id']]) || $tracked_topics['topics'][$cur_topic['id']] < $cur_topic['last_post'])
		&& (!isset($tracked_topics['forums'][ $cur_topic['forum_id'] ]) || $tracked_topics['forums'][ $cur_topic['forum_id'] ] < $cur_topic['last_post']))
		echo '[unread]&nbsp;';
	else
		echo '[read]&nbsp;';
	echo '<a href="', forum_link($forum_url['topic'], $cur_topic['id']), '">', $cur_topic['subject'], '</a>';
	
	echo '</li>';
}

?>
</ul>
</code>

==== Showing active topics ====
<code php><?php

header('Content-type: text/html; charset=utf-8');

define('FORUM_ROOT', './');
require FORUM_ROOT.'include/common.php';

require FORUM_ROOT.'lang/'.$forum_user['language'].'/index.php';
require FORUM_ROOT.'lang/'.$forum_user['language'].'/forum.php';

$topics_count = 5;
$query_active_topics= array(
    'SELECT'    => 't.id AS tid, t.poster, t.subject, t.posted AS has_posted, t.last_post, t.last_post_id, t.num_replies, t.num_views, t.closed, t.sticky,
 t.forum_id, t.last_poster',
    'FROM'        => 'topics AS t',
    'JOINS'        => array(
        array(
            'INNER JOIN'    => 'forums AS f',
            'ON'            => 'f.id=t.forum_id'
        ),
        array(
            'LEFT JOIN'     => 'forum_perms AS fp',
            'ON'            => '(fp.forum_id=f.id AND fp.group_id='.$forum_user['g_id'].')'
        )
    ),
    'ORDER BY'    => 't.last_post DESC',
    'LIMIT' => $topics_count
);
$result_active = $forum_db->query_build($query_active_topics) or error(__FILE__, __LINE__);

if ($forum_db->num_rows($result_active) == 0) {

?>
    <div class="main-content main-message">
        <p>There is no message.</p>
    </div>
<?php
    
} else {
    require_once FORUM_ROOT.'lang/'.$forum_user['language'].'/forum.php';

?>    
    <div class="main-subhead">
            <p class="item-summary">
                <span>
                    <strong class="subject-title"><?php echo $lang_index['Topics']; ?></strong>
                    <strong class="info-replies"><?php echo $lang_forum['Replies']; ?></strong>
                    <strong class="info-views"><?php echo $lang_forum['Views']; ?></strong>
                    <strong class="info-lastpost"><?php echo $lang_index['last post']; ?></strong>
                </span>
            </p>                                                
        </div>
    <div class="main-content main-forum">                    
    <?php

        $item_num = 1;

        while ($cur_set = $forum_db->fetch_assoc($result_active))
        {
           // Start from scratch
            $item_subject = $item_body = $item_status = $item_nav = $item_title = array();
            $item_indicator = ''; 
            
            if (!$forum_user['is_guest'] && $forum_config['o_show_dot'] == '1' && $cur_set['has_posted'] > 0)
            {
                $item_title['posted'] = '<span class="posted-mark">'.$lang_forum['You posted indicator'].'</span>';
                $item_status['posted'] = 'posted';
            }

            $item_title['link'] = '<a href="'.forum_link($forum_url['post'], $cur_set['last_post_id']).'">'.forum_htmlencode($cur_set['subject']).'</a>';

            if (!empty($item_nav))
                $item_title['nav'] = '<span class="item-nav">'.sprintf($lang_forum['Topic navigation'], implode('&#160;&#160;', $item_nav)).'</span>';

            $item_body['subject']['title'] = '<h3 class="hn"><span class="item-num">'.forum_number_format(++$item_num).'</span> '.implode(' ', $item_title).'</h3> <em> by '.forum_htmlencode($cur_set['poster']).'</em>';
            if ($cur_set['sticky'] == '1')
            {
                $item_subject_status['sticky'] = $lang_forum['Sticky'];
                $item_status['sticky'] = 'sticky';
            }

            if ($cur_set['closed'] != '0')
            {
                $item_subject_status['closed'] = $lang_forum['Closed'];
                $item_status['closed'] = 'closed';
            }
            // Does this topic contain posts we haven't read? If so, tag it accordingly.
            if (!$forum_user['is_guest'] && $cur_set['last_post'] > $forum_user['last_visit'] && (!isset($tracked_topics['topics'][$cur_set['tid']]) || $tracked_topics['topics'][$cur_set['tid']] < $cur_set['last_post']) && (!isset($tracked_topics['forums'][$cur_set['forum_id']]) || $tracked_topics['forums'][$cur_set['forum_id']] < $cur_set['last_post']))
            {
                $item_status['new'] = 'new';
            }
            
            if (!empty($item_subject_status))
                $item_subject['status'] = '<span class="item-status">'.sprintf($lang_forum['Item status'], implode(' ', $item_subject_status)).'</span>';

            $item_body['subject']['desc'] = implode(' ', $item_subject);
            if (empty($item_status))
                $item_status['normal'] = 'normal';

            $item_style = (($item_num % 2 != 0) ? ' odd' : ' even').(($item_num == 1) ? ' main-first-item' : '').((!empty($item_status)) ? ' '.implode(' ', $item_status) : '');
            
            $item_body['info']['replies'] = '<li class="info-replies"><strong>'.forum_number_format($cur_set['num_replies']).'</strong> <span class="label">'.(($cur_set['num_replies'] == 1) ? $lang_forum['Reply'] : $lang_forum['Replies']).'</span></li>';
            $item_body['info']['views'] = '<li class="info-replies"><strong>'.forum_number_format($cur_set['num_views']).'</strong> <span class="label">'.(($cur_set['num_views'] == 1) ? $lang_forum['View'] : $lang_forum['Views']).'</span></li>';
            $item_body['info']['last_post'] = '<li class="info-lastpost"><span class="label">'.$lang_index['Last post'].'</span> <strong><a href="'.forum_link($forum_url['post'], $cur_set['last_post_id']).'">'.format_time($cur_set['last_post']).'</a></strong> <cite>'.sprintf($lang_index['Last poster'], forum_htmlencode($cur_set['last_poster'])).'</cite></li>';

            ?>
                <div class="main-item<?php echo $item_style ?>">
                    <span class="icon <?php echo implode(' ', $item_status) ?>"><!-- --></span>
                    <div class="item-subject">
                        <?php echo implode("\n\t\t\t\t", $item_body['subject'])."\n" ?>
                    </div>
                    <ul class="item-info">
                        <?php echo implode("\n\t\t\t\t", $item_body['info'])."\n" ?>
                    </ul>
              </div>
    <?php

       }

}
</code>

==== Login form outside the forum ====

<code php><?php

// Define the path to the forum root
define('FORUM_ROOT', './forum/');
require FORUM_ROOT.'include/common.php';

// Where will we go after login?
$forum_page['redirect_url'] = 'http://your_site.com/forum/';

$forum_page['form_action'] = forum_link($forum_url['login']);

$forum_page['hidden_fields'] = array(
	'form_sent'	=> '<input type="hidden" name="form_sent" value="1" />',
	'redirect_url'	=> '<input type="hidden" name="redirect_url" value="'.forum_htmlencode($forum_page['redirect_url']).'" />',
	'csrf_token'	=> '<input type="hidden" name="csrf_token" value="'.generate_form_token($forum_page['form_action']).'" />'
);

?>
<form method="post" action="<?php echo $forum_page['form_action'] ?>">
	<?php echo implode("\n\t\t", $forum_page['hidden_fields'])."\n" ?>

	Username:
	<input type="text" id="fld1" name="req_username" value="" />
	<br />

	Password:
	<input type="password" id="fld2" name="req_password" value="" />
	<br />

	<input type="checkbox" id="fld3" name="save_pass" value="1" />
	<label for="fld3">Log me in automatically each time I visit.</label>
	<br />

	<input type="submit" name="login" value="Login" />
</form>
</code>